ES Rendering Framework

ES uses the ES rendering framework to render pages. The ES rendering framework internally uses the Handlebars template engine to define views as HBS files. Any syntax construct that is valid in Handlebars is also valid in a ES rendering framework view template. A page in ES rendering framework consists of the following components:

• Page Renderer - This is a view controller, which arranges the structure of the page by defining a page layout and partials.
• Page Layout - This is a handlebars template file that defines regions in which partials may be added.
• Partials - Handlebars template files that define a portion of the view.
• Helpers - A script file that defines the resources required for a partial.

In addition, ES rendering framework uses file names to the interrelated components defined above.Therefore t he page renderer should have the same name as the page controller (e.g., A  help.jag file should have a help.js as the renderer) and t he partials and helpers should have the same name (e.g., A  help-body.hbs file must have its helper named as follows: help-body.js). ES rendering framework also depends on a rigid file structure to locate resources. The file structure is as follows:

Rules when working with the ES rendering framework

When working with the ES rendering framework the following rules should be always followed:

• All partials should be only placed in the partials directory.
• All helpers should be only placed in the helpers directory.
• View resources should be only placed in the appropriate resource folder (e.g., All JS files should be placed in the js directory).

Workflow of rendering a page using the ES rendering framework

The above diagram explains the workflow associated with rendering a page using ES rendering framework. A breakdown of the key steps is given below:

1. The caramel.render() is called within a page controller.
2. Renderer resolution - A renderer in ES rendering framework binds the different components of a view to produce a page. 
   • ES rendering framework uses the mapped path of the controller handling a request to determine the renderer. 
   • The theme resolve method is invoked to determine the location of the renderer in context of the application. 
   • ES uses this resolve method in its extension model to locate renderers, which have been defined by developers, in app and asset extensions.
3. Renderer executed - 
   • The renderer has a call to the ES rendering framework theme method. 
     
   • The theme method is a utility method provided by the ES rendering framework to allow developers to layout a page. 
   • The theme method signature consists of a layout page and a data object against which it will be evaluated: theme (pageName,context)
     • In the above screenshot the pageName is single-col-fluid
     • The context object consists of a set of partials and data object.

   • The page layout is itself another partial. ES rendering framework will attempt to locate a partial named single-col-fluid.hbs within the pages directory of the active theme.
     

   • The page layout consists of a set of well defined areas in which other partials can be plugged in as shown above. In the above screenshot there are 6 zones where other partials can be plugged in: title, header, ribbon, leftnav and footer.

   • The data object passed into the theme method corresponds to these zones:
      
4. Partial resources are collected. Each partial in the ES rendering framework can consists of a set of supporting resources such as, client-side javascript files, CSS and font files. These resources are defined in helpers. A helper is javascript file with a resource callback.
   
   • ES rendering framework locates the helper files of partials, by checking for a script with the same name as the partial in the helpers directory of the active theme.
     

5. Page is rendered.

   • Each partial is compiled into a Handlebars template function.

   • The template function is then evaluated in terms of the context object and the HTML string is returned.

   • The resources defined in the helpers are appended to the {{js}}, {{css}} and {{code}} sections of the partial.