OpenWGA 7.7 - OpenWGA Concepts and Features
Design and development » TMLScript » TMLScript ObjectsModule Controllers
Starting with OpenWGA 7.2 each TML can have a "module controller" that is automatically instanciated by the OpenWGA runtime when a TML is rendered. Module controllers enable the designer to move script from TML to a TMLScript module. This makes the TML itself cleaner and easier to understand and makes the script methods testable by test frameworks. It also may improve the performance of TML modules.
The module controller for a TML is searched in a TMLScript module with name <tml-path>.Controller.tmlscript. Note that the name of the constructor therefore is Controller().
Sample:
Assume you have a TML with name "products" in directory "customer": tml/html/customer/products.tml.
Then OpenWGA will search for a TMLScript module "tmlscript/customer/products.Controller.tmlscript" to find a module controller for this TML. If such TMLScript module is found, the controller object is automatically instanciated when the TML is rendered.
The WDS 3.2 supports you in navigating to and/or creating of new module controller scripts.
Inside the TML module controller methods can be accesses using item expression $mc (standing for "module controller").
Sample:
products.Controller.tmlscript:
function Controller(){}
Controller.prototype.products = function(){
return WGA.app().query("hql", "content.contentclass='product'")
}
products.tml:
<tml:foreach item="$mc.products">
...
</tml:foreach>
Named Method parameters
If the TML code needs to call a controller method with parameters, those can be specified with a_* or a-* attributes of the <tml:item> Tag:
<tml:item name="$mc.productName" a_articleNumber="4711"/>
<tml:item name="$mc.productName" a-articleNumber="<item-expression>"/>
The parameters have to be specified in the controller method with the defined name:
Controller.prototype.productName = function(articleNumber){...}
Parameter injection
TMLScript object are "isolated" by default. This means the script has only access to the following objects:
- WGA - The WGA object providing access to the servers resources. In the isolated case these are only environment-independent resources.
- console - The JS default console object
Object methods have no access to HTTP Request, TML-Context, TML-Options ... Instead access to the environment must explicitly be specified as parameters to the methods. In case of module controllers this is done via "parameter injection" by OpenWGA when calling a method:
If a module controller method needs access to the current TML context a parameter "$cx" must be specified in the method definition:
Product.prototype.getName = function($cx){
console.log($cx.TITLE);
}
The $cx value is automatically "injected" when using the method via item expression in TML.
The following parameters can be injected when specified as method parameters:
- $cx - Current WebTML context
- $pc - the current portlet controller
- $request - The current HTTP request object (only in non-isolated-mode)
- $pageVar_<name> - global variable with specified name
- $sessionId - the session ID
- $cookie_<name> - a cokkie object with the specified name
- $option_<name> - an TML option with given name
- $form - Current WebTML form
- $field_<fieldname> - Value of a WebTML form field
- $fieldList_<fieldname> - Value of a WebTML form field in list form
- $item_<itemname> - Value of a WebTML item
- $itemList_<itemname> - Value of a WebTML item in list form
- $pMode - Mode of the current portlet
- $pContext - Context of the current portlet
- $urlParam_<name> - Value of an URL parameter
- $portlet - Current portlet object
- $portlet_<name> - portlet item (requires OpenWGA 7.5.5)
- $pEvent - Portlet event, in case of such an event
- $pEventParam_<name> - value of a portlet event parameter, in case of such an event
- $websocket - A WebSocket (only PAGE scope globals)
- $event - Application event, when called on behalf of such an event
- $tagInfo_<tagid>_<infoname> - Some WebTML tag info from the current page
- $tag - the current tag (requires OpenWGA 7.6.1)
Controller method prepare()
When a TML is rendered and a controller is found a method prepare() is called on the controller (if defined). This method may initialize internal values and return an JS-object containing options and vars available in the TML:
module constroller:
Controller.prototype.prepare = function(){
// ... init object if necessary
return{
$options: {
customer: "Innovation Gate"
},
$vars: {
_customer: "Innovation Gate"
}
}
}
TML:
<tml:item name="$option_customer"/>
<tml:option name="customer"/>
<tml:item name="_customer"/>
Calling actions
Methods on the controller may also be called as WebTML actions:
<tml:url action="$mc.someMethod"/>
The action may return a JS object with properties that influence the following request:
- $vars: Contains a JS object with key/value pairs that are given as WebTML variables to the following WebTML request.
- $portletVars: The same for portlet variables
- $pageVars: The same for page vars
- $redirect: Instructs OpenWGA to redirect to some other URL.
- $portletEvents: Portlet Events to be thrown. A JS object, names are portlet event names, values are again JS objects with event parameters as key/value pairs. An event without parameter uses an empty JS object
Disable isolation for specific methods
On an otherwise isolated object you can mark certain methods to be "non-isolated":
Controller.propotype.myFreeMethod = function() { ... }.nonIsolated()
This method will have full access to the current WebTML environment, just in case something is needed that is not available in isolated mode.