A Website For Yancy

by Doug Bell
(he, him, his)
@preaction
preaction

preaction.me/mojo
CC-BY-SA 4.0

For navigation help, press ?
For speaker view and notes, press S
For full-screen, press F

A Website For Yancy

Project Intro
Links
Documentation
Static Site

No Static Site Generator

A Yancy Markdown Site

Mojolicious
Yancy
(Bootstrap)
Mojo::SQLite

`myapp.pl`

#!/usr/bin/env perl
use Mojolicious::Lite;

Database Schema

`db` Helper

#!/usr/bin/env perl
use Mojolicious::Lite;
use Mojo::SQLite;
helper db => sub {
    state $db = Mojo::SQLite->new( 'sqlite:docs.db' );
    return $db;
};

Schema Migrations

app->db->migrations->from_string( <<ENDSQL );
-- 1 up
CREATE TABLE pages (
    path VARCHAR PRIMARY KEY,
    markdown TEXT,
    html TEXT
);
ENDSQL
app->db->auto_migrate(1);

Configure Yancy

plugin 'Yancy', {
    backend => { Sqlite => app->db },
    read_schema => 1,
    schema => {
        pages => {
            properties => {
                markdown => {
                    format => 'markdown',
                    'x-html-field' => 'html',
                },
            },
        },
    },
};

With my database schema ready, I can configure Yancy. Yancy will provide the UI for me to update my content. For the most part Yancy can configure itself from my schema, but I have to give it a database connection to use and tell it to read my schema. I can also add some annotations to make the editor easier to use!

I add Yancy like any other Mojolicious plugin, using the `plugin` function. I tell it to use the `Sqlite` backend, and give it my database connection by calling my `db` helper. Then I tell it to read my schema from the database.

I need to do one more thing to configure Yancy: I need to tell Yancy how to take my Markdown and where to put the HTML. Yancy calls tables "schemas", and uses JSON schema to configure them. Since most of the schema was configured with `read_schema`, I only need to configure the "markdown" column to say it should be formatted as "markdown" and that the HTML should be stored in the "html" column.

Routes

get '/*id' => ...;

Last, I need a way to display my pages. To display content, I need to create a route. Specifically I want a get route. I want the route to find any page I create in the database, so I use '/*id' as the path. The '/' matches the leading slash, and the *id matches the rest of the path, including slashes, and puts it in the "id" stash variable. More on that later.

Destination

get '/*id' => 'index';

get '/*id' => sub {
    my ( $c ) = @_;
    $c->render( text => 'Hello' );
};

Controller

get '/*id' => sub {
    my ( $c ) = @_;
    $c->render( text => 'Hello' );
};

package MyApp::Controller::MyController;
use Mojo::Base 'Mojolicious::Controller';
sub hello {
    my ( $c ) = @_;
    $c->render( text => 'Hello' );
}

get '/*id' => {
    controller => 'MyController',
    action => 'hello',
};

get '/*id' => 'MyController#hello';

Yancy Controller

get '/*id' => {
    controller => 'yancy', # Yancy::Controller::Yancy
    action => 'get',
    schema => 'pages',
    template => 'pages',
    id => 'index', # Default to index page
};

So, for my route, I'll use the yancy controller, and the get action (which is the name of a subroutine in the Yancy::Controller::Yancy module). The get action will display a single item from the database based on the "id" stash variable, which we have in our route path. The controller needs to know what schema to use, and I need to give it the name of a template (which I'll create next). Last, I want to specify a default ID of "index" so that if no path is given, the user sees my index page. So, with this route, a user can go to any path on our site, and the application will fetch that page from the database and display it with the "pages" template.

Finish the App

app->start;

Now I need to write the template, but first I need to finish the code. The last line of every Mojolicious::Lite app needs to be app->start. That starts the application.

Template

__DATA__
@@ pages.html.ep
%== $item->{html}

<%== $item->{html} %>

<% my $html = $item->{html} %>
<%== $html %>

% if ( $item->{html} ) {
    %== $item->{html}
% }

% if ( $item->{html} ) {
    <h1><%= $item->{path} %></h1>
    %== $item->{html}
% }

Try it out!

$ perl myapp.pl daemon
[Wed Jan 23 23:24:28 2019] [info] Listening at "http://*:3000"
Server available at http://127.0.0.1:3000

Yancy Editor

Up Next

Documentation
Style
Deploy

PODViewer

Mojolicious::Plugin::PODViewer

Add Plugin

plugin 'PODViewer', {
    default_module => 'Yancy',
    allow_modules => [qw(
        Yancy Mojolicious::Plugin::Yancy
    )],
};

