wintersmith-tally

This is a simple plugin for wintersmith that allows the use of Tally templates.

Installation

Install wintersmith if you have not yet done so:

npm install wintersmith -g

Change directories to the site you would like to use with wintersmith (for example, the example site located in the wintersmith-tally source tree) and install wintersmith-tally:

npm install wintersmith-tally

Finally, add "wintersmith-tally" to the plugins array of the config.json file of the wintersmith site:

"plugins": [
  ...,
  "wintersmith-tally"
]

Example

There is a simple weblog example in the example/ directory. To get it started, cd example/ and type wintersmith preview -v, then connect your browser to http://127.0.0.1:8080/.

A short introduction to Tally

Consider a template called test.tally.html. The template contains a paragraph tag that contains a nested span:

<p>The <span data-tally-text='flowername'>skunkweed</span>
is the most beautiful flower in the world.</p>

(As you can see from the above, Tally templates are simply HTML. This allows you to design in a browser before worrying about populating data using JSON.)

Our goal is to have Tally to replace the string skunkweed with a string that we provide when the template is compiled.

Tally uses data-tally-* attributes to signal to the template engine that text (either of an element or an attribute) needs to be replaced. In the case of the test.tally.html template, the attribute data-tally-text tells Tally that it should replace the text of the span with a flowername, which will be provided in the JSON data that is passed to the Tally template engine. (If no flowername value is passed to the template engine, the original text will be left unchanged.)

Assume that we pass the following data to the Tally template engine at template compile time:

data = {
    "flowername": "orchid"
}

In that case, the Tally template engine will output the following HTML:

<p>The <span data-tally-text='flowername'>orchid</span>
is the most beautiful flower in the world.</p>

Tally can change attributes, not just values. For example, we might want to display a link providing more information about the flower. We can pass in a target URL in our JSON data, but in order to create the anchor link, we will need Tally to change the value of an attribute (the href attribute, in this case) rather than changing the value of text.

To do this, we use data-tally-attribute instead of data-tally-text:

<p>The <a data-tally-attribute='href flowerurl'>
<span data-tally-text='flowername'>skunkweed</span></a>
is the most beautiful flower in the world.</p>

(To specify multiple attributes, separate them with a semicolon.)

Now, if we pass the following data to the Tally template engine at template compile time:

data = {
    "flowername": "orchid",
    "flowerurl": "https://en.wikipedia.org/wiki/Orchidaceae"
}

Tally will output the following HTML:

<p>The <a data-tally-attribute="href flowerurl"
href="https://en.wikipedia.org/wiki/Orchidaceae">
<span data-tally-text="flowername">orchid</span></a>
is the most beautiful flower in the world.</p>

You can see this in action by starting the example and examining /flowertest.html. The template for the flowertest page is located in /templates/flower.tally.html, and the markdown source for the page is located in /contents/flowertest.md.

The wintersmith-tally plugin

The wintersmith-tally plugin is responsible for marshalling article metadata and Wintersmith site configuration information into a JSON object suitable to pass to the Tally template rendering engine.

The fields that the wintersmith-tally plugin passes to Tally are:

• All of the metadata fields defined in the .json or .md article.
• site.url, the value of locals.url from the site's config.json file.
• site.title, the value of locals.name from the site's config.json file.
• site.owner, the value of locals.owner from the site's config.json file.
• site.description, the value of locals.description from the site's config.json file.
• originaldate, the date string provided in the article metadata date field (if it exists).
• rfc822date, an RFC 822 formatted date string useful for reformatting using a small javascript script on page load. This is obtained from originaldate, and so it will not exist if originaldate does not exist.
• renderedhtml, the rendered HTML from the markdown contained in the .md file's body or the .json file's content field. (See ./example/contents/pages/jsontest and ./example/contents/pages/markdowntest for examples.)