Template development guide

uBlog renders every HTML page with one Mustache entry template, index.template, plus partials it includes. Request handlers do not choose a template per page. They fill a context with flags and data, and index.template decides what to show.

How a request becomes HTML

1. RequestHandlerService asks each AbstractRequestHandler in order whether matches(path). The first match wins. ContentHandler matches everything and is last.
2. AbstractRequestHandler.handleRequest creates a fresh MustacheBlogContext. It looks up the session from the session cookie and sets LOGGED_IN, plus USERNAME if logged in.
3. The concrete handler calls setters on the context (see the table below).
4. createHttpResponseFromContext renders index.template with the context map via MustacheTemplateService. The key/value pairs of theme.properties are merged into the same map and override context keys of the same name.
5. Client errors (createClientError) render index.template with a fresh context. That context shows the Error.md content, HAS_ERROR_MESSAGE=true, and the user is not logged in. Templates must therefore render error messages on every page, not only on forms.

Template folder: MUSTACHE_TEMPLATES_FOLDER (template/personal or template/plain in this repo; ./run.sh points at the former). Partials are included with {{>name.template}}. Mustache escapes {{x}}. Use {{{DATA}}} for pre-rendered HTML.

Files a template folder must provide

Only index.template is requested by name. The other file names are conventions used by the bundled templates, so a new template may structure partials differently.

Pages and URLs

Rules for every protected URL: not logged in returns 403 rendered as the error page. A wrong or missing csrfToken also returns 403. A wrong method returns 405 with an Allow header. Every form that changes state must submit csrfToken from {{CSRF_TOKEN}}.

Page flow

stateDiagram-v2
    [*] --> Index: GET /
    Index --> Login: GET /login
    Login --> Index: POST /loginaction
    Index --> TopicListing: GET /{topic}
    TopicListing --> EntryView: GET /{topic}/{entry}
    Index --> EntryView: GET /{rootEntry}
    EntryView --> EditEntry: GET /editentry/... (logged in)
    EditEntry --> EditEntry: POST/PUT /editentry/... (message)
    EntryView --> TopicListing: POST /deleteentry/... (303)
    TopicListing --> CreateEntry: GET /createentry/{topic}
    CreateEntry --> CreateEntry: POST /createentry (message)
    Index --> CreateTopic: GET /createtopic
    CreateTopic --> CreateTopic: POST /createtopic (message)
    Index --> UserDetails: GET /user
    UserDetails --> UserDetails: POST /passwordchange or /templateproperties
    UserDetails --> Index: POST /logout

Form submissions that fail validation re-render the same page with a message, not a redirect. A successful create or edit also re-renders the same form with a success message. Only delete redirects.

Context variables

All keys are defined in MustacheBlogContext. Booleans are only present when set. Mustache treats a missing key as false, so {{#IS_X}} and {{^IS_X}} both work.

Always present

Session

Page selectors

Exactly one of these normally selects the main content in index.template. IS_INDEX and IS_ENTRY_VIEW also control extra UI such as edit and delete links.

Page data

Messages

Wrap each message in its HAS_* section. The bundled templates repeat the three message blocks in each form partial. Consider a shared messages.template in a new theme.

Theme variables

Every key in theme.properties becomes a top-level variable (for example {{INDEX_TITLE}}). If the file exists, the publisher can edit the values on /user. Only existing keys can be edited, so declare every setting your template uses in the file.

Building a new template from scratch

1. Copy template/plain to template/mytheme. Run with MUSTACHE_TEMPLATES_FOLDER=template/mytheme (or ./run.sh, see its --help).
2. In index.template, include html_start.template and navbar.template, then render {{{DATA}}}, then one section per page selector from the table above. Include html_end.template last.
3. Always render the three message blocks outside the form partials too, because client errors use them on the Index/Error page.
4. In the navbar render TOPICS, QUICK_LINKS, and the login or logout controls. Logout must be a POST form to /logout. Login links to /login.
5. Build forms per the URL table. Use the exact field names, enctype="multipart/form-data" for create and edit entry, and include the csrfToken hidden field.
6. Build entry URLs with IS_ROOT_ENTRY so that root entries use /{entry} and topic entries use /{topic}/{entry}.
7. Optionally add theme.properties for publisher-editable text, colors or image URLs.
8. Set MUSTACHE_TEMPLATES_CACHING_ENABLED=false while developing, so edits show on reload. Restart if theme.properties changes outside of /user, because it is loaded at startup.
9. Check these states by hand: logged out and logged in, an unknown URL, a topic with and without entries, a failed login, a failed create (draft kept), and the profile page.

Extending the context

Adding a variable needs three changes:

1. A key constant and setter in BlogContext and MustacheBlogContext (src/main/java/info/gabrielszabo/ublog/service/template/mustache/).
2. A call from the relevant handler in src/main/java/info/gabrielszabo/ublog/service/requestHandlers/.
3. Use in every template that should display it.

A new page needs a handler registered in RequestHandlerService, placed before ContentHandler, a page selector flag, and a section in index.template.