ShowTable of Contents
Container Custom Actions
When using a container, a composite application assembler can instrument an existing application, like a web application, terminal emulation session, or a notes document, with input and output properties. When one of these instrumented properties are triggered (a property change event for input properties, or a field on the existing application for output properties) a set of actions can be configured for that property. The default actions provided by the container infrastructure are receive and publish.
Assemblers have requested the ability to add their own actions to the container framework so that they can perform other functionality during the property trigger. For example, assemblers using the web container configured for google can instrument the page to update the search field by creating a setSearchField property. In many situations, just setting the search field is not enough; the assembler would like to perform some presentation micro flow. In this case, the assembler would also like to submit the search after the field was updated.
Since there is so much variation on how web application developers perform this search, submitting a form, clicking a button, performing some javascript function, etc. different actions are required. This is where container custom actions are leveraged. They allow a third party to extend the container infrastructure by creating a small java class which performs specific action functionality. These container custom actions are shareable for all containers they were configured to support. Since they are shareable by all the instances of the containers, they are by default stateless.
Other container custom actions have been created as well. Min, Max, … custom actions have been created for the notes view container, EnterKeys, MoveToPos, … have been implemented for the HOD container, and submitForm, executeJS, … have been created for the browser container. These custom actions are developed to the specific container they support, however you can also develop their own custom container actions. A custom container action allows developers to create actions for specific container types independent of the containers themselves.
There is a project underway to have these custom actions available on the OpenNTF site. The OpenNTF site can act as a central repository for developers to have their contributions available for consumption and for assemblers to obtain these contributions for consumption in their composite applications.
Actions consist of an definition, actionConfiguration, and run time element, java class, which is leveraged both at execution and assembly. First, we will look into the actionConfiguration extension point which is a way you define your custom actions and let the runtime know of the custom actions. We will briefly go over available attributes for this extension. Secondly, we will look into the base com.ibm.rcp.composite.container.core.Action class since this is the class you would be extending to provide your custom action logic. Since this article only provides introduction to custom actions, we will not discuss any implementation specific steps here. The detailed step-by-step tutorials can be found in the referenced articles.
Following steps need to be performed in order to develop and use the custom actions:
- Define your action in the plugin.xml file via the actionConfiguration extention point
- Implement your Action class by extending the com.ibm.rcp.composite.container.core.actions.Action
- Make use of the Custom Actions when assembling composite applications using the toolbar or the landmark configuration page
So now let's take a look at the actionConfiguration extension point.
The actionConfiguration extension point
For you to associate custom actions to any of the container types, you must specify the actionConfiguration extension point. These custom actions allow you to extend the action set that the assembler can use to define a container instance. Here is an example use of the extension point:
Let's take a look at its elements and attributes to understand what they are and how they are used.
As shown in Image 1, the value
com.ibm.rcp.composite.container.core.actionConfiguration of the point attribute of the extension element indicates that we are extending the com.ibm.rcp.composite.container.core.actionConfiguration point.
Elements/Attributes | Description |
|
|
It can contain minimum of one to many action elements.
|
|
|
This is the action element. It has/can have the following attributes.
|
|
|
This is the unique id for this action. It is used to identify the actions. It is a required attribute.
|
|
|
Human Readable name. It is shown in the tooling to display this action It is a required attribute.
|
| help | The help that will be shown to the user when the user hovers over the action. It is an optional attribute. |
| class | The custom action class provided by the developer. The implementation of this class must extend the com.ibm.rcp.composite.container.core.actions.Action. |
| type | Fully qualified name of the top level container that the action is targeted for. Following are the the system provided containers that one can provide custom actions for:
com.ibm.rcp.composite.container.core.AppContainer
com.ibm.rcp.composite.container.browser.BrowserAppContainer
com.ibm.rcp.composite.container.symphony.SpreadsheetContainer
com.ibm.notes.view.container.NotesViewContainer
com.ibm.notes.document.container.NotesDocumentContainer
The actions are scoped in a hierarchy. That means custom actions targeted for the parent can be applied to all its children and the ones targeted for the children can only be applied to its children. So for the case, the custom actions targeted for the com.ibm.rcp.composite.container.core.AppContainer will be applicable to all the container types since it's the parent of all the containers. |
| data | 0 - 1 data tables. 0 occurrence means this action will not support any data. |
| dataelement | A key/value pair for the data. There can be 0 to n occurrence of the data element. This is data you would like to pass to you Action class. This can be data you would want your assembler to provide for this action. It can be initial configuration data to - such as information about database server, port, URL, etc. |
The abstract Action class
In order for you to extend the container's default functionality, you need to implement a custom action for that container by extending the abstract
com.ibm.rcp.composite.container.core.actions.Action class. Following are some of its methods of interest when developing your actions.
The excecute method
public abstract void execute(AppContainer container, LandmarkEvent event, Object context);
This is THE method to implement when you are developing your custom actions This is where you would want to provide your enhancement to the containers you are extending. This method is called by the CA framework for any event that an assembler has configured this action with. Since the custom actions are shared by all the instances of the containers, it is stateless by default.
Let's look at some of the basic things you could do. Let's say you wanted to have your action perform a translation of the property value and then republish the property with the translated value. You can write a simple action as shown in the sample below: Examine how we retrieve the property value and then republish it.
public void execute (AppContainer container, LandmarkEvent event, Object context) {
BrowserAppContainer c = (BrowserAppContainer)container;
String value = null;
// this.property gives you the name of the property and if you wanted the value for the property
// you can get it from the container using the getPropertyValue method and passing the property name.
value = (String)c.getPropertyValue(this.property);
// This is our way of translating the value... :-) ..but you get the point.
String newValue = value + " (Translated!)";
// Now republish the modified property value back
BrowserAppContainer )container).publishProperty(this.property, newValue);
}
Since the above action is written for the BrowserAppContainer, you can use the browser container's tool bar to configure your landmark, action and the property as shown below.
There are other useful methods provided by the containers that you can use from your custom action class. Let's say want to provide custom actions that pre-populates a field with the property value or get the values of those fields. You can use the setField and getField methods of the container. Here is an example usage:
public void execute (AppContainer container, LandmarkEvent event, Object context) {
BrowserAppContainer c = (BrowserAppContainer)container;
String value = null;
// this.property gives you the name of the property and if you wanted the value for the property
//you can get it from the container using the getPropertyValue method and passing the property name.
value = (String)c.getPropertyValue(this.property);
// This is our way of translating the value... :-) ..but you get the point.
String newValue = value + " (Translated!)";
// set the translated value for the field id:trtxt or what that may be.
((BrowserAppContainer)container).setField(newValue, field ,event, context);
}
The getSuggestedFields method
public List getSuggestedFields(AppContainer container, String lmi, String landmark);
If the action is aware of a subset of fields it can utilize the the
getSuggestedFields method. This method should return a list of suggested fields from which a field can be associated with this action. The action can dictate which fields show up as selectable fields in the user interface for any tooling for this component. The default implementation simply invokes the
getSuggestedFields method from the container. You can decide to filter certain fields based on the actions. For example, If you are extending the BroserContainer to provide the submit action for a search field, you may not want to provide all the fields of the entire DOM. You may want filter the fields to display only the submit action related fields. This method also takes in a landmark identifier and a landmark to further enable any filtering of fields to be made available based on the landmark.
The getData method
This method allows access to the dataelement key/value pair for this action. You can specify the default key/value pair in the actionConfiguration extension. An assembler can update it's value in CAE when configuring the actions either via the container's toolbar or landmark configuration page.
Using the new action in CAE
Actions need to be installed in the client so it can be leveraged by an assembler. The suggested way to do this it to package it in a feature, and include the feature in the .ca file. Once installed into the Notes or Expeditor, assemble can use this action in any landmarks you define for applicable container types. The actions can be accessed via the container 's toolbar or the landmark UI page. Lets take a look at both of the options:
Configuring the action from the Landmark toolbar
The toolbar allows you create new landmarks that can leverage your custom actions. All of your custom actions can be accessed via the Select Action drop down selection field on the container's toolbar. This drop down would list both of the default actions (Publish and Receive) as well as your custom actions that pertain to this container. Right next to the Select Action drop down field, you notice a Table icon which is the edit action parameter icon. , this icon would only be displayed, if there is one or more dataelement is defined in the actionConfiguration extension point definition. Clicking on this table icon would present a Parameters Selection dialog which would allow you to edit the values of the parameter as well as add new action parameters for this action. Of course, any new action parameter added here would not be recognized by the custom actions unless you have made the actions aware of these parameters.
Configuration the action from the landmark UI
You can also access and configure your actions via the Landmarks UI tab. You can access the landmark UI tab from the Edit Component Properties dialog for the container. Assembler would want to use the tab to edit the landmarks created via the toolbar.
Conclusions
In this article, we have learned what custom actions are and when they can be used. We also covered basic building blocks of creating and using custom actions by learning about the actionConfiguration extension point, abstract Action class and its important methods, and accessing the action inside the CAE. To instrument your own custom actions for the containers, refer to the tutorials in the Resources sections.
Resources
Creating custom actions in java
Create a custom container action that executes JavaScript
Extending the Notes View Container with a "Run Agent" custom action
Extending the Notes View container with a custom action