How to Customize the Rule Team Server User Interface

Samples > Rule Team Server Authoring Extensions > How to Customize the Rule Team Server User Interface

How to Customize the Rule Team Server User Interface

This sample shows how to customize the Rule Team Server user interface to provide convenient access to key features for different users, depending on their profile, and a personalized look & feel. These changes will make it possible to:

View the content of the BOM in a custom BOM tab available to Admin users only.
View the verbalization navigation/action templates defined in the BOM in a custom Category tab available to all users.
Move rules from one package to another using a custom drop-down list and toolbar button in the Explorer tab.
Customize the Rule Team Server Home tab, and make it different according to the user group.
Show how to change the current project in one click on the Home tab.
Show how to have direct access to an action rule.
Customize the Edit button so that it does a quick edit action.

Key Features

Key features in this sample include:

Accessing the graphical model through the ManagerBean class (entry point for extending the graphical user interface)
Adding a button to the Rule Team Server toolbar
Adding a tab in the Rule Team Server UI
Restricting access to a tab to specific users
Retrieving BOM information such as classes, fields, and methods
Retrieving verbalization templates
Redefining standard Rule Team Server tabs
Redefining Rule Team Server command actions
Using page templates to write custom pages in the tabs
Using the permalink API to access projects and rules

Installing this Sample

To install this sample through the Samples Console:

Go to the Samples Console and locate the teamserver > servercustomui sample.
Check that the Samples Server is started. For information on how to start and stop the Samples Server, see Stopping and Restarting the Samples Server from the Samples Console.
Execute the repack command to compile and repackage the application into a new deployable EAR.
Execute the deploy command to deploy the new EAR.
Wait for the Java EE application to start before continuing. The following message will be displayed:

Application ready. You can now sign in to Rule Team Server.

Running this Sample

This sample can only be opened and run in the Samples Console.

Because this sample shows examples of customizing, you should already be familiar with Rule Team Server. If you are not, follow the Rule Team Server Tour by clicking the link at the bottom of the Home page once you have signed in.

How to See the Customized Home Page and Direct Access Link

To see the customized Home page and direct access link:

Username: rtsUser1

Password: rtsUser1

In the Home page, select the loanvalidation-rules project.

The customized Home page displays the list of the latest modified rules to all users except the Administrator, who sees the list of projects instead (more later).

Click the Explore tab.
Click the Validation > Borrower package.
In the table, select the checkAge rule.
Click Edit.

Notice that this accesses the Rule Editor directly and that the other steps of rule editing are no longer available.

Change the value of maxAge to 130.
Click Save.
Click on the Home tab.

Notice how your saved rule appears in the list.

Click on the checkAge link.

The rule details are displayed directly.

How to See the Custom Tab and Toolbar

This sample also shows a custom tab displayed to all users, as well as a new button in the toolbar.

To see the new tab and toolbar:

Click the Category tab.

All verbalization templates are displayed as a list sorted by category and showing the class name, the member, and the template. The list can be filtered by selecting a specific category in the Category list box.

Click the Explorer tab.

Notice the custom drop-down list and Move button in the toolbar. The Move button enables packages to be moved up or down a level, or to the previous or next sibling package.

Click the Validation > Borrower package.
In the table, select the checkAge rule.
In the selection list, choose Up, and then click Move.

The checkAge rule is moved to the Validation package.

Click the Validation package.

The checkAge rule is listed in the table.

In the table, select the checkAge rule once again.
In the selection list, choose Down and click Move.

The rule now is now back in the Borrower package.

Sign out by clicking Sign Out in the top right corner.

How to See the Home Page and Added Tab for Administrators

The Home tab has been customized and made different according to the user group.

To see the Home tab and added tab for Administrators:

Username: rtsAdmin

Password: rtsAdmin

The Home page proposes the list of projects. The current project is shown with a check mark on its left. When you click on a project name, it becomes the current project.
Click on loanvalidation-rules to make it the current project.
You have now 2 more tabs: Category, which is available to all users, and BOM, which is only available to Administrators.
Click the BOM tab and expand the tree view by clicking loan > Borrower.

Three sub-items are displayed:

fields: which holds loan.Borrower fields

methods: which holds loan.Borrower methods

types: which holds the inner classes of the loan.Borrower class

Expand the fields tree item and click the age field.

The details of the field are displayed to the right.

How to See a Custom Look&Feel

Two choices are proposed by default for the global look&feel (skin) of Rule Team Server: Classic or Mozilla. In this sample, a custom skin has been added.

To see the custom look&feel:

Click Options at the right in the top banner.
Click Edit Display Options.
Open the Select a theme list box.

Notice that a custom skin is now available.

Select skin.customskin.
Click OK.

The top banner and footer background color have changed to black.

Sign out by clicking Sign Out in the top right corner.

Source Files

This sample is located in <InstallDir>/teamserver/samples/servercustomui.

