In this tutorial I will show how to create custom components and controls for IBM Maximo system. The presentation XML of any application consists of tag elements which are controls. The control is an object that enables user interaction or input, often to initiate an action, display information, or set values. The control is based on one or more components linked together. In other words, the component is part of the control. At the beginning of this article I’ll tell you how to register new components and controls, which files to modify and then we go through the steps of creating progress bar control using the Twitter Bootstrap framework.
Definition of metadata
The development of any component or control begins with the definition of its metadata. The IBM Maximo system stores metadata in the component-registry.xml and control-registry.xml files. These files are located at the admin. station where IBM Maximo was installed:
applications\maximo\properties\component-registry.xml applications\maximo\properties\control-registry.xml
Contents of component-registry.xml file
In the component-registry.xml file the component descriptor registers. A component descriptor describes the properties of a component. By defining component properties, you can modify certain aspects of its appearance and behavior. Component gets the necessary values for initialization through the properties.
A component descriptor can have an instance-class as a tag parameter. The framework has two classes that can be used as an instance class:
- ComponentInstance
- BoundComponentInstance
If your component will be associated with an attribute of a MBO object, then you should use BoundComponentInstance class as an instance class.
Contents of the control-registry.xml file
The control-registry.xml file defines a control descriptor. A control descriptor used to register a component list and a list of containers inside which the control can be added through the Application Designer application.
Step-by-step instructions for creating a progress bar control
In this part of the article I’ll show how to create a progress bar control for IBM Maximo.
Registering component in the component-registry.xml
First of all we need to register a component and it’s properties in the component-registry.xml file. To do this open XML file, scroll to the bottom and add a component-descriptor tag with the following attributes:
| Attribute | Value |
| name | progressbar |
| instance-class | ${package}.controller.BoundComponentInstance |
On the next step it’s necessary to define the properties that will be supported by our component. All the properties should be registered inside the property-list tag. Here is the property list:
- jsp-filename – property to set a JSP file name
- defaultrender – property to set a render option
- id – property to set a unique identifier of the element
- visible – property to change a visibility state of a component
- dataattribute – property to set an attribute of MBO object (persistent/nonpersistent)
- color – property to set a color of the control
- striped – property to turn on/off striped effect
- labeltext – property to set a text of the label
The property defaultrender is frequently used by the standard Maximo components. If the property is initialized with the true value, then on a page the component will be wrapped in additional div container with bc class. The bc class has one of the most important CSS property for controlling layout. It sets display property with inline value. When page renders, an inline element does not start on a new line and only takes up as much width as necessary.
Below is an example of a property declaration:
<property-list>
...
<property name="striped" type="xsd:boolean">
<default-value>false</default-value>
</property>
...
</property-list>
Registering control in the control-registry.xml
Now we need to register the progress bar control in the control-registry.xml file. Registration of control begins with the insertion of the control-descriptor tag:
<control-descriptor name="progressbar">
...
</control-descriptor>
Inside the control-descriptor tag we should put the component list. Because our control will have several components, we need to wrap them into a components tag. The container will have a horizontal layout, so the components will be rendered in one row:
<component-list>
<components id="${name}_components_v" layout="vertical">
<components id="${name}_components_h" layout="horizontal">
<label id="${name}_label" dataattribute="@{dataattribute}" title="@{labeltext}:" align="right" labelalign="@{labelalign}" hidewhen="@{labeltext}==null" labelfor="${name}_progressbar" />
<progressbar id="${name}_progressbar" dataattribute="@{dataattribute}" striped="@{striped}" color="@{color}" maxvalue="@{maxvalue}" />
</components>
</components>
</component-list>
As a final step we need to define the container list. It’s a list of elements that can hold the progress bar control as a child element:
<containers>
<container name="dialog" />
<container name="section" />
<container name="sectioncol" />
<container name="tab" />
<container name="tablecell" />
<container name="tablecol" />
<container name="tabledetails" />
</containers>
Adding CSS styles to the maximo.css file
Since the progress bar control will use some CSS styles of the Twitter Bootstrap framework, you need to extract the necessary styles and add them to the maximo.css file. To facilitate this task, you can use the style generator, which is available on the official Bootstrap website:
http://getbootstrap.com/customize/
Follow the steps to generate a minified CSS file:
- Go to Customize and download page
- Click the Toogle all button to remove all the checkmarks in the Less files section
- Check the Progress bars checkbox
- Click the Toogle all button to remove all the checkmarks in the jQuery plugins section
- At the bottom of the page, click the Compile and Download button to download the bootstrap.zip archive.
Unpack bootstrap.zip archive and open the file css/bootstrap.min.css. Copy and paste the contents of the file into maximo.css. Please note that Maximo has several skins for changing the appearance of pages. According this the path to the maximo.css file may differ a little. Here is a quick solution to check what the skin Maximo is using right now (for Maximo 7.5+ only):
- Login to Maximo with the maxadmin rights
- Go to the System Properties application:
Go To → System Configuration → Platform Configuration → System Properties - In the Global properties table search for the mxe.webclient.skin property. In the Global Properties Details check the value of the Current Value field
Thus, the path to the file will be as follows (where {@skin} – name of a skin):
applications\maximo\maximouiweb\webmodule\webclient\skins\{@skin}\css\maximo.css
Creating a JSP file
It’s time to create a JSP file for our control. The name of the JSP file must match the value of the jsp-filename property that was defined in a property list of the component descriptor:
<property name="jsp-filename">
<default-value>progressbar</default-value>
</property>
The progressbar.jsp file should be created inside the components folder:
applications\maximo\maximouiweb\webmodule\webclient\components
Because our control will display the current value of the MBO attribute on a progress bar line, we should include componentheader.jsp file on the first line of our JSP file. The componentheader.jsp file has an instance of the BoundComponentInstance class where the getString() method is implemented. The getString() method returns the value of the attribute that was specified as a value of the dataattribute property. If a non-existing attribute was specified, the method returns the Invalid Binding string.
Furthermore the BoundComponentInstance class implements methods that can be useful in developing custom components and controls:
- getProperty() – returns the current value of a property
- isRequired() – used to check if a field is required to fill in by user
- isPasswordField() – used to check if a field has input mode Password (field with asterisks)
- isReadOnly() – used to check if a field is read only
- isQuery() – used to check if a field has input mode Query (field with additional rules)
In JSP file we need to define an HTML control template that will be rendered on the page. Below is the structure of the template that was taken from the Bootstrap documentation:
<div class="progress">
<div class="progress-bar" role="progressbar">...</div>
...
</div>
The full listing of the progressbar.jsp file you may find in the progressbar_control.zip archive which can be downloaded from the Source Code section.
How to apply changes?
For the changes to take effect you need to rebuild and redeploy maximo.ear file.
Usage example
Export application definition using Application Designer and add the following code to the XML file:
<section id="pg_control_1_container" label="Workflow Progress">
<progressbar dataattribute="{@attr}" id="pg_control_1" striped="false" color="progress-bar-success"/>
</section>
Then replace {@attr} stub with a name of the MBO attribute. And finally import XML file back to Maximo.
Conclusion
I hope that this article was useful and you learned the basics of developing custom components and controls for IBM Maximo system. In the next article, I’ll show how to add a custom control to the Application Designer’s palette.
Source code
Useful links