Page Comparison

As every framework is different, there is no "one size fits all" solution. Some frameworks might not need templates (for example, the JSON plug-in simply writes JSON to files), others might need a handful of templates, others might need a mix of Javascript and HTML, JSX or even CSS.The template files that the plug-in provides are what will be turned into the source of the forms components. As each framework defines its components in a different way, template files will be different for every framework, perhaps even for every framework version.

The template files from a plug-in are copied out of the plug-in folder and into the templates folder specified during the Forms CLI project initialisation. This is so that the developers can modify the templates (for example, if every form element needs a certain CSS class, or some custom code needs to be put into every javascript controller) on a per project basis, and use their version control system to version the templates with the project.

To make working with templates easier, we have the Template Helper Module, with common functions for reading, writing, and storing templates for use during the transformation.

We use the mustache template library, with the delimiters set to <% %> rather than {{ }} so that we don't interfere with libraries like AngularJS, whose built in system also uses {{ }}.

Template Helper Module Installation & Commands

Installation:

npm i --save @blinkmobile/forms-template-helper

API

The template helper exposes the following functions via an object. The majority of function are wrapped by the functions provided by "service", but are exposed for convenience

service

Object containing two functions that wrap most the below functions.

• load (templatePath) => Promise(<Array<MustacheRenderers>)
  • Loads all templates in a given path. Sub folders are treated as 'types', eg a folder structure of

|-templates
| |-html
| | |-text.mustache
| |-js
| | |-controller.js.mustache

results in two types of templates, "html" and "js"

• getByType (type) => Array<object>
  • returns an object where the key is the name of the file (minus the .mustache part) and the value is a Mustache Renderer, "primed" with the template

fileListHelper

Object containing helper functions for getting lists of files.

• getFileList(path <string>) => Promise(Array<string>)
  • Gets a list of files from the specified path
• getFolderList(path <string>) => Promise(Array<string>)
  • Gets a list of folders from the specified path

readFileContents

readFileContents(path-to-file <string>) => Promise(contents <string>)

Asynchronously reads the contents of a file and resolves with the contents of the file.

mustacheRenderer

Object containing helper functions to prime a mustache template with the contents of a mustache file

• renderer (template<string>) => (data<object>) => <string>
  • Returns a function that accepts an object of data, lazily runs mustache on the initial template with the data
• createRenderer (filePath<string>) => (data<object>) => <string>
  • Takes a path to a mustache file and reads the file, passing the template to the above renderer function, returning the result

writeFile

writeFile(filePath<string>, contents<string>) => Promise(filePath<string>)

Writes contents to path. Will recursively create the path if it doesn't exist

lazyWriteFile

lazyWriteFile (filePath<string>, contents<string>) => (basePath = '') => writeFile

Same as writeFile but returns a function that will write the file to basePath when run

writeTemplates

writeTemplates (srcFolder<string>, destFolder<string>)

Used by the forms transformer during initialisation to copy the templates into the forms project folder. srcFolder is where in your plugin project the template files are, destFolder is where they will be copied to. Note that all contents of destFolder are removed.

Sample Angular Template:these templates individually.

Sample Angular Template

<ng-form name="<%interaction%>" class="bm-form" <%#showWhen%>ng-show="<%moduleName%>.<%showWhen%>()"<%/showWhen%>
                  <%#hideWhen%>ng-hide="<%moduleName%>.<%hideWhen%>()"<%/hideWhen%>>
  <%&header%>
  <%&elements%>
  <%&footer%>

  <ng-transclude ng-transclude-slot="pagination"></ng-transclude>
  <button ng-click="<%moduleName%>.onSaveClick(<%moduleName%>.model)" ng-show="!<%moduleName%>.isSubForm">Submit</button>
</ng-form>

...

We have a very simple AngularJS ng-form element which uses the properties of the passed in element to create a HTML string representation of a form. It is important to note that whilst we have a data normalization step, the data that is passed to processForm can be freely modified by you to match your mustache templates.

Use The Template

...

If you use the template helper module we take advantage of the mustache Mustache.parse function to "prime" a Mustache renderer with the template string. When using the template helper module, service.getByType('my-type')returns an object with the template file name as the key (minus the .mustache part), and the value is a "Mustache renderer" - a function that takes an object and returns the compiled template string. See the template helper docs for a list of functions and how to use them

What about other template systems?

...

Helper Module

To make working with templates easier, we have the Template Helper Module, with common functions for reading, writing, and storing templates for use during the transformation. We also use the mustache template library, with the delimiters set to <% %> rather than {{ }} so that we don't interfere with libraries like AngularJS, whose built in system also uses {{ }}.

The next section will go into detail on what functionality the Template Helper Module provides.

Next Step

Template Helper Module