How to Use a Custom Value Editor in the Rule Editor

Samples > Rule Studio Authoring Extensions > How to Use a Custom Value Editor in the Rule Editor

How to Use a Custom Value Editor in the Rule Editor

This sample shows how to associate a custom value editor with a data type (that is, a BOM class) and its lexical representation in Rule Studio's text and guided editors.

Key Features

Key features include:

Value editor
Value translator
Value descriptor
Swing control integration
Rule Studio extension points

Installing this Sample

This sample extends the Rule Studio API, and the required sample plug-ins are delivered as pre-deployed. If you have not already done so, you must install the samples extension site in Eclipse before running this sample.

To install the plug-in samples extension site:

Click Help > Software Updates > Manage Configuration.
In the Product Configuration dialog, click the Add an Extension Location link.
In the Browse dialog, select the following folder: <InstallDir>/studio/samples/eclipse folder.
If prompted to restart the Eclipse Workbench, click Yes.

Eclipse shuts down and restarts.

To check that the Value Editor Sample feature is enabled:

Click Help > Software Updates > Manage Configuration.
In the left pane of the Product Configuration page, expand C:\ILOG\JRules\studio\samples\eclipse and check that Value Editor Sample 1.0.0. is listed.

To import the valueeditor sample:

Click File > Import.
In the Import Wizard, select ILOG Rule Studio Samples and Tutorials.
Click Next.
On the Sample or Tutorial page, select the sample: samples > authoring > valueeditor.
Click Finish.

The sample project files are imported and displayed in the Rule Explorer.

Running this Sample

When you install this sample, a custom value editor, such as the ones provided for simple and full date representations, is added to Rule Studio. It demonstrates how to filter elements based on a pattern.

To test the custom value editor:

Open the valueeditor-rules > offer rule in the Guided Editor.
Click on #BFGHFDF in the condition part of the rule.

The custom value editor appears:

The top text input field is used to enter a pattern.
The left list is automatically filtered, based on the pattern you enter.
The right panel displays useful information about the selected item to help you find the best match in the list.
When you click OK or press Enter, the custom value editor disappears and the new value is processed.
If you press the Escape key, the custom value editor disappears and the old value is kept in the rule.

You can also access the custom value editor from within the Intellirule Editor:

Note

This kind of customization is also available in Rule Team Server, with just a few minor changes: you will need to use a Web component instead of the Swing component used in Rule Studio.

Source Files

All classes for this sample are located in the package ilog.rules.studio.samples.valueeditor, in an Eclipse plug-in with the same name.

The FilterValueEditor class extends ilog.rules.brl.ui.value.editor.IlrAWTValueEditor, which is needed to integrate the custom value editor in Rule Studio by extending the extension point ilog.rules.studio.model.brl.valueEditors.
The getValue and setValue methods are used to handle communication between the value editor integrated Swing component and the rule editors.
The getEditorComponent method returns the Swing component used by the value editor. It is called each time the component is displayed.
The FilterControl class is our Swing component class. We use the setValue and getValue methods to perform Input and Output operations in the Swing component:

setValue is used to pass an existing promotional offer code value, if any, which will ideally map an element of the filter list.

getValue is performed when the OK button is clicked or the Enter key is pressed. It returns the new promotional offer code value to display in the rule.

Depending on your Swing component, you can use any kind of methods in place of our setValue and getValue methods to perform the required I/O operations.

The FilterDataProvider class and its implementation, FilterDataProviderImpl, are used to populate the value editor list and its items descriptions. It is possible to make more complex implementations that include XML or database integration.

The value descriptor is used to transform values back and forth from the rule text to the value editor component. It is needed for representation and persistence purposes.

Here, we are using an existing value descriptor because our custom value editor deals with simple values that can be converted to an existing String type (ilog.rules.brl.String). We have also added a prefix decoration: #.

We could also have made a custom value descriptor by:

creating a class that implements ilog.rules.brl.value.descriptor.IlrValueDescriptor (or is more conveniently extending ilog.rules.brl.value.descriptor.IlrAbstractValueDescriptor) and is referenced in an extension of ilog.rules.studio.model.brl.valueDescriptors in your plug-in.
making a new lexical representation of our "promotional offer code" in the rules (# "<promotional offer>") is needed because Rule Studio is working with regular expressions in order to distinguish different types of values and to know how to persist and represent them.

You need to be careful with the regular expressions used in your value descriptors (getParsableRepresentation method) to avoid lexical collisions/conflicts with other existing data types.

Once your rule is written, you must associate a value translator to your data type (BOM class) to help Rule Studio convert your rule to its IRL representation.

In the sample, this is done using the FilterValueTranslator class, which is referenced in our extension of ilog.rules.studio.model.brl.valueTranslators in the plugins.xml file.

To make our extension work, FilterValueTranslator implements ilog.rules.brl.translation.codegen.IlrValueTranslator.

The "promotional offer code" is translated into IRL by an instantiation of the sample.PromotionalOffer class. You can examine the translateValue method.

To display the source code of the valueeditor Eclipse plug-in:

Click File > Import.
In the Import Wizard, select External Plug-ins and Fragments and click Next.
In the Import As section, select the Projects with source folders option and click Next.
In the Plug-ins and Fragments Found list, scroll down and select the ilog.rules.studio.samples.valueeditor plug-in (be careful not to select ilog.rules.studio.samples.valueeditor.source), then click Add.
Click Finish.

The plug-in source code is imported and appears in the Rule Explorer.

Switch to the Plug-in Development perspective. In the Package Explorer, navigate to the Java source files.

Highlights

Open the model BOM entry in the valueeditor-rules project and navigate to the PromotionalOffer class inside the sample package. A few custom properties are set on this BOM class.

The properties are used to: