Widgets

Beautiful WebForms Widgets¶

Beautiful WebForms Widgets are the base units a View is composed of (a View is in fact nothing but a collection of Widgets). Beautiful WebForms Widgets are implemented by Module Suite Template objects of type Beautiful WebForm Snippet stored under the CSFormSnippets folder in the Content Script Volume.

Widgets are defined by a Model and a Template.

View's Widgets templates and their models are evaluated by the Form Builder¹ to produce the intermediate View Velocity Template Document (VVTD).

At runtime (when a WebForm is rendered) the Beautiful WebForm MVC framework evaluates the VTD against a Content Script Model to produce the final WebForm HTML page.

Model and Template¶

The Widget model is implemented in the form of a Javascript object while the template is implemented in the form of an Handlebars template. The template might contain a set of partials defined by Module Suite Template objects of type Content Script Snippet stored under the CSSystem folder in the Content Script Volume, partials can be identified because their name is prefixed by the Partial keyword.

Below an example of a Widget Model and template:

{
  "fields":{
    ...
    "h_base"  :{"title":"Basics","type":"_help","help":"oh_baseProperties"},
    "fieldA":{"label":"A Field Label","type":"input","value":"","help":"Field's help message", "i18nDisabled":true},
    ...
  }
  ,"title":"My Widget" 
  ,"help":{"value":"oh_textInput"} 
  ,"order":["fieldA", "fieldB"] 
  ,"jsdependencies":[] 
  ,"cssdependencies":[] 
  ,"nonRendableWidgets":false 
  ,"columns":true 
  ,"binding":true 
  ,"style":true 
  ,"validation":true  
  ,"readonly":true 
  ,"container":false,
  ,"rendered": true
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

{{> _renderedOpen}} {{!-- Manages the "Show-if" configuration option (creates the VTL expression)--}}
{{#*inline "_componentClass"}}am-form-text-input{{/inline}}

{{#if label}}^
    {{> _labelLeft}}
    <div class="{{> _colSize}} {{>_componentClass}} {{add_class}}" {{>_amWID}}>  {{!-- {{> _colSize}} is the partial used to manage columns size --}}
    {{> _labelTop}}

{{else}}
    <div class="{{> _colSize}} {{>_componentClass}} {{#unless label}}{{#if required}}am-form-required{{/if}}{{/unless}} {{add_class}}" {{>_amWID}}>    
{{/if}}

        {{#if render}} 
        #foreach( $rowField in {{id}} )
        {{> _defaultValue }}
        {{/if}}

        <div class="am-form-input-wrap"  {{> _popover }} >

            {{#if render}}
            #if({{{readonly}}})

            <p class="{{#if bold_body}}am-form-bold{{/if}}" >
                <span class="form-control-static"> $esc.html({{id}}.value)</span>
            </p>

            #else

            {{/if}}
            <input id="{{id}}.id" 
                  name="{{id}}.id" 
                  value="{{#if render}}$esc.html({{id}}.value){{else}}{{placeholder}}{{/if}}" type="text" 
                  placeholder="{{placeholder}}" 
                  class="form-control"
                  style="{{style}}"
                  data-constraints="{{id}}.validation('{{validation}}')"

                  {{#each dataatts}}
                  data-{{label}}="{{{value}}}"
                  {{/each}}
                  />

                {{> _addDeleteButtons}}

                {{> _showErrors}}
            {{#if render}}
            #end
            {{/if}}      
        </div>

        {{#if render}}
        #end
        {{/if}}


        {{#if helptext}}    
        <p class="help-block">{{helptext}}</p>
        {{/if}}

{{#if label}}

    {{> _labelBottom}}
        </div> {{!-- Close component div --}}   
    {{> _labelRight}}

{{else}}
    </div> {{!-- Close component div --}}   
{{/if}}
<!-- END Text input-->    

{{> _renderedClose}} 

Designers can modify widgets' models properties using the Form Builder widgets configuration panel. Any a widget's model modification triggers the immediate re-evaluation of the widget's template resulting into an update of the source code.

Static Resources Management¶

Beautiful WebForms widgest might depend on static resources (Javascript and CSS files). These dependencies are defined in the widget's model through the properties jsdependencies and cssdependencies.

The definition of a static-resource dependency is represented by a list of three elements:

• the reltaive² path to the static resource file
• the version of the resource to load (a string formatted as "Major.Minor.Revision")
• an optional list of dependency definitions for static resources this library depends on

E.g.

["v2/css/select2/select2-bootstrap","3.5.4", [ ["v2/css/select2/select2","3.5.4"] ] ]

When a form is rendered the framework computes the list of all the static resources required by the associated view's widgets. The list is optimized to avoid repetitions and to respect the proper loading order. The final list of static dependencies is then automatically injected by the framework in two ViewParams variables:am_CssViewDependecies and am_JsViewDependecies.

Beautiful webForms View Templates utilize the aformentioned variables to render the HTML code required to load the associated static files.

Two Velocity macros have been designed to handle this task:

#macro( bwfJsResources $resList $blackList )
#macro( bwfCssResources $resList $blackList)

These macros combine the contents of the variables am_CssViewDependecies and am_JsViewDependecies with the list of dependencies specified as macro arguments (which are typically dependencies specific to View Template) to calculate the final list of static resources that must be loaded (producing at the same time the relevant HTML code).

E.g.

#bwfCssResources([ 
    ['v2/css/am/am_form', "2.0.0"]
    ,['v2/css/font-awesome.min', "0.0.0"]
    ,['v2/css/metro-bootstrap.min', "0.0.0"]
    ,['v2/css/am/am_gridTable', "2.0.0"]
    ,["v2/css/select2/select2-bootstrap","3.5.4",
        [
            ["v2/css/select2/select2","3.5.4"]
        ]
    ]
],
[ ["v2/css/bootstrap.min","3.3.6"]])

There are situations in which it is necessary to load multiple views dependecies when a WebForm is rendered:

• It is necessary whenever the WebForms can programmatically swithc view (e.g. a Webform organized in tabs);
• It is necessary whenever the WebForm's View makes use of SubViews widgets;

In these cases it is possibile to use the Content Script forms.addResourceDependencies API in the view OnLoad CLEH Script to force the framework to also load static resources dependencies from other Views.

The above mentioned API accepts three parameters: forms.addResourceDependencies(boolean loadJS, boolean loadCSS, String[] viewNames)

• A boolean flag indicating if Javascript resources should be loaded;
• A boolean flag indicating if CSS resources should be loaded;
• An optional list of Views from where to load dependecies from, if not specified resources will be loaded for all the Views associated with the parent Form Template object;

forms.addResourceDependencies(true, true, "'View2'", "'View3'")

forms.addResourceDependencies(true, true, "View2", "View3")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

form.viewParams.ajaxEnabled=true
if(form.viewParams.ajaxEnabled && !form.viewParams.isResourcesInit){
    forms.addResourceDependencies( form, true, true)
    form.viewParams.isResourcesInit = true
}
if (form.isFirstLoad()){
  //Code to be executed on first load only
  // es. form.myField.value = 'my value'

}
else{

}

Widgets libraries¶

A Widgets library is defined as an extensible set of Widgets that can be used through the drag & drop visual editor (FormBuilder). To simplify the navigation, the widgets are arranged in families of objects having similar functionalities. Widgets within the same library use the same initialization mechanism, as far as the JavaScript and CSS frameworks are concerned. Whenever it is necessary or convenient to introduce breaking changes, in the way in which the widgets are defined or in the way in which the widgets are managed, a new library is released.

Widget Library V1¶

This is the first version of the widget library shipped with the first version of Module Suite. This widget library has been retired and is no longer supported since Module Suite version 2.6. View Templates designed to work with library V1 are not compatible with any other library. Do not use other libraries' widgets with these View Templates.

Widget Library V2¶

This version of the widget library was first introduced with Module Suite 2.0 and is still fully supported. This library is the first using the concept of static resources management. View templates leveraging this library loads their static resource dependencies through standard HTML tags <link> and <script>. The actual HTML code required to load resources is produced by the two Velocity macros (bwfCssResources and bwfJsResources) mentioned in the static resources management paragraph. View Templates designed to work with library V2 are not compatible with any other library. Do not use other libraries' widgets with these View Templates.

Widgets of library V2 have two additional model properties: jsdependencies and cssdependencies, they represent the list of static javascript and css resources the widget depends on:

The definition of a static-resource dependency is represented by a list of three elements:

• the reltaive² path to the static resource file
• the version of the resource to load (a string formatted as "Major.Minor.Revision")
• an optional list of dependency definitions for static resources this library depends on

E.g.

...
jsdependencies:[ ["v2/css/select2/select2-bootstrap","3.5.4", [ ["v2/css/select2/select2","3.5.4"] ] ] ]
...

Widget Library V3¶

This version of the widget library was first introduced with Module Suite 2.4 and is still fully supported. This library revised the concept of static resources management. View templates leveraging this library loads their static resource dependencies through standard HTML tags as far as CSS resources are concerned and a JavaScript file and module loader Require JS for Javascript resources. The actual HTML code required to load CSS resources is produced by the the Velocity macro (bwfCssResources) mentioned in the static resources management paragraph. View Templates designed to work with library V3 are not compatible with any other library. Do not use other libraries' widgets with these View Templates.

Widgets of library V3 have two additional model properties: jsdependencies and cssdependencies, they represent the list of static javascript and css resources the widget depends on:

...
"cssdependencies":[
  ["v3/js/handsontable/handsontable.full","4.0.0", [["v3/js/handsontable/pikaday","1.4.0"]]]
  ,["v3/css/select2/select2","3.5.4"]
]
...

...
"jsdependencies":[
    ["v3/js/handsontable/am_init","1.0.0",[["Handsontable","4.0.0"], ["pikaday","1.4.0"], ["numbro","2.0.6"]]]
]
...

Widget Library V4¶

This version of the widget library was first introduced with Module Suite 2.6 and is still fully supported. This library it's an evolution of the previous iteration (library V3) which significantly increases the compatibility with standard Smart View UI. View templates leveraging this library loads their static resource dependencies through standard HTML tags as far as CSS resources are concerned and a JavaScript file and module loader Require JS for Javascript resources, which is the same AMD library used by native Content Server Smart View framework. The actual HTML code required to load CSS resources is produced by the the Velocity macro (bwfCssResources) mentioned in the static resources management paragraph. View Templates designed to work with library V4 are not compatible with any other library. Do not use other libraries' widgets with these View Templates.

Widgets of library V4 have two additional model properties: jsdependencies and cssdependencies, they represent the list of static javascript and css resources the widget depends on:

...
"cssdependencies":[
    ["amui/handsontable.full","4.0.0", [["amui/pikaday","1.4.0"]]]
    ,["amui/select2/select2","3.5.4"]
]
...

...
"jsdependencies":[
    ["bwf/handsontable/am_init","1.0.0"]
]
...