Customizing in CM WebClient
Attach point
A template for a given screen can be generated from more than one template by using attach points. The templates are arranged in order from root to leaf. An attach point is a location defined in a template that other templates further towards the leaf can populate with data. See Template generation.
Attach points can be defined in the root template or a page template using the /(!AttachPoint) command. When an attach point is defined, it is initally empty (it will not expand to anything), until it is populated by templates further down the inheritance path, or by controls via their control name property.
See Also /(!AttachPoint).
Bean controls
Some controls are implemented in Plex as a Java Bean control. Although Java Beans cannot be loaded in WebClient, their functionality can be emulated through the use of a custom template and customized source code objects in Plex.
The name property of the bean control is the default name of template that is used (without the .ctrl extension.)
In the source code objects, variables in the control may be created using names which you define. The methods that do this are called setVar and getVar and they are located in the class WebBeanData. The source code objects may also call the method processAction to send a control action to the template.
In the bean control's template, the variables may be retrieved using the /(!Var) control command.
If the bean control sends a value to the server as a request parameter, the data in the parameter is taken to be a JSON object, and bean's variables are updated with the keys and values of that object.
Example: See DojoTab.ctrl in the distribution for an example of a tab control implemented in Javascript.
Control action
If the value of a control changes, the rendering on the web browser would also need to be updated. CM WebClient supports this two different ways. In the first method, page refresh, when the value of a control changes, the web browser is instructed to reload the page from the server. This will cause the template to be re-evaluated and the user will see the new data. This is the default method that is used to update the display.
In order to avoid page reloads, a second method is supported. In this method, called action updates, the page is not reloaded. Instead, the server sends back commands corresponding to only the changes that have occurred. These are called actions. An action has a name and an optional argument. Each action is expanded into a block of Javascript code that is then used to incrementally update the screen.
In order to use action updates with a control, the desired actions must be enabled for that control. This is accomplished by using the /(!EnableAction) template command within the control template for that control. The names of the actions that are going to be handled by the template are specified as parameters to that command. Then the /(!Action) command can be used to specifiy that commands that should be expanded when that action occurs. Ordinarily, the /(!Action) command is placed within an attach point that is within a Javascript output path.
The following actions are defined:
SetValue
sent when the value of a field has been changed.
SetState
sent when the state of the control has been changed.
SetFocus
sent when the control is to be given focus.
Refresh
sent to a panel or site control when the panel needs to be refreshed. The argument is the panel control.
Alert
sent when a Dialog Message or Status Message has been sent to the panel.
Enquiry
sent when an Enquiry Message has been sent to the panel.
Load
sent to a site control when the child panel has been loaded. The argument is the panel control.
Hide
sent to a site control when the child panel has been hidden.
Show
sent to a site control when the child panel has been shown.
Grid.Insert
sent to a grid when a row has been inserted. The argument is the row. Grid.Clear
sent to a grid when the grid has been cleared.
Grid.Remove
sent to a grid when a row has been removed. The argument is the row. Grid.Update
sent to a grid when a row has been updated. The argument is the row.
Control context
When the template generator is in a control context, it is expanding a template for a specific control. This means it is possible to use control commands to access that control.
The template generator is automatically in a control context when it is expanding a control template. It is also in a control context when expanding the /(FOCUS) command.
Control name property
The control name property is a panel property that can be set in Plex for each control. Although it is not required to be set, it is strongly recommended that the control name be set for each control that is to be used under WebClient.
The control name property can take two syntaxes. The first syntax is simply a unique name given to the control. This name appears in the generated HTML and Javascript and aids in debugging. In the second syntax, the unique name is followed by a colon, then an attach point name, then optionally another colon and template parameters. In this case, the control is given a name and also a location in the template where it is to appear. The control will be placed in the named attach point, which must be defined in the current panel's root template or page template. Any additional parameters following the attach point are passed to the control's template.
Example: If you have defined an attach point named ButtonsArea, and you want to place a button in it, you might assign the button the control name ExitButton:ButtonsArea.
Control reference
Certain template commands are not intended to expand to text, but rather are used to refer to a control to which another command is addressed. The next parameter of the command is taken to be the next command to be applied.
Any control with a control name can be used as a control reference, by giving the control name as a command. In addition, there are special template commands which are useful as control references.
Example: If you have a control named Grid1 and wish to access its size, you can may write /(!Grid1:Size). Here, Grid1 is functioning as a control reference command. If you have a column heading control and need the NameID of the corresponding edit control, you can write /(!Edit:!NameID). /(!Edit) is a control reference command.
Control template
A control template is used to produce HTML and Javascript for a control that is on a Plex panel. A control template is expanded and placed in the attach point that is associated with the control via the control name property.
The default control template that is used is in a file that is named by taking the type for of the control and prefixing it by Web. The extension that is used is .ctrl. For example, the default control template used for edit fields is WebEdit.ctrl. These control files are normally located in the SysTemplates folder.
To override and specify a specific control template that is to be used for a control, specify the template= parameter in the control name property for that control. The value of this parameter will be suffixed with the extension .ctrl and used instead of the default control template.
Example: If you have a custom template called ToggleButton.ctrl and wish to use this template for a check box control, you may set the control name parameter template=ToggleButton.
Default attach points for controls
If the control name property for a control does not specify an attach point for the control, a default attach point is selected based on the type of the control. The attach point is selected as follows:
Column heading
ColumnsArea
Grid edit control
CellsArea
Menu bar
MenuBarArea
Menu
MenuArea
Menu item or separator
MenuItemArea
Toolbar
ToolbarArea
Toolbar Button
ToolArea
All other controls
MainArea
In addition, the parameter default is passed to the template when the default attach point is selected.
Example: If an edit field control is given a control name property of MyControl, the default attach point of MainArea applies and the parameter default is also passed to the template. In other words, it is as if the edit field control had a control name property of MyControl:MainArea:default.
Name identifier
If a Plex panel contains child panels, the control name of a control, as given by /(!Name), may not uniquely identify a control in the web browser. This is because even though the control is unique within a page, it still may appear in multiple child panels and create duplicates.
To resolve this issue, use the /(!NameID) command to generate a unique name identifier. This name will be prefixed by both the site's control name and the child panel's name. This name is suitable for use an identifier in the web browser's DOM.
Output path
CM WebClient can send a response back to the client of several different types. The output path is a parameter that determines what type of response is sent. In addition, some response formats can include hierarchical data. The output path can be used to index into that data.
The main output paths supported are:
html
the response mime-type is text/html. The contents are escaped according to HTML rules.
json
the response mime-type is application/json. The contents are encoded as a valid JSON expression.
For the json output type, a hierarchical naming scheme is possible. After the json component, which must be the top-level component in the path, a dot-separated path may be placed. The components of this path are created as JSON sub-objects in the JSON path.
Example: Suppose a response is created with the command /(!OutTo:json.x.y.z)abc/(!OutTo). If this response is returned to a web browser and loaded as a JSON expression and assigned to the variable t, then t.x.y.z == "abc".
Page template
A page template is an optional template that is expanded during the template generation process. A page template can place data into attach points that are defined by either the root template or another page template.
See Also: Template generation
Physical event
The Plex physical events which may be handled in WebClient are:
Pressed
Load Grid
Double Click
Select
Mouse Down
Mouse Move
Mouse Up
Gained Focus
Lost Focus
Changed
Updated
Select Menu
Query Close
Modified
See also: /(!Event)
Property modifier
A property modifier is an optional parameter which may be placed after the property name parameter in a /(!Property) command. The following property modifiers are available:
x
for a property value which is a coordinate in the format x y, expands to x.
y
for a property value which is a coordinate in the format x y, expands to y.
hexcolor
for a property value which is a color in the format r g b, expands to the color in HTML #rrggbb notation.
htmlaccel
for a property value which uses the & character to indicate that the next character is to be underlined, converts this notation to HTML using the <u> tag.
For example: control name is set to
buttonA:MainArea:default:htmlaccel=&Apply
Apply button can be executed by pressing CTRL+A
htmlbr
for a property value which uses the ^ character to indicate a line break, converts this notation to HTML using the <br> tag.
nbspifempty
if the property value is blank or consists only of spaces, expands to instead (as HTML source). Otherwise, leaves the value as is.
html
marks that the value is to be treated as HTML source.
js
marks that the value is to be treated as JavaScript source. This is the default option; if html is not specified, the property command will generate JavaScript source.
Root template
The root template is first template that is expanded during the template generation process. The default root template is called WebShell-root.wcli. It expands to the basic HTML and Javascript templates where all other template data is placed, via page templates and control templates.
See Also: Template generation
Source
Text that is expanded into the template can be of two types, source or data. By default, any text that is placed into a template at run-time is considered data. When text is considered data, it cannot contain markup commands such as HTML tags or Javascript expressions. If the data contains any special characters that would have meaning to the HTML or Javascript parser, such as angle brackets, ampersands, or quote markers, they will be automatically escaped appropriately for those parsers.
Specifically, if text is handled as data, and the output path is set to an HTML fragment, the characters less-than, greater-than, and ampersand are escaped with entity references. For example, <foo> is encoded as <foo>
If text is handled as data, and the output path is a Javascript fragment, the text is encoded as a valid Javascript string literal constant. This includes all quotation marks automatically. For example, abc"def is encoded as "abc\"def".
If you have some text that is to be expanded at run-time and interpreted as an actual HTML tag or Javascript expression, with escaping, you must inform WebClient to handle it as source. This can be accomplished with a property modifier parameter on the property command.
Template generation
When generating a template for a panel, WebClient first attempts to locate a root template. The root template is a template available in the classpath such that the following two conditions are met:
The name of the file consists of the implementation name of a function followed by -root.wcli.
That function is in the inheritance path of the panel function being generated.
When there are two or more such functions in the inheritance path, the lowest (closest to the generated function) one takes precedence. If no root templates are available, template generation aborts with an error.
WebClient loads the root template, then it searches for page templates which may occur in the inheritance path between the generated function and the root template function. The following must be true for a valid page template:
The name of the template file consists of the implementation name of a function followed by -page.wcli.
That function is in the inheritance path of the panel function being generated, and is lower than the root template that is in use.
The page templates are applied in order starting from the page template closest to the root template, and ending with the template closest to the panel function. Page templates are optional.
Finally, WebClient automatically generates a template for the panel function itself. This file does not need to be supplied by the user and is named by taking the implementation name of the panel function and appending -panelgen.wcli. This file is obtained by automatically expanding all of the control templates in the panel.
The following figure illustrates the process:
Related Articles
CM WebClient for CM M3
Pre-requisites CA Plex dispatcher – The System i TCP/IP Dispatcher is required when the transformed applications call external iSeries objects (RPG, CL programs) Properties Configuration m3startup.properties This is the file were the AS400 ...Download CM WebClient 1.8.8
This article contains information on the latest public release of CM WebClient, updated 08/03/2023. WebClient 1.8 group model(WEBCLI60) and advanced control group model(WebClientControls6.0) are available for Plex 6.0 or greater. If prompted to ...Patch Build to CM WebClient 1.8.8
New Patch Build Version: Date 08/02/2024 WebClient-1.8.9-pre13469 NOTE : If the hightail link doesn't open correctly the first time, please just reload the screen, we recommend using the Chrome browser to open it. Stable Release CM WebClient 1.8.8 ...WebClient Manual
Here you can find the articles of the CM WebClient user manual, just click on the name and it will take you directly to the article. Introduction Installation Requirements Plex Model Configuration Overview of Workspace Setup Calling WebClient from an ...CM WebClient 1.8.8 Release Notes
Download current GA Release : Download CM WebClient 1.8.8 WebClient Mobile Updates To see the latest updates of WebClient Mobile, please visit: WebClient Mobile repository. What's New? Support Java 11 Complete functionality of DojoTimePicker.ctrl to ...