template

From IndieWeb

This article is a stub. You can help the IndieWeb wiki by expanding it.


A template is a file used to generate a page. Templates typically have codes, instructions, or special tags that are used by a publishing tool to fill in content. The result is then returned as a page, or sometimes constructed clientside.

Open Source Examples

WordPress

WordPress (the software) has templates which can be used to customize the look and feel of various pages on your WordPress blog.

WordPress Template Issues

WordPress splits markup responsibility between their "core" code (in functions like body_class post_class) and templates, thereby making it difficult / fragile for template authors to control the markup of the page — they're restricted by the hardcoded markup output by WordPress core.

This poses real world problems, e.g. updating WordPress blogs to use h-feed and h-entry instead of class microformats hfeed hentry

Based on this real world experience, when designing your own template system, empower it with the full ability to change the markup of any pages, and do not hard code any markup in your core CMS code.

ProcessWire

ProcessWire template documentation: http://processwire.com/api/templates/

The ProcessWire template system associates a set of fields with the template and the page creation interface reflects that. For example, a template named "blog" might have fields: title, body, author, and date_published. When adding a page, you first select the template "blog" and the subsequent form would only contain those fields.

In the associated PHP file for the template, the fields would be available as $page->title, $page->body, $page->author, and $page->date_published (the $page variable is part of the ProcessWire API). Template files are usually HTML with PHP tags to insert the content.

  • In my experience, this makes it relatively easy to add new post types by adding new templates. It also allows for more specific posting interfaces for each type of content, rather than a longer form with many options. gRegor Morrill 16:45, 14 November 2016 (PST)

Silo Examples

Some silos have their own template formats which allow you to customize the look and feel of your blog on their site.

IndieWeb Thoughts

Use Cases

What are the use cases for indieweb templates, e.g. for specific indieweb projects?

Falcon

For Falcon I have encountered the following use cases for templates:

  • home page (uses file index.html) with blocks to fill in:
    • composite stream or most recent n (e.g. 16) posts (uses classname stream - number is hardcoded)
    • sidebar box list of recent articles - a few (e.g. 3) most recent articles (names + permalinks) (uses class name recent-articles - number is hardcoded)
  • legacy feed (uses file updates.atom) -
    • most recent n (e.g. 3) posts (optionally filtered to only be of one or more specific post types. number is hardcoded)
  • post permalink (different per post type. currently hardcoded, needs templates)
  • archive page (composite/mult-post-type for bim, newmonth, day, and all posts of a single type on a day. currently hardcoded, needs templates)

For the "needs templates" items, I'm planning on taking the approach of using microformats2 h-entry and h-card to identify the elements that should be replaced with information.

For outputting user visible datetime formatting in particular, I'm going to use a new (but hopefully more straightforward) datetime formatting format:

Tantek

Taproot

Taproot uses templates everywhere to render data from filesystem storage into HTML for the web.

  • there’s a header and footer template which wrap the body of every page, adding basic navigation+stylesheets+js in the header, licensing information and credits in the footer
    • (next version) the header template handles putting microformats2 root classname(s) on the body element
  • the homepage is a single HTML file which gets loaded in between the padding

For each content type there are typically three templates:

  • an editing template, a form which gets used both for creating new content and editing existing content
    • nice side effect of this is that fields can be prefilled by giving the template a partial post
  • a permalink page template
  • a list template, for feed views of the content — typically a list of compact versions of the permalink page template
    • usually enough difference between list and individual that I can’t reuse anything between them — better to hard code and optimise for both scenarios

--Barnaby Walters 14:29, 21 November 2013 (PST)

HTML based template formats

Very few templating systems use HTML itself to express template semantics in HTML (which seems like an obvious simple place to start, rather than jumping to a new syntax!)

Note: if your templating system uses {{}} or {% %} or other DSL constructs to insert areas into template files, it's NOT HTML based, but rather, ASCII-based at best, since such templating sytems are assigning special meaning to those ASCII characters, rather than assigning special meaning to HTML markup.

These are the few known HTML based template formats:

  • Tally is a template language that uses HTML5 data-* attributes.
  • Templating With DOM uses class names
    • but where is a simple markup example of an element that is repeated?
    • and how a template specifies a count of how many times / instances are filled in?
      • one possibility is for the template-filling code to count the children of the element to decide how many times to iterate. A single child could mean 'as many as you see fit' as a single-entry list is unlikely as a design. This has the advantage that the template looks closer to the desired layout. Alternatively, the last child could contain ... to signal to append more.
      • API is quite similar to jQuery in places
  • DOM Templating in Node.js
    • JSDOM: For creating DOMs in node or client apps
    • Weld.js: 'Welding' data to a DOM template
    • Plates: The followup to Weld.js that allows pure html templating in server and client node apps, without having to build a DOM tree.
    • jade is a template engine often used in NodeJS but is not restricted to it as it can generate HTML and when combined with stylus it can be used to generate fully styled pages or parts of a page
  • Enforcing Strict Model-View Separation in Template Engines
    • Argued benefits of DOM style templates:
      • encapsulation: the look of a site is fully contained within templates and, likewise, the business logic is located entirely in the data model. Each specification is a complete entity.
      • clarity: a template is not a program whose emergent behavior is an HTML page; a template is an HTML file that a designer or programmer can read directly.
      • division of labor: a graphics designer can build the site templates in parallel with the coders’ development efforts. This reduces the load on programmers not only by having a (usually less expensive) designer building the templates, but by reducing communication costs; designers can tweak the HTML without having to talk to a programmer.
      • component reuse: just as programmers break large methods down into smaller methods for clarity and reusability, designers can easily factor templates into various sub-templates such as gutters, navigation bars, search box, data lists, and so on. Entangled templates tend to be difficult to factor and can- not be reused with other data sources.
      • single-point-of-change: by being able to factor templates, the designer can abstract out small elements like links and larger items like user record views. In the future, to change how every list of users, for example, appears on a site, the designer simply changes one template file. This also avoids the errors introduced by having multiple places to change a single behavior. Having a single place to change a single behavior in the model is also important. Logic in the template is to be avoided because “is admin user” logic is repeated in many templates.
      • maintenance: changing the look of a site requires a template change not a program change. Changing a program is always much riskier than changing a template. In addition, template changes do not require restarting a live, currently- in-use server application whereas code changes normally require recompilations and restarts.
      • interchangeable views: with an entangled data model and display, the designer cannot easily swap in a new look for such things as site “skins.”
      • security: templates for page customization are commonly made available to bloggers but, like macros in Microsoft Word, unrestricted templates pose a serious security risk.
  • Kit is a templating language that uses HTML comments e.g. <!-- @import ... -->

