OpenWGA 7.5 - OpenWGA Concepts and Features
Design and development » WebTML » Features » PortletsPortlet modes
A WebTML portlet may be rendered in different modes. Your WebTML code inside the portlet decides what to display in each mode that your portlet is available in.
A mode typically represents a display and working state that the portlet is in. The default mode named "view" should display the portlet in its initial state. Other modes may be freely defined for the other states that the portlet needs to support. The mode of a portlet can be switched by WebTML action.
For example if your portlet displays some user preferences then the mode "view" might display the preferences readonly and offer a link to switch to mode "edit". This might be the code to be rendered in "view" mode:
User name: <tml:item type="profile" name="username"/>
Favorite color: <tml:item type="profile" name="favcolor"/>
<tml:button portletmode="edit">Edit</tml:button>
For the switch you can use <tml:url> together with attribute portletmode, which switches the mode of the current portlet after clicking the link. This attribute is available for all tags that are able to create action links (this usage of <tml:url> actually creates an action link which only performs the noop action "$refresh").
The set portlet mode is persistent for the current browser session. So the mode for a portlet is kept while the browser is open, even if the portlet is not rendered on every request.
In mode "edit" the portlet may want to offer a WebTML form to change those preferences and a button to save those changes while returning to mode "view". This may be the code that needs to be rendered:
<tml:form source="profile" id="editprefs">
User name: <tml:input name="username"/>
Favorite color: <tml:input name="favcolor" options="Blue,Yellow,Green"/>
<tml:button clickaction="$store" portletmode="view">Save</tml:button>
<tml:button clickaction="$refresh" portletmode="view">Cancel</tml:button>
</tml:form>
Deciding what code is to be rendered for which portlet mode is up to the code of the portlet module. There is no automatism that chooses the right code or module for each mode. So every designer can choose himself how the code of his portlet modes should be organized.
One way would be to just do a big <tml:select> in the portlet module, choosing the right code for each mode. Modes can easily be tested by another attribute portletmode available on condition tags, which tests for the given portlet modes:
<tml:select>
<tml:case portletmode="view">
... code for mode "view" ...
</tml:case>
<tml:case portletmode="edit,newdoc">
... code for modes "edit" and "newdoc" ...
</tml:case>
<tml:case portletmode="edit">
... code only for mode "edit" ...
</tml:case>
</tml:select>
However the recommended way for organizing code of portlet modes and portlets in general is the following
- Create a separate folder in WebTML module files for all modules of your portlet, for example "tml/html/portlets/userinfo"
- Have one central WebTML module file named "portlet.tml", which will be directly referenced by the portlet include. It holds the shared code that all modes use plus one central WebTML include which dynamically includes the code for the current mode as a separate module:
<tml:include ref="[::mode-{portlet.mode}]"/>
(If you are wondering about the "::" syntax see Local references. If you are further wondering about the brackets/braces meaning see Dynamic attributes)
- Have a separate WebTML module file named "mode-modename.tml" for each mode that the portlet supports
In OpenWGA developer studio there is a wizard creating all neccessary files for a new portlet in that way. Just navigate to the folder where the new portlet folder should be created. There click the "New..." button on the absolute left of the toolbar and choose the wizard for WebTML portlet. The wizard will ask you for a name of the portlet folder plus the modes that need to be supported. It then creates the folder, the central "portlet.tml" plus one WebTML module for every mode. Additionally a "form.tml" is created which may hold the definition of a WebTML form to be used in "edit" or "newdoc" modes.