How to Declare an Interactor and Connect it to the Equipment View Component

The following example shows how to declare a predefined interactor (the pan interactor) in the JSP page and connect it to the equipmentView component so that it is always available.

  <!-- Declare the predefined 'pan' interactor -->
  <jvf:panInteractor id="pan" />
 
  <jvtf:equipmentView id="myEquipment" 
                      context="#{contextBean}"
                      style="width:740;height:550" 
                      interactorId="pan" 
                      project="data/myProject.itpr" />

In this example, the predefined panInteractor is declared. A unique identifier is associated with it ("pan"). Then, the interactorId tag attribute of the equipmentView component specifies the interactor to be connected to the equipment view.

How to Associate Interactors with Image Buttons in the Equipment View Component

Usually many interactors are made available in a web application. The following example shows how to declare multiple predefined interactors and how to use image buttons to make them active. Note that only one interactor can be set in the equipment view component at a time. Whenever a new interactor is set, the previous one is removed.

  <!-- Declare the predefined 'select' interactor -->
  <jvtf:selectInteractor id="select" />
 
  <!-- Declare the predefined 'pan' interactor -->
  <jvf:panInteractor id="pan" />
 
  <!-- Create a 4 columns grid -->
  <h:panelGrid columns="4">
 
    <!-- Declare a button for selection -->
    <jv:imageButton onclick="myEquipment.setInteractor(select)"
                    buttonGroupId="interactors"
                    image="images/arrow.gif"
                    rolloverImage="images/arrowh.gif"
                    selectedImage="images/arrowd.gif"
                    title="Select Interactor"
                    message="Select Interactor" />
 
    <!-- Declare a button for panning -->
    <jv:imageButton onclick="myEquipment.setInteractor(pan)"
                    buttonGroupId="interactors"
                    selected="true"
                    image="images/pan.gif"
                    rolloverImage="images/panh.gif"
                    selectedImage="images/pand.gif"
                    title="Pan Interactor"
                    message="Pan Interactor" />
 
    <!-- Declare a button for zooming in -->
    <jv:imageButton onclick="myEquipment.zoomIn(true)"
                    image="images/zoom.gif"
                    rolloverImage="images/zoomh.gif"
                    selectedImage="images/zoomd.gif"
                    title="Zoom In" 
                    message="Zoom In" />
 
    <!-- Declare a button for zooming out -->
    <jv:imageButton onclick="myEquipment.zoomOut(true)"
                    image="images/unzoom.gif"
                    rolloverImage="images/unzoomh.gif"
                    selectedImage="images/unzoomd.gif"
                    title="Zoom Out" 
                    message="Zoom Out" />
  </h:panelGrid>
  <jvtf:equipmentView id="myEquipment" 
                      context="#{contextBean}"
                      style="width:740;height:550" 
                      interactorId="pan" 
                      project="data/myProject.itpr" />

This example defines two predefined interactors:

Two buttons are declared to connect the interactor to the equipment view component. The buttonGroupId tag attribute is used to group image buttons so that only one button of the group is selected at a time. The selected attribute is used to specify which button should be made selected when the page is loaded. This should correspond to the interactor initially connected to the equipment view with the interactorId tag attribute. In this case, the pan button is selected (select="true") and the pan interactor is connected to the equipment view (interactorId="pan").

If you have started the bundled Tomcat web server, the following link will take you to the small sample illustrating this:

You will find more information about the sample web application in:

where <installdir> stands for the directory where ILOG JViews TGO is installed.

The selectInteractor Faces Component

This interactor has the following limitations in terms of handling events:

Client-side interactions are converted into the following mouse events, dispatched to the appropriate interactor:

How to Declare the selectinteractor Faces Component for the Equipment View

<jvtf:selectInteractor id="select" />

Configuring the selectInteractor

The cursor, lineWidth and lineColor tag attributes control the look of the interactor when it is activated, they do not affect its functionality.

If you have started the bundled Tomcat web server, the following links will take you to the small samples illustrating this:

You will find more information about the sample web application in:

where <installdir> stands for the directory where ILOG JViews TGO is installed.

Configuring Action Listeners for the Select Interactor Component

Action listeners are responsible for processing the interactions performed with the select interactor component. Their default behavior is to convert the interactions into server events dispatched to the IltSelectInteractor. It is possible to override this behavior by adding action listeners to the component.

Unlike in the regular equipment Swing component, it is not possible to declare view interactors through a CSS file. Instead, in the equipment faces component, the view interactors are declared within customized action listeners added to the selectInteractor faces component.

As the selectInteractor extends the JavaServer Faces UICommand, it allows one or more action listeners (implementing javax.faces.event.ActionListener) to be registered to receive events (javax.faces.event.ActionEvent) whenever a user interaction is performed. For the ActionEvent API there are the following methods:

The following example illustrates how to override the default selectInteractor behavior with a customized one:

  <jvtf:selectInteractor id="select" 
                         actionListener="#{MyListenerBean}"
                         invocationContext="JSF_CONTEXT" />

Here the actionListener tag attribute gets a binding to a bean implementing the javax.faces.event.ActionListener interface. Note that actionListener will override the default behavior of the selectInteractor. It is possible to add more than one action listener, combining customized action listeners with the default behavior as shown in the next example:

  <jvtf:selectInteractor id="select" 
                         invocationContext="JSF_CONTEXT">
    <f:actionListener
     type="ilog.tgo.faces.graph.dhtml.event.IltFacesSelectInteractorListener"/>
    <f:actionListener type="demo.MyInteractionListener"/>
  </jvtf:selectInteractor>

If you have started the bundled Tomcat web server, the following link will take you to the small sample illustrating how to customize action listeners:

