Ogel

Templating system for the rapid prototyping of flat html builds.

This is meant to help facilitate the creation of flat builds. It pieces together fragments of a site build and produces the final flat html output that you would get sign off on etc.

Installation

npm install xp-ogel

Usage

var ogel = require('xp-ogel');

var options = {
  src: 'src',
  dest: 'build',
  templateDir: 'src/templates'
};

// preview mode - will trigger the function callback for each file found and parsed
// returns an object with the filename and compiled html
ogel.preview(options, function(args){
   console.log('new file parsed: ' + args.file);
   console.log(args.html);
});

//build mode - returns when completed and generates the new flat build for you based on the 'dest' directory

ogel.build(options);

TODO

In no particular order

~~Fix \r\n vs. \n differences between systems in regex. \s\S produced odd results~~
The system currently works inwards. Some efficiencies could be gained by working outwards
Tests (started)
General regex cleanup. I'm terrible with regex and I'm sure there could be some fixes applied
It would be nice to randomize the lorem ipsum that is generated
~~Turn this into a npm module + grunt task (two separate projects where the task references the npm module)~~

Features

Templates (inline and block)
Nested Templates
Optional placeholders (yields)
Basic model support (think of having a layout where you need to set values based on interior page)
Lorem ipsum generation
Placeholder.it shortcut
Repeatable blocks

## Templates

Templates are found via {{name}}, where the name would match a filename in your templates directory. If you place your template in a sub folder, such as templates/menus/main-navigation.html, you would reference it via {{menus/main-navigation}}

There are two types of templates.

Inline Templates

This is a straight replacement.

An example:

<body>
  ...
  {{footer}}
</body>

In this scenario, the {{footer}} would fetch the contents of the footer.html template and swap the content.

Block Templates

This allows for you to nest content within the data of a template. In order to do so, you must include a {{yield}} in your template. You must also include an opening and closing tag for the template.

An example (say index.html referencing the layout template):

{{layout}}
    <article>
      main article content goes here
    </article>
{{/layout}}

## Nested Templates

You can nest templates. So a template can reference another template. It's a recursive system.

An exmaple:

{{layout}}
  {{aside}}
  <article>
    main article content goes here
  </article>
{{/layout}}

You can see above that we've used both the layout template as well as the aside template. In fact, the layout template could also reference multiple other templates etc.

## Optional Placeholders (optional yield blocks)

You can include optional placeholders (or yield blocks) in your templates. For instance, maybe your layout has the ability to be either 1 or 2 columns. Your aside (column 1) is optional, so you can declare it like:

<!-- layout.html (a template) -->
<body>
  <div class="row">
    {{yield:aside}} <!-- define an optional yield block -->
    <div class="col-md-10">
      {{yield}} <!-- main content of callee goes here -->
    </div>
  </div>
</body>

And in your page that references the layout template

<!-- index.html (a page) -->
{{layout}}
  {{layout:aside}}
    <div class="col-md-2">
      side nav could go here
    </div>
  {{/layout:aside}}
  main content goes here and ends up in the {{yield}} block
{{/layout}}

## Basic Model Support

In the previous example you saw that we had a col-md-10 in our layout template. The aside yield block is also optional, so ideally, you would want the col-md-10 to change based on whether you used the aside block or not.

One way that you could achieve this is through exposing model properties.

Some things to keep in mind.

Models can support properties
Models can support methods
Models compound as templates are used. Meaning that they stack properties. If you had 4 templates, all adding different properties to the model, all of those properties would be made available.

In the situation described above, we could handle it via:

<!-- layout.html (a template)-->
{{model}}
  {
    width: 12
  }
{{/model}}
<body>
  <div class="row">
    {{yield:aside}} <!-- define an optional yield block -->
    <div class="col-md-{{model.width}}"> <!-- here we use the model property instead -->
      {{yield}} <!-- main content of callee goes here -->
    </div>
  </div>
</body>

<!-- index.html (a page using the layout) -->
{{model}}
  {
    width: 10 <!-- here we override the default width and set it to 10, as we're using 2 columns for our aside -->
  }
{{/model}}
{{layout}}
  {{layout:aside}}
    <div class="col-md-2">
      side nav could go here
    </div>
  {{/layout:aside}}
  main content goes here and ends up in the {{yield}} block
{{/layout}}

Models can also utilize functions. For instance, in your copyright notice you might want to use the current year.

{{model}}
  {
    year: function(){ return new Date().getFullYear(); }
  }
{{/model}}

<!-- footer.html (a template) -->
<p class="copyright">&copy; {{model.year}} company inc.</p>

Notice that you still reference it using the same syntax.

Model methods do not currently support arguments.

## Lorem ipsum generation

This shortcut allows you to quickly inject lorem ipsum placeholder data. It uses lorem by shyiko and allows for any of the classnames that he supports.

A few exmaples

{{ipsum:w10}} would generate 10 words of lorem ipsum

{{ipsum:p4}} would generate 4 paragraphs of lorem ipsum

{{ipsum:s8}} would generate 8 sentences of lorem ipsum

## Placeholder.it shortcut

This shortcut allows you to quickly specify placeholder.it images. There are to styles that you can leverage.

{{img:200x200}} where the 200x200 specifies the dimensions being passed to placeholder.it. Because of this, any of their syntax is valid here as well.

{{img:200x200:class="pull-left" alt="no image"}} here you can see that we're also including additional attributes.

## Repeatable blocks

This shortcut allows you to quickly repeat content with a repeatable block. An example could be a list or table of data. This lets you quickly set how many items or rows etc should show up.

<ul>
{{repeat:10}} <!-- 10 could be any number -->
  <li>some data here</li>
{{/repeat}}
</ul>