Teddy templating engine

Teddy is the most readable and easy to learn templating language there is!

Or put a more technical way, Teddy is an easy to read, HTML-inspired, mostly logic-less DOM templating engine with support for both server-side and client-side templating.

It uses HTML-like `` for rudimentary templating logic and Teddy Roosevelt's facial hair for {variables}.

Check out this live demo or see below for documentation on how to write Teddy templates.

Table of contents

• Why yet another templating engine?
  • Other popular templating engines are too cryptic
• Teddy, symbol-buster extraordinaire
• How to write Teddy templates
  • Variables
  • Includes
  • Conditionals
  • Boolean logic
  • One-line ifs
  • Loops
  • Non-parsed-blocks
  • Caching blocks
  • A complex example combining many tags
• Using Teddy in Node.js
• Using Teddy with client-side JS
• API documentation
• Hacking the code

Why yet another templating engine?

Good question.

Here's why:

Other popular templating engines are too cryptic

Are you tired of all those unnecessarily cryptic templating systems out there that look like this?

<h1>{{header}}</h1>
{{#bug}}
{{/bug}}

{{#items}}
  {{#first}}
    <li><strong>{{name}}</strong></li>
  {{/first}}
  {{#link}}
    <li><a href="{{url}}">{{name}}</a></li>
  {{/link}}
{{/items}}

{{#empty}}
  <p>The list is empty.</p>
{{/empty}}

...Or this?

{{#each comments}}
<h2><a href="/posts/{{../permalink}}#{{id}}">{{title}}</a></h2>
<div>{{body}}</div>
{{/each}}

...Or this?

{#names}{.}{@idx}{.}{/idx}{@sep}, {/sep}{/names}

Want something simpler and more readable so you can stop wasting time memorizing what all those funky symbols do so you can focus more on getting actual work done?

Well you're not the only one.

Teddy, symbol-buster extraordinaire

Teddy the trust-buster was a man of the people, curtailing the abuse of monopolists. As the most badass President of all-time, there's no way he'd put up with all this indecipherable templating nonsense.

As such, Teddy the templating engine is an engine of the people, curtailing the abuse of indecipherable templating systems. Teddy trust-buster extraordinaire is now symbol-buster extraordinaire.

Here's how:

• More concise {variable} syntax. One curly bracket. Not two, not three, no pound signs, no question marks, no backticks, no gang signs, and no hieroglyphs.
• An tag for layout templates and partials which accepts arguments via child elements.
• Flow control tags: , , , , and `` for basic templating logic.
• A `` tag for looping.
• Server-side {! comments !} delimited by exclamation points in a fashion similar to ``. Server-side comments are stripped out at the template compilation stage.

How to write Teddy templates

Here's some examples of how to write Teddy templates:

Variables

Display a variable by simply writing {varName} anywhere in the template.

HTML entities such as <, >, &, ', and " will be escaped by default as a safeguard against cross-site scripting.

If you need to suppress this escaping in certain scenarios, write your variable like this: {varName|s}.

You can also use template literal ${templateLiteral} variables as well.

Includes

Include another template:

Or use the no extension shorthand (Teddy will append the .html extension for you):

Pass arguments to the template:

  Plain text argument
  
    <span>Argument with HTML in it</span>
  

The arguments you've defined will be accessible as {firstArgument} and {secondArgument|s} in the child template partial.html. Note you must use the |s flag to suppress escaping HTML entities in order to render the HTML in the second argument.

Conditionals

Check for the presence of a variable:

  <p>The variable 'something' is present</p>


  <p>The variable 'something' is not present</p>

Check a variable's value:

  <p>The variable 'something' is set to 'hello'</p>


  <p>The variable 'something' is not set to 'hello'</p>

Check for the non-presence of a variable:

  <p>The variable 'something' is not present</p>


  <p>The variable 'something' is present</p>

An statement structure with an tag which is evaluated if the first `` fails:

  <p>The variable 'something' is present</p>


  <p>The variable 'something' is not present, but 'somethingElse' is present</p>


  <p>The variable 'something' is not present and neither is 'somethingElse'</p>

An statement structure with an tag which is evaluated if the first `` fails:

  <p>The variable 'something' is not present</p>


  <p>The variable 'something' is present, but 'somethingElse' is not present</p>


  <p>The variables 'something' and 'somethingElse' are both present</p>

Note: and are considered logically equivalent statements in Teddy.

Boolean logic

Boolean logic operators are evaluated left to right.

or operator:

  <p>This will render if either 'something' or 'somethingElse' is present.</p>

and operator

  <p>This will render if 'something' is present and 'somethingElse' is present too.</p>

xor operator:

  <p>This will render if either 'something' is present or 'somethingElse' is present, but it will not render if both are present.</p>


  <p>This will render if 'something' is present and 'somethingElse' is present too.</p>

not: prefix:

  <p>This will render if 'something' is not present.</p>

Note: you cannot query the same variable twice in the same if statement or use the same boolean logic operator twice in the same if statement due to the rules of HTML grammar requiring that no HTML attributes appear more than once on the same tag.

One-line ifs

If you need a more concise conditional to control which attributes are applied to a given element, then use this syntax:

<p>One-line if.</p>

In that structure, the attribute if-something checks to see if the variable something is truthy. This means it will check for either variable presence in the model or the boolean value true. If so, the class delcared in the true attribute is written to the element, resulting in the following output:

<p class="shown">One-line if.</p>

If not, this will check for non-presence in the model or the boolean value false. If so, the class declared in the false attribute is written to the element, resulting in the following output:

<p class="hidden">One-line if.</p>

Like the `` tag you can check for both the presence of a variable as well as its value. To check the value of a variable, use this syntax:

<p>One-line if.</p>

It's important to note that whichever type of quotes you use on the outside of your true or false attributes must be reversed on the inside. So if you use single quotes on the outside, then you must use double quotes on the inside.

Also note you can only have one one-line if statement per element.

Loops

Assume the following JS model:

letters = ['a', 'b', 'c'];

It can be iterated over like so:

  <p>{letter}</p> 

In the above example through='letters' defines the JS model being iterated over and val='letter' defines a local variable for the current letter being iterated over.

When looping over more complex data structures, sometimes you will need access to both the key and the value of your array or object. For instance, suppose this JS model:

names = {jack: 'guy', jill: 'girl', hill: 'landscape'};

It can be iterated over like so:

  <p>{name}</p> 
  <p>{description}</p> 

We once again define a through attribute which we set to through='names' and a val attribute which we set to val='description' similar to the last example. However this time we've iterated over a JS object with named keys instead of a simple indexed array, so it is useful to define a key attribute in the `` tag to gain access to the name of the current iteration variable. We have defined it as key='name' in this example.

Even complex, hierarchical data structures can be iterated over. For instance, suppose this JS model:

objects = [{a:1, b:2, c:3}, {a:4, b:5, c:6}, {a:7, b:8, c:9}];

For the above array of objects, we can combine the techniques illustrated above to display each member of the hierarchy in sequence:

  <p>{i}</p> 
  <p>{item.a}</p> 
  <p>{item.b}</p> 
  <p>{item.c}</p> 

Non-parsed blocks

To skip teddy parsing a block of code, use a or tag:

<p>{this_var_will_not_be_parsed}</p>

You can also instruct the contents of a variable to not be parsed after that variable is rendered using the |p flag:

<p>{this_var_will_be_parsed_but_its_contents_will_not_be|p}</p>

Note: Teddy tags will also not be parsed if they appear inside of elements that interpret child text as plain text, e.g. `