OpenWGA 7.11 - Guide for OpenWGA Content Manager
Content Manager Agents
A content management agent is a procedure, predefined in an applications design, that can be run from within content manager. It can offer a variety of functionality related to content management, for example modifying the currently selected content document in special ways.
An agent is always run the following way:
- While a document is selected and shown in content manager the author opens the OpenWGA Content Manager menu. If agents are available he will find a menu item Start Agent there. A submenu will offer each agent with an individual name.
- Clicking on an agent menu item will bring up the agent dialog. Here the agent can request certain input data for running the agent procedure. The agent "knows" about the document currently selected in Content Manager and can adapt dialog information to it, as well as the following agent procedure.
- The procedure then can be run by clicking the button Start Agent. Alternatively a button Cancel can be clicked which will just cancel agent execution.
- After the agent has been run the Content Manager UI may react in custom ways, like just closing the dialog or giving further information about the procedure result in it.
Defining agents
Content Managers are defined in an OpenWGA design by adding a system resources folder "wga/content-manager/agents" below the "tml/html" folder. Inside this folder each individual WebTML module will be used as a single agent.
The contents of the agent module defines both: The agent dialog as well as the agent procedure (or at least the part of the procedure that is directly triggered) in form of an WebTML action "run-agent":
The contents of the WebTML module is loaded as contents of a WebTML AJAX portlet. Note that no <tml:form> is necessary for input fields defined in the agent module, as the surrounding CM already defines a form. Also it is not necessary to render the "Run Agent" and "Cancel" buttons as these are provided automatically by Content Manager as well.
The agent module is rendered in the context of the currently selected page in Content Manager. So the operations offered by agents may be specific to this selected document.
On clicking "Run Agent" the action "run-agent" is called and may run any TMLScript operation that is defined there. It is also ran in the context of the currently selected CM page. Additionally it retrieves the selections in the agent dialog as tmlform object. The agent procedure may react and work with both.
The agent action should return boolean true if the agent dialog should just be closed after the action has finished. This will also trigger a reload of the currently selected page. It may return false if the agent dialog should remain open and be re-rendered. This can be used to display agent result information, like errors.
Tips & Tricks
Determining agent name
By default an agent in OpenWGA Content Manager menu is labeled by the name of the WebTML module that represents the agent.
Alternatively you can determine a specific WebTML label which is used instead for a display name. In label file "general.tmlscript" define a label "agent.<webtml-name>" which contains the display name to use. For example:
In file "files/labels_en/general.properties":
agent.that-agent=That agent
Manipulating the UI
Here are some JavaScript tricks how you can manipulate the Agent / Content Manager UI.
Hiding the "start agent" button
Your agent may not be able to run on any context document that is chosen. So you might want to disable the "start agent" button in certain situations when the agent dialog is run under an unappropriate context .
To do this you can render this little script in your agent dialog code:
<script>BI.dialog.submitButton.hide();</script>
This will hide the "start agent" button.
Closing the agent dialog manually
While you can force the agent dialog to close by returning true in your agent action there may be certain situations where you want to trigger the closing of the agent manually. This little script can do this:
<script>WGA.event.fireEvent("CMS_dialog_closed");</script>
Reload the CM explorer and choose a document to display
In case your agent creates documents you will want the Content Manager UI to show the new document(s) once the agent has run. For this you need to manually trigger the reload process:
<script>BI.se.reload();</script>
If you want a special document to be selected after the reload you can specify its struct key as first parameter. Most time you will calculate this from WebTML/TMLScript and also close the agent dialog after that. So a working example would be:
<script>
BI.se.reload('<tml:script expression="newDoc.getStructKey()"/>');
WGA.event.fireEvent("CMS_dialog_closed");
</script>