You will find more information about the sample web application in:

where <installdir> stands for the directory where ILOG JViews TGO is installed.

The clientSelectInteractor Faces Component

The clientSelectInteractor faces component is an interactor designed to minimize the number of image requests and image updates between the graph view on the client and the image servlet on the server by dynamically rendering and managing the selection borders in the client side.

Instead of requesting a new graph view image every time the user selects an object, the clientSelectInteractor dynamically renders an HTML rectangular selection around the object. The server is notified so that the selection model is kept synchronized with the user interactions. A new graph view image is requested only when the user drags objects or interacts with specific decorations (such as information icons, and expansion icons).

The performance and responsiveness is greatly improved as lesser images are generated and dispatched by the server. However, the selection graphic feedback is impacted, as the client is limited to only displaying a rectangular border around the selected object.

The interactor can be configured to work in image mode. In this mode, it will ask the server to process the selection and get a new image on every user interaction. The dynamic selection border will only be displayed while objects are being dragged, as when objects are in their resting position the new image sent by the server already represents the selection.

It is possible to customize the interaction with object decorations, controlling when a click on a particular object decoration should trigger a new image request or not.

How to Declare the clientSelectInteractor Faces Component for the Equipment View

The clientSelectInteractor is declared like any other faces component defined in the JViews TGO faces library:

<jvtf:clientSelectInteractor is="clientSelect" />

Configuring the clientSelectInteractor

The clientSelectInteractor faces component is configured through the following tag attributes:

If you have started the bundled Tomcat web server, the following link will take you to a small sample illustrating this:

You will find more information about the sample web application in:

where <installdir> stands for the directory where ILOG JViews TGO is installed.

Configuring an Object Action for the clientSelectInteractor

By default, the clientSelectInteractor supports interactions with the following object decorations:

If the user clicks on any of these decorations, the interactor triggers a default object action instead of selecting the object. These actions change the look of the objects, which means that a new image is generated.

It is possible to override or even extend this behavior through the objectActionMethodBinding tag attribute, as follows:

<jvtf:clientSelectInteractor id="clientSelect"
 
objectActionMethodBinding="#{interactorBean.objectAction}" />

Here, the objectActionMethodBinding tag attribute is bound to the objectAction method declared in the interactorBean. The method binding must conform to the following signature:

boolean methodName(IlpGraphView, int, int)

The IlpGraphView is a reference to the graph view containing all the objects. The two integer parameters are the x and y components of the view position where the user has clicked. Returning true indicates that a new image has to be generated, while false indicates that nothing has been processed and the clicked object will be selected.

The selectionManager Faces Component

You can customize the way the selection is performed and displayed by using a selection manager.

This selection manager is defined in a facet on the equipmentView tag, as follows:

The selection manager has two display modes:

Other parameters can be configured on the selectionManager, like for example the line width or the color of the selection rectangle used in regular selection mode:

<jvtf:selectionManager lineWidth="2" lineColor="red"/>

Configuring the selectionManager

The selectionManager faces component is configured through the following tag attributes:

Exposing Selection Details

You can expose details on the current selection by taking advantage of the property accessor of the selection manager.

List getPropertyNames(IlpGraphicView view, IlpRepresentationObject object)

The following code illustrates how to provide your property accessor:

<jvtf:selectionManager propertyAccessor="{#serverBean.propertyAccessor}" [...] />

The following code illustrates how to implement your custom requirements in a new property accessor:

public class ServerBean {

  private IltFacesPropertyAccessor accessor = new MyPropertyAccessor();

  public IltFacesPropertyAccessor getPropertyAccessor() {
    return accessor;
  }

  class MyPropertyAccessor extends IltFacesPropertyAccessor {
   
    protected List getPropertyNames(IlpGraphicView view, 
IlpRepresentationObject object) {
      [...]
    } 
  }
}

Then you can register a JavaScript listener that will be called when the selection changes:

<jvtf:selectionManager onSelectionChanged="displayProperties(selection)"/>

The JavaScript function can be as follows:

// Alert the ID and bounds of all the selected objects
function displayProperties(selection) {
  for (var i = 0; i < selection.length; i++)
   alert(selection[i].getID()+"+selection[i].getBounds());  
}

In addition to the ID and bounds properties of the selected object, you can also expose the properties of the selected object in the TGO model as follows:

// Alert all the properties of all the selected objects
function displayProperties(selection) {
  for (var i = 0; i < selection.length; i++) {
    var propertiesNames = selection[i].getObjectPropertyNames();
    for (var j = 0; j < propertiesNames.length; j++)
         alert(selection[i].getObjectProperty(propertiesNames[j]));
  }   
}

The following example shows how to use the selection manager with a property accessor:

Managing Object Selection

The selectionManager also allows for changing the selection state of objects programmatically via its client side by means of JavaScript. This can be accomplished by using the following API:

Selecting and Deselecting an Object

The selectById function allows you to select or deselect an object by providing the object's identifier:

equipmentView.getSelectionManager().selectById("tgoObjectId");

This method call will select the object with the identifier tgoObjectId and deselect the object currently selected.

You can extend/reduce the current selection by selecting/deselecting a node as follows:

equipmentView.getSelectionManager().selectById("tgoObjectId", true);

This method call keeps the existing selection and selects the object with the identifier tgoObjectId, if it's not already selected; or it will deselect it, if it is already selected.

Selecting All Objects

The selectAll function allows you to select all objects:

equipmentView.getSelectionManager().selectAll();

This method call will select all visible objects.

Deselecting All Objects

The deselectAll function allows you to deselect all objects:

equipmentView.getSelectionManager().deselectAll();

This method call will clear the selection of all visible objects.

The following example shows how to use the selection manager API: