OpenWGA 7.5 - OpenWGA Concepts and Features
Design and development » WebTML » Features » PortletsPortlet configuration, variables and context
These three portlet features have in common that they increase the modularity of the portlet by making it independent from the page it is rendered on and - vice versa - keep the portlet from influencing the rest of the page in an unintended manner. Therefor the data that these features store is only available inside the current WebTML portlet plus inside WebTML actions whose action links were rendered inside the portlet.
Portlet configuration and items
The portlet configuration is a part of the user profile of the current user which is reserved for the current portlet and therefor enables it to store its own personalisation data. It is able to store custom items just like the profile itself that are called portlet items. These items are stored persistently on the user profile and reretrievable on further sessions of the same user, therefor being suitable to store long-lived settings/informations for the user.
Items on the portlet configurations may be stored in TMLScript using the object "portlet", which represents the current WebTML portlet for which the TMLScript code is run:
portlet.setItem("favcolor", "blue");
You do not need to trigger persisting changes to portlet items. This is done implicitly at the end of each request.
Another way is to use a WebTML form with source "portlet" to let the user enter data for the portlet configuration himself. On storing the WebTML form data using default action $store or TMLScript method tmlform.storeInPortlet() the inputs are stored to items of the portlet configuration.
<tml:form source="portlet" name="userconfig">
See navigator: <tml:input name="shownav" type="boolean"/>
...
<tml:button clickaction="$store">Save</tml:button>
</tml:form>
To refetch once saved items a portlet just as to read them using WebTML tag <tml:item type="portlet"/> or portlet.item() in TMLScript:
<tml:item type="portlet" name="shownav"/>
<tml:case condition="portlet.item('shownav') == true">
... navigator code ...
</tml:case/>
Portlet variables
Portlet variables are basically normal WebTML variables that are only visible for the current portlet. Therefor they do not influence code outside the portlet. Both "normal" WebTML variables with page scope and session variables are available. Set them using the WebTML attributes pvar and psessionvar in WebTML or methods portlet.setVar() and portlet.setSessionVar() in TMLScript.
<tml:range pvar="prerenderedCode">
....
</tml:range>
<tml:action id="changeColor">
portlet.setSessionVar("color", tmlparam1);
</tml:action>
Just as with normal variables they are retrievable via <tml:item> in WebTML and any varialbe retrieval functionality in TMLScript, for example this.item(). To explicitly retrieve a portlet variable you can also use portlet.getVar() or getSessionVar() in TMLScript.
<tml:item name="prerenderedCode"/>
<tml:script>
color = portlet.getSessionVar("color");
if (!color) {
color = "black";
}
</tml:script>
Portlet context
The portlet context is an optional way to control the WebTML context under which a portlet is rendered. Without a set portlet context the portlet is rendered under the context that the <tml:include> tag gave it, just like any other tag takes its context from the parent tag.
The portlet context can be set via attribute portletcontext available on all action link tags or via property portlet.context on
the portlet object. When a portlet context is set then the portlet is
automatically using the given WebTML context when it is rendered, no
matter what the context of the parent include is.
A set portlet context is kept for the current browser session, but only as long as the portlet mode does not change.
When the portlet mode changes then the portlet context is cleared to
prevent the new mode from malfunctioning, unless of course the portlet
context is again explicitly set while changing the mode. A portlet
context can also be cleared by setting attribute portletcontext to "none" or setting null to portlet.context. After the portlet context has been cleared the portlet will again be rendered under the context with which it was included.
See
the following example of WebTML code for a portlet mode "view", which
iterates over some documents and offers a link to edit each iterated
document. To accomplish this it sets a portlet context to the current
document and changes the mode to "edit", which will render a WebTML form
to modify the data of the current context document:
<tml:children context="name:docparent">
<li> <a href="<tml:url portletcontext="this" portletmode="edit"/>"><tml:meta name="title"></a>
</tml:children>
The following could be the code for mode "edit", a small WebTML form for editing document data, then two buttons to save the modifications or to cancel editing. Both buttons return to mode "view", but only the "save" button calls an action to store the modifications. On returning to mode "view" the portlet context will get cleared, so the "view" code will again have the correct context for its iterating code.
<tml:form id="editdoc">
Name: <tml:input name="name"/> <br>
Status: <tml:input name="status" type="select" options="Open|o,Closed|c"/>
<tml:button clickaction="$store" portletmode="view">Save</tml:button>
<tml:button portletmode="view">Cancel</tml:button>
</tml:form>