Formation is a JavaScript library for dealing with dynamic HTML in JavaScript.
Formation runs on top of Hogan.js by default (the engine can be easily swapped out) and is useful for building complex forms and UIs from a JSON config.

At it's simplest, Formation can simply be a wrapper around a templating engine to allow all templates to be loaded in asynchronously via 1 request to your json config.

Dig a little deeper, and you'll be able to use the config to build incredibly complex (and context-aware) UIs with a JSON file. Formation supports automatic form validation, recursion, separate templates for different themes, rendering to HTML string as well as directly to a DOM entity, and much more!

Formation comes with some pre-built templates for common elements (form elements, labels, modals, divs) under the bootstrap theme. Working forms can easily be created by combining these elements right off the bat, and more advanced UIs can be created by adding in a few more templates of your own.

Formation requires a few things to run:

• jQuery
• A templating engine (Hogan, Mustache, etc)
• A formation config file (default in the repo)

Something like this in your HTML would satisfy the first two requirements.

<script type="text/javascript" src="//code.jquery.com/jquery-1.11.3.min.js"></script>
<script type="text/javascript" src="assets/js/hogan.js"></script>
<script type="text/javascript" src="assets/js/formation.js"></script>

For the third, you just need to instantiate Formation in your javascript and let it know where your template file is. (Default is assets/templates/templates.json) Here's a snippet that will instantiate Formation with a custom template file path, and provide a callback for Formation to execute when it's all set up:

$(document).ready(function() {
    window.formation = new Formation({
        'template_file':'path/to/templates.json', // Only needed if your path is *not* assets/templates/templates.json
        'template_engine': Hogan, // Not actually needed unless you *are not* using Hogan, Hogan is default.
        'ready_callbacks':[ // An array of functions. Each function in the array will be called when Formation loads it's config and is ready for use.
            callback,
            function(){ console.log('I am a callback'); }
        ]
    });
});

Every instance of Formation will also have a ready property, which will be true once Formation has readied itself, if for some reason you don't like using callbacks. Once all of this is done, you should be all set up! See the example in examples/basic-setup for something bare-bones that works.

There're three entities you need to know about in Formation. A theme, a template, and a form.

Themes are simple. They're simply a way of grouping a bunch of templates. Most projects will only ever need one theme. In the default configuration, there is one theme, bootstrap. Themes allow you to easily change between different templates, and can be incredibly helpful when building a new version of an existing website or even A/B testing UI changes.

Templates are the core of Formation. How templates get rendered and what logic they support depend on the rendering engine used. By default Hogan js is used. Templates are provided to Formation in the form of JSON strings within the JSON config, however the most popular way of storing templates is within HTML files that get compiled at build time into the JSON configuration.

Within Formation, a form is a JSON representation of a bunch of templates. It allows attaching attributes which templates can use internally, as well as specify custom things such as how to validate a text field template or pretty much anything.

The usual dev setup for a project using formation is as follows:

• A forms.json file containing only the forms for the applications.
• A templates folder, containing folders named after themes in the application, which in turn contain your templates as HTML files.
• At build time, a simple script is run. This script will do the following:
  • Generate a JSON object containing your themes and templates by inferring names from the file structure of your templates folder
  • Combine this JSON object with your forms.json file
  • Generate the final config for Formation in the form of a templates.json file.

This may seem a bit complicated, however it allows separation of all the entities, as well as allowing you to edit your templates in nice structures HTML files and have them automagically tidied up and condensed for your build.

Once you've got Formation up and running, you'll be ready to start working with the templates!

Formation has three main methods:

• .template(template_id, values, theme_id)
  • Render a single template and return a HTML string.
  • template_id - ID of the template to render
  • values - optional - Dictionary to inject into the template configuration.
  • theme_id - optional - Override the theme the template is pulled from
• .form(form_id, values, theme_id, return_html)
  • Render a form and return either a HTML entity or a HTML string of the rendered form.
  • form_id - ID of the form to render
  • values - optional - Dictionary to inject into the form configuration. Keys in the dictionary should correspond to the name property of the fields in the form, Values to be dictionaries to update that field's template config with.
  • theme_id - optional - Override the theme the template is pulled from
  • return_html - optional - Return a HTML string instead of a HTML entity
• .extract($form, name_map, unvalidated)
  • This method extracts values from a formation form and returns them in the form of a Dictionary
  • $form - A jQuery element referencing the container for the formation form.
  • name_map - optional a Dictionary to map the names of the fields to the keys you'd like them in the return dictionary
  • unvalidated - optional - Not too sure tbh.