Brainstorming

A DOM templating library should, given an HTML document, be able to make intelligent replacements and transformations of content.

jQuery is one of the most well developed DOM transformation libraries, likely to be a good source of inspiration for DOM templating.

DOM templating should optimise for HTML authoring and design process at all times, above all other concerns (e.g. performance can be dealt with later, human authoring experience is more important). The HTML templates must not be devalued by cryptic squiggly bracket notation — they must be useful design artifacts at all times.

The HTML template should not depend on any one vocabulary, templating idiom, syntax, library or language.

There should be no concept of “helpers” — typically they’re just functions which take a string and output a string, but wrapped up in a bunch of framework-specific nonsense which makes them impossible to reuse. Pushing the interpolation of variables up a layer into code means that functions can just be functions, and be reused extremely easily.

Issues

How to reuse header/footer markup whilst still keeping the template files standalone?

Typically all pages on a site will share a basic layout, a header/footer or at least some invisible data (stylesheets, JS etc.) in the head. Allowing each individual template to not repeat this data is one of the main reasons templating languages exist. DOM Templating could share a common header/footer element and inject that into the DOM of each template, but then how to make each template a standalone useful HTML document?

  • One potential solution is to have modular templates with whatever CSS/JS links are required for the template to work in the template file itself, and then shared templates are injected in, maybe overwriting the other code. This way layouts can be coded in a DRY way whilst preserving each piece as being useful+viewable on its own --Barnaby Walters 02:10, 22 November 2013 (PST)
  • Minimal <head> + JS src siteheader approach - Tantek 09:14, 22 November 2013 (PST)
    • Design very minimal <head> markup in templates such that it requires little if any change ever, e.g.:
      • *one* <link rel=stylesheet> - all other handling of stylesheet includes etc. should be in that one stylesheet or done on the server. You should be minimizing your HTTP requests anyway.
      • optionally *one* <script> for handling dynamic clientside behavior - all other including of scripts should be done by that one script or on the server. You should be minimizing your HTTP requests anyway. Even this one script could likely be included at the top of the <body> along with the site header.
      • everything else in the <head> is likely template specific (e.g. <title>, other link rels, metacrap etc.)
    • For visible site-headers (i.e. stuff just inside <body> at the top of the page), try: <script src> include it in in the template file and then also have the template engine replace that script src with the real site-header on the server. (similar with footer if needed) e.g.
      • <body><script src="include-site-header.js"></script>...
      • include-site-header.js could just have a giant document.write statement.
      • the template engine could process all <script src="include-***.js"> by reading them, stripping document.write from around the markup and including the result directly replacing the <script src></script> element from the template.

Other template formats

The vast majority existing template formats use {{}} (e.g. [1]) or that and/or {% %} (e.g. [2]) or other DSL constructs to insert areas into template files.

All of these add weird (new syntax) markup to HTML, or replace HTML altogether with another form of markup.

Alphabetically:

eRuby

eRuby (AKA ERB) is a templating system that uses <% %> tags to embed Ruby into HTML.

Haml

Haml is a replacement for eRuby that drops all HTML and uses its own markup language instead using %tagname e.g. %h1, linebreaks, and indentation. Doing so, claims haml.info, "accelerates and simplifies template creation"[3].

IndieWeb opinions of Haml:

  • -1 Aaronpk[4]
  • -1 Tantek - anything that tries to be a replacement HTML is typically going to do a poor job, and fails the "quickly check it in the browser" editability test (Oh I have to setup Ruby first? Oh I have to check to make sure I have the right version of Ruby? More commandline futzing? Forget it.)
  • ...

jinja2

Main article: jinja2

jinja2 uses {% %} syntax.

Liquid

Liquid is a templating language extracted from the Shopify engine that uses {% %} {{ }} markup inside HTML.

IndieWeb opinions of Liquid:

  • -1 Aaronpk:

    I don't like all the things like liquid, cause they invent other syntaxes for things that just end up being more complicated[5]

  • ...

Twig

Twig is a PHP based templating language very similar to Liquid.

Resources

See Also

Retrieved from "https://indieweb.org/wiki/index.php?title=template&oldid=55115"