Introduction to Kendo UI Builder Templates

Learn how to modernize your web applications with Kendo UI Builder. We explore custom templates, views, and components for AngularJS and Angular.

Kendo UI Builder 2.0, our latest tool to help you design elegant and responsive web experiences (for both OpenEdge and standalone web apps), introduced the concept of templates, or in other words, the capability to create your own custom views and custom components. The installation bundles several examples that you can tailor. However, these are quite complex and not conducive to learning how to create them from scratch.

This blog is the first of a series where we will explore how to create both custom views and custom components.

Creating Custom Views

We will start with custom views. Since there are quite a few items to understand we will explore the simplest view possible in the form of a “Hello World” custom view. This will help us comprehend the overall mechanics of getting all the elements in place with minimum dependencies and without additional complications. Also, this will constitute a bare-bones working template from which to start writing future templates.

To follow along, download the project zip from github or clone the repository.

Copy the folder “custom-hello-world-v1” to the folder “template/views” in your target application and restart Kendo UI Builder. Click “Add View,” and you should now see the custom Hello World V1 view like in this screenshot:

Select “Custom Hello World V1,” enter view name and label. 

Change the title and greeting properties as desired and click Preview. This gives you a feel for the design part and the runtime part. Now, we are ready to explore the project.

When building a custom view or component, there are three main items to construct:

1. The custom view definition file: A JSON file that describes the Custom View to Kendo UI Builder.
   
2. The design-time elements rendered in KBUI.These include:
   1. The icons shown in the component and view selection dialog.
   2. The UI of the view or component as they render at design-time—this allows you to have a different UI at design-time from the one at runtime.
      
3. How the view renders and behaves at run-time for the specific target framework (for example, AngularJS or Angular 5).The tasks we typically take care of include:
   1. Presenting the UI.
   2. Reacting to events.
   3. Interacting with data sources.

Here is a screenshot illustrating where some of these items show:

Custom View Definition File

Open the file custom-hello-world-v1.json. 

This file contains a set of fields. The key fields to define are:

1. The name and the description as they appear in the custom view creation dialog.
   
   
2. The list of properties to render in the right-side panel of the designer (view properties). For each item, an editor will be used based on the item type. The supported editors are string, integer, numeric, boolean, arrays and collections. In our case, we have defined two string properties to render in the view: title and greeting

Notes:

• Kendo UI Builder will validate the file using http://json-schema.org/specification.html
• The list of properties can be a tree. Kendo UI Builder will render the same hierarchical structure as implemented in the field “properties.”
• An object with sub-structure will be represented with expandable/collapsible panels.
• The required array is left empty as we are not imposing that any of the properties be provided.

Design-Time Elements

These are in the sub-directory “design-time.” In this directory we have:

1. Two icons: a large one, used in the view creation dialog and a small one, used in the left side panel listing all the views in the selected module.
   
2. options.json.ejs: it is used to augment the model with additional properties not defined in the definition file. These would be properties the user does not edit in the properties panel. In our case, this is an empty object literal as we have no additional properties to provide (later in custom-hello-world-v3 we will explore this capability).
   
3. template.html.ejs: this is where we program the HTML defining how our custom view will render in the Kendo UI Builder main panel.It is parameterized with metadata properties.

EJS files are template files. They are executed by Kendo UI Builder to replace the template tags with their actual value. See http://ejs.co/ for more information. 

When you program a custom view, you simply provide a representation of the widget that comes close to the runtime view, but you do not have to implement user interactions as Kendo UI Builder does not pass mouse or keyboard events to the design-time view. 

The intent is to let you focus your time and energy on the runtime view.

The sub-directory “generator” contains a file called index.js. This file will be executed with node. It contains an entry point called augmentModel. In a future post we will look into an example where we extend the model, but for now we do not need to program anything in this function.

Runtime Elements

The content of the runtime files will depend on which target framework is used. In Kendo UI Builder 2.x, we support the AngularJS framework. Starting in version 3, we will support both the AngularJS and Angular 5 frameworks.

Note: Kendo UI Builder 3.0 should be available towards the end of May 2018.

For AngularJS: The files are in sub-directory “angularjs”:

Options.json.ejs: This is where we define which view properties will get added to the model in the controller.

The model is added to the variable vm.$model (the view model) in the controller (See controller.js.ejs).

template.html.ejs: This is the file that contains the HTML that will be rendered at runtime. The items defined in options.json.ejs are available from the model.

In this template we can use AngularJS expressions, for example, {{vm.$model.greeting}} to access the “greeting” property.

A property travels from the definition file to the options.json file, then to the controller and finally to the runtime view. To help understand and follow how it travels from each file, I have named the title property:

• “titleX”: in custom view definition file (custom-hello-world-v1/custom-hello-world-v1.json)
• “titleY”: in custom-hello-world-v1/angularjs/options.json.ejs

Note: do not get confused with “title”, which is the label of the field in the view property panel.

Generator/index.js: this file is invoked when generating the source code for the view. Like at design-time, this is where we can augment the model. But we can also provide translations for distinct items using the function getTranslation. In this function, we just return an object literal with the set of items to include in the translation file.

For Angular: The files are in sub-directory “angular”

• Config.json.ejs: This is where we define which view properties will get added to the model.
• __name__view.base.component.ts.ejs : This is the Angular 5 component file (templated with ejs)
• __name__.component.html.ejs : This is the Angular 5 view file.

At this stage, you should be able to add your own property. In the next blog post, we will explore what goes on behind the scenes to complete our understanding.

Read the Next Post