The sample is based on the Sun JSF framework. A typical JavaServer Faces application includes one or more backing beans (JavaBean components associated with UI components used in a page). A backing bean defines UI component properties, each of which is bound to either a component's value or a component instance. A backing bean also defines methods that perform functions associated with a component. In this sample, the beans feed the model that will be displayed and handle navigation.

The JSP files are in the /WebContent directory:

WebContent/custom - Contains files redefined from Rule Team Server:

home.jsp - The new Home page. It describes the middle part of the page without the top banner or footer.
tabs.jsp - Describes the list of tabs.
tableToolbar.jsp - Describes the toolbar provided above the table in the Explore tab, used to interact with the elements listed in the table.

WebContent/custom/extensions - Contains the new page definitions. Each new page has two description files:

<extension>page.jsp - The page itself, named bompage.jsp in this sample. It contains the teamserver:page tag that defines the page, giving the location of another JSP file as its content.
<extension>contents.jsp - The contents of the page, named bomcontents.jsp in this sample. It describes the page without the top banner or footer.

The beans are declared in WebContent/WEB-INF/extended-faces-config.xml.

MyTableToolbarBean.java - The backing bean extends the Rule Team Server bean TableToolbarBean and redefines the edit action.
ProjectsBean.java - The backing bean for the list of projects displayed in the Home page:

getProjects() - Returns the project list. The projects in the list are instances of ProjectHandle. They are directly used in the home.jsp page.
getHasProjects() - Recomputes the list, calling the Rule Team Server API in the computeProjects() internal method. It returns true if there is at least one project.

RulesBean.java - The backing bean for the list of rules displayed in the Home page:

getRules() - Returns the rule list. The rules in the list are instances of RuleHandle. They are directly used in the home.jsp page.
getHasRules() - Recomputes the list, calling the Rule Team Server API in the computeRules internal method. It returns true if there is at least one rule.
getNumberOfDaysBefore() - Returns a list of items to be displayed in a JSF list box to choose the number of days for which rules are considered recent.
getNumberOfRules() - Returns a list of items to be displayed in a JSF list box to choose a number of rules.
setNumberOfDaysBefore(String str) - Sets the Rule Team Server user parameters for the number of days.
setNumberOfRules(String str) - Sets the Rule Team Server user parameters for the number of rules to be displayed.

QuickEditBean.java - The backing bean that manages the custom quick editing. It uses the Rule Editor web component:

printRuleEditor(HttpSession session) - Displays a rule in the Rule Editor. The rule is locked before being edited.
save() - Saves the contents of the editor and unlocks the rule. It returns a JSF navigation string that brings you back to the Explore tab.
cancel() - Unlocks the rule. It returns a JSF navigation string that brings you back to Explore tab.

BOMTreeBacker.java - The backing bean for the tree that displays the BOM classes, fields, methods, and their details. It is used in servercustomui/WebContent/custom/extensions/bomcontents.jsp:

getTreeData() - Called to feed the treeview model. See the value attribute of the t:tree2 tag in servercustomui/WebContent/custom/extensions/bomcontents.jsp.
updateFormData(ActionEvent event) - Called to feed the detail information of the selected field or method. See the actionListener attribute of the h:commandLink tag with the id memberlink in servercustomui/WebContent/custom/extensions/bomcontents.jsp.

CategoriesBacker.java - The backing bean for the list displaying the verbalization templates. It is used in servercustomui/WebContent/custom/extensions/categorycontents.jsp:

getCategories() - Used to fill the list box. See the value attribute of the f:selectItems tag with id categorySelectItems in servercustomui/WebContent/custom/extensions/categorycontents.jsp.
getList() - Used to fill the list. See the value attribute of the t:dataTable tag with id data in servercustomui/WebContent/custom/extensions/categorycontents.jsp.
setCategory(String category) - Used to set the current category. See the value attribute of the h:selectOneMenu tag with id selectCategorie in servercustomui/WebContent/custom/extensions/categorycontents.jsp.

MoveBeanBacker.java - The backing bean for moving rules from package to package. It is used in servercustomui/WebContent/custom/tableToolbar.jsp:

setMoveaction(String moveaction) - Used to set the current action. This action will be triggered when the user clicks the Move button. See the value attribute of the h:selectOneMenu tag with id selectAction in servercustomui/WebContent/custom/tableToolbar.jsp
move() - Used to execute the move action. See the action attribute of the h:commandLink tag with id movecommand in servercustomui/WebContent/custom/tableToolbar.jsp.
getMoveactions() - Used to fill the list box next to the Move button. See the value attribute of the f:selectItems tag with id selectActions in servercustomui/WebContent/custom/tableToolbar.jsp.

Filter.java - A class helper defining and filtering BOM classes that are candidates to be displayed.
RuleHandle.java and ProjectHandle.java - Classes to handle the information displayed on the page about the projects and the rules.
WebUtil.java - A utility class to redefine the editing command.

Highlights

The highlights of this sample are described in the following sections.

Adding a Button to a Rule Team Server Toolbar

The Move button is added to the toolbar by adding a teamserver:button tag in servercustomui/WebContent/custom/tableToolbar.jsp. This file describes all the toolbar buttons. When the user clicks on the button, the MoveBeanBacker.move method is called.

Note that MoveBeanBacker is a bean with a session scope, which means that there is one instance per user session. This way, the list box choice persists during the user session since it is kept as an attribute of the bean.

Adding a Tab in Rule Team Server

The file servercustomui/WebContent/custom/tabs.jsp describes all the tabs. Each tab is described using the teamserver:tab tag. Descriptions of the tags are available in jrules-teamserver-web-JBOSS40.war/WEB-INF/teamserver.tld.

Handling Access Rights to a Tab in Rule Team Server

In the file servercustomui/WebContent/custom/tabs.jsp, you will notice the rendered attribute for the BOM tab. Here we used the Manager backing bean to check whether the current user is an administrator or not. The tab is displayed only if the Manager.administrator field value is true.

Defining a New Page in Rule Team Server

The teamserver:page tag is used to define the location of the contents of a JSP file describing a new page without the top banner and the footer since these are added by Rule Team Server. The content is included in a JSF tag. All HTML tags, such as table, div, and so on, should be surrounded by <f:verbatim> </f:verbatim> to be correctly interpreted. For example, WebContent/custom/extensions/bompage.jsp gives the location in teamserver:page and WebContent/custom/extensions/bomcontents.jsp describes the contents of the page.

Redefining a Page in Rule Team Server

The Home page is redefined simply by adding, in the /custom directory, a file home.jsp describing the page contents. The top banner and the footer are added by Rule Team Server. In this sample, the new page is made of two panel groups with different rendering: the projects part is shown only when the user belongs to the Admin group and the rules part is shown when the user does not belong to the Admin group.

Redefining an Action in Rule Team Server

The edit action is redefined by extending the TableToolbar bean. This extension is declared to be the managed bean class of TableToolbarBean in WebContent/WEB-INF/extended-faces-config.xml. The constructor of this class redefines the command associated with the edit method (see src/ilog/rules/rts/samples/util/WebUtil.java). This command returns the navigation string quickeditpage described in WebContent/WEB-INF/extended-faces-config.xml:

<navigation-case>
<from-outcome>quickeditpage</from-outcome>
<to-view-id>/custom/extensions/quickeditpage.jsp</to-view-id>
</navigation-case>

The quickeditpage is a custom page defined using the teamserver:page tag. Its content is described in WebContent/custom/extensions/quickeditcontents.jsp. It calls QuickEditBean to display, save, or cancel the Rule Editor web component. You can find more information about this component in the How to Use Web Components for Rule Editing sample.

Using Permanent Links

Permanent links give direct access to projects or rules. They are used as the URL associated with the project or with the rule on the custom Home page. See the IlrPermanentLinkHelper API for more information.

Changing the Rule Team Server Skin

A new customskin directory is added in the web/skins/ directory. This directory contains the files that define the new customskin skin. The css subdirectory contains the CSS style sheet, and the images subdirectory contains the images used by the skin.

The skin is declared in WebContent/WEB-INF/extended-faces-config.xml. The customskin is configured in the customSkins property of the SkinBean bean. This customized skin has been set as default for the following user types:

administratorSkin
configManagerSkin
defaultUserSkin

Handling Navigation of Customized Tab Pages

The action attribute of the teamserver:tab tag in servercustomui/WebContent/custom/tabs.jsp is a navigation string on the page describing the tab. It is defined in WebContent/WEB-INF/extended-faces-config.xml. For instance, the BOM page is described with an action string bompage. This navigation string is described in the navigation rule part of extended-faces-config.xml as:

<navigation-case>
  <from-outcome>bompage</from-outcome>
  <to-view-id>/custom/extensions/bompage.jsp</to-view-id>
</navigation-case>

So a click on the BOM tab navigates to the /custom/extensions/bompage.jsp page.

Rebuilding this Sample

To rebuild this sample:

Execute the build command to compile the code.
Execute the repack command to repackage the Rule Team Server EAR.
Execute the deploy command to put the modified EAR in the deploy directory of the JBoss directory included in the ILOG JRules distribution.

To return to the original Rule Team Server EAR:

Stop the server.
Remove the following directories:

<InstallDir>/shared/tools/jboss/server/jrulessamples/work/jboss.web/localhost/teamserver

<InstallDir>/shared/tools/jboss/server/jrulessamples/tmp

Copy <InstallDir>/teamserver/applicationservers/jboss40/jrules-teamserver-JBOSS40.ear to <InstallDir>/shared/tools/jboss/server/jrulessamples/deploy.
Restart the server.

Related Concepts

Rule Model API

Related Tasks

Customizing Rule Team Server

Customizing the Rule Team Server GUI

Implementing the Session Controller

Completing the Installation Using Ant Tasks