By default, the PODViewer plugin takes the path /perldoc, so let's take a look. Holy ugly. Alright. Well, that brings us to our next issue: Making the site look nice.

Style

Bootstrap Layout
Navigation Bar
Code Style

Layouts

`default` Layout

__DATA__
@@ layouts/default.html.ep

Like the pages template, I can add my layout template to the DATA section. Layout templates are in the layouts directory, so my file name is layouts/default.html.ep (the extension is the same). This is the biggest part of the entire application. Unfortunately, I don't have the time to introduce Bootstrap and discuss how its responsive navbars work, but I will point out a few key things about how to make layout templates.

Building a Layout

__DATA__
@@ layouts/default.html.ep
<!DOCTYPE html>
<html>
    <head>
        <title><%= title %></title>
        %= stylesheet "/yancy/bootstrap.css"

1. The layout template surrounds the content, so this is where you can put the DOCTYPE, the tag, the tag, and so on. 2. It's a template, so we can use template directives. The best practice is to use the title helper here so that our page can control the title. 3. Always use the stylesheet and javascript helpers. These helpers (to me) read better, but when you pass paths/URLs into them they will get fixed if you're behind a reverse proxy that lives at a different path. Not a common scenario, but a difficult one to diagnose.

Building a Layout

<main class="container">
    <%= content %>
</main>

4. The main page content is added to the layout by the content helper. This is the most important part of the layout.

Content Sections

@@ pages.html.ep
% content_for 'head' => begin
    %= javascript 'vue.js'
% end

@@ layouts/default.html
<head>
    %= content 'head'
</head>
<body>
    %= content
</body>

5. If you want to have additional places where the page can add content to the layout, use the % content_for $name, '...' helper in your page template, and the content helper in the layout, passing in the same name (%= content $name)

Code Style

pre {
    border: 1px solid #ccc;
    border-radius: 5px;
    background: #f6f6f6;
    padding: 0.6em;
}
.crumbs .more {
    font-size: small;
}

Use the Layout

plugin 'PODViewer', {
    layout => 'default',
};
get '/*id' => {
    layout => 'default',
};

app->defaults({ layout => 'default' });

Once I create the layout template, I need to tell the PODViewer plugin to use it, and my route to use it. I can add layout => 'default' in both places, or I can set the default layout for all pages everywhere using app->defaults({ layout => 'default' }).

Static Export

Rewrite redirects
Prefix /yancy

To upload my site, first I need to write it as HTML. There are a lot of ways to do this, but I have some specific needs: 1. Any links to redirects my site might make need to be rewritten as links to the redirect's destination 2. Since I will be deploying this to http://preaction.me/yancy, All of the internal links in my site need to have /yancy prepended This is a bit more than wget --mirror can handle, but Mojolicious includes an amazing DOM library which can make quick work of a problem like this. And, as luck would have it, someone (me) already did that work to create the export Mojolicious command.

`export` Command

Mojolicious::Command::export

To use this, I just install the "Mojolicious::Command::export" module from CPAN. Now in addition to the daemon command I used before to run my webapp, I have an export command that will export my site as static HTML files

Run an Export

$ perl myapp.pl export \
    --base /yancy \
    --to ./deploy

Deploy

# [r]ecursive, [v]erbose, [z]ipped, [m]odified dates
# --delete files from destination not in source
rsync -rvzm --delete ./deploy/. \
    preaction.me:/var/www/yancy/.

And now to deploy it, I can use whatever I want: FTP, SCP, Rsync. I wrote a very small shell script which uses this rsync command to do it:

Questions?

Postscript

Static Site Generator

Yancy::Backend::Static

---
title: Yancy
---
# Yancy

Yancy is a simple Content Management System written for
[the Mojolicious web framework](http://mojolicious.org).

plugin Yancy => {
    backend => 'static:' . app->home,
    read_schema => 1,
};

A Website For Yancy

A Website For Yancy

No Static Site Generator

A Yancy Markdown Site

myapp.pl

Database Schema

db Helper

Schema Migrations

Configure Yancy

Routes

Destination

Controller

Yancy Controller

Finish the App

Template

Try it out!

Yancy Editor

Up Next

PODViewer

Add Plugin

Style

Layouts

default Layout

Building a Layout

Building a Layout

Content Sections

Code Style

Use the Layout

Static Export

export Command

Run an Export

Deploy

Questions?

Postscript

Static Site Generator

Yancy::Backend::Static

Thank You

`myapp.pl`

`db` Helper

`default` Layout

`export` Command