Interacting with the network view component

JViews Framework JSF and core JViews JSF libraries declare predefined interactors that can be connected to the networkView component to add extra user interaction. Interactors are JSF components that execute client- or server-side actions. Most of them can be extended and configured to suit the user needs.

How to declare an interactor and connect it to the network view component

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

  <!-- Declare the predefined 'pan' interactor -->
  <jvf:panInteractor id="pan" />

  <jvtf:networkView id="aNetwork" 
                      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 networkView component specifies the interactor to be connected to the network view.

How to associate interactors with image buttons in the network 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 network 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="aNetwork.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="aNetwork.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="aNetwork.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="aNetwork.zoomOut(true)"
                    image="images/unzoom.gif"
                    rolloverImage="images/unzoomh.gif"
                    selectedImage="images/unzoomd.gif"
                    title="Zoom Out" 
                    message="Zoom Out" />
  </h:panelGrid>
  <jvtf:networkView id="aNetwork" 
                      context="#{contextBean}"
                      style="width:740;height:550" 
                      interactorId="pan" 
                      project="data/myProject.itpr" />

This example defines two predefined interactors:

selectInteractor: This is a server-side interactor that processes object selection by default. (See The selectInteractor JSF component for details).
panInteractor: This is a client-side interactor that enables panning of the image displayed by the network view component.

Two buttons are declared to connect the interactor to the network 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 network view with the interactorId tag attribute. In this case, the pan button is selected ( select="true" ) and the pan interactor is connected to the network view ( interactorId="pan" ).

If you have started the bundled Tomcat web server, the following link will take you to the small sample illustrating this: http://localhost:8080/jsf-network-step-by-step/faces/example13.jsp .

You will find more information about the sample web application in: <installdir> /samples/faces/jsf-network-step-by-step/index.html where <installdir> stands for the directory where Rogue Wave JViews TGO is installed.

The selectInteractor JSF component

The selectInteractor JSF component has been defined as an interactor that maps client-side mouse clicks to server-side events dispatched to the underlying view interactor. It extends the JavaServer™ Faces UICommand component, which means that it will fire ActionEvents to registered ActionListeners .

This component allows you to create customized IlvManagerViewInteractor instances that will process the mouse actions on the client side. By default, it uses the IltSelectInteractor , which allows selecting, dragging and expanding graphic objects.

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

Only BUTTON1 and BUTTON3 mouse buttons are supported (left and middle).
Pop-up menus are supported in a different way from the Swing network component. See Adding pop-up menus.
Double-click events are not supported.
There is no visual feedback when dragging an object (the graphic representation of the object does not follow the mouse pointer).
No keyboard actions are supported except the following modifiers:
- Shift key
- Control key
- Alt key
- Meta key

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

MOUSE_PRESSED
MOUSE_DRAGGED
MOUSE_RELEASED

How to declare the selectinteractor JSF component for the network view

The selectInteractor is declared like any other JSF component defined in the JViews TGO JSF tag library:

<jvtf:selectInteractor id="select" />

Configuring the selectInteractor

The selectInteractor JSF component is configured through the following tag attributes.

Tag attributes of the selectInteractor JSF component

Tag Attributes	Description
`cursor`	Defines the mouse cursor to be used when the interactor is active; it should be one of the cursors supported by the web browser.
`lineWidth`	Defines the width of the interaction area drawn by the interactor.
`lineColor`	Defines the color of the interaction area drawn by the interactor.
`actionName`	Defines the name of the action event triggered by this interactor; it is used to identify events coming from this interactor.
`autoSubmit`	Defines whether the request will be submitted by a mouse click or not; this tag is used to control when the actions are submitted. When this tag attribute is set to `false` , the `selectInteractor` will not submit any request after the user interaction, but wait until some other component does it.
`actionListener`	Defines an action listener that is called when this interactor is used. Action listeners should implement the `ActionListener` interface (from JSF library), but JViews TGO JSF provide the IltFacesGraphInteractorActionListener abstract implementation that decodes the user interactions into events dispatched to a given view interactor. Subclasses should implement the method `getViewInteractor` in order to return the appropriate view interactor to process the events. The default implementation ( IltFacesSelectInteractorListener) dispatches all events to the `IltSelectInteractor` view interactor. Therefore, the `actionListener` tag attribute may be used to register any `ActionListener` that will be notified whenever a user interaction has been performed, or a subclass of `IltFacesGraphInteractorActionListener` can be registered to decode the user interaction into events dispatched to view interactions ( IlpViewInteractor).
`invocationContext`	Defines whether the server-side processing is performed in the JSF lifecycle or directly by the image servlet. The possible values are: JSF_CONTEXT: Processing is done in the JSF lifecycle (the default value) IMAGE_SERVLET_CONTEXT: Processing is done by the image servlet, bypassing the JSF lifecycle The `selectInteractor` submits requests to be processed on the server side. By default, the request is addressed to the JavaServer JSF controller servlet which processes all requests according to the well-defined JSF lifecycle. This means that all component dependencies will be verified, any registered listener will be notified. The result is a full page refresh with an update of all components involved. If your interaction triggers updates of components other than the `networkView` , then the `JSF_CONTEXT` should be used. If, on the other hand, your requests are supposed to only update the image displayed by the `networkView` component, then you may want to benefit from the faster `IMAGE_SERVLET_CONTEXT` . In this case, the interactor requests will be addressed to the image servlet responsible for generating the image displayed by the `networkView` component. Note that the image servlet has no access to any JSF component other than `networkView` , which means that your request cannot rely on other JSF components, and that any registered listener for changes on the `selectInteractor` and `networkView` will not be updated. There is one exception to this rule. As the `overview` JSF component is largely used with the `networkView` JSF component, and as its displayed image is also generated by the image servlet, you can force the overview to be refreshed whenever the main view ( `networkView` ) is updated, at the cost of an extra client-server-client roundtrip. To do so, you must set the `autoRefresh` tag attribute of the `overview` JSF component to true.
`binding`	Defines a binding expression to a backing bean.

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: http://localhost:8080/jsf-network-step-by-step/faces/example12.jsp and http://localhost:8080/jsf-network-step-by-step/faces/example13.jsp .

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 network Swing component, it is not possible to declare view interactors through a CSS file. Instead, in the network JSF component, the view interactors are declared within customized action listeners added to the selectInteractor JSF 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:

getComponent() or getSource() : Return a reference to the interactor JSF component that is currently active (for example, IltFacesGraphInteractor ).

A predefined abstract implementation of the ActionListener interface named IltFacesGraphInteractorActionListener is provided to translate client-side interactions into server-side events that are dispatched to a given view interactor. When notified, this class translates user interactions into mouse events that are automatically dispatched to the IlpViewInteractor returned by the abstract method getViewInteractor(actionName) .

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>

Here IltFacesSelectInteractorListener is the action listener (extends IltFacesGraphInteractorActionListener) that implements the default behavior of the selectInteractor JSF component, and MyInteractionListener is a customized implementation of the javax.faces.event.ActionListener interface. The actionListener tag is used to add several action listeners to the selectInteractor , which are invoked in the order in which they have been declared. Note that action listeners may conflict with each other, especially multiple implementations of IltFacesGraphInteractorActionListener , as the first one invoked may change the business model and invalidate the next action listener.

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: http://localhost:8080/jsf-network-step-by-step/faces/example14.jsp .

The clientSelectInteractor JSF component

The clientSelectInteractor JSF 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.

Note

Unlike the selectInteractor , the clientSelectInteractor always communicates with the image servlet directly. Therefore, it does not follow the JSF lifecycle, which means that only the view JSF component and a possibly attached overview are updated and not all the other components in the page.

How to declare the clientSelectInteractor JSF component for the network view

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

<jvtf:clientSelectInteractor is="clientSelect" />

Configuring the clientSelectInteractor

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

Tag attributes of the clientSelectInteractor JSF component

Tag Attributes	Description
`binding`	Defines a binding expression to a backing bean, allowing the user to customize the `clientSelectInteractor` JSF component.
`message`	Defines the message displayed by the view when the interactor is set.
`cursor`	Defines the mouse cursor to be used when the interactor is active. It should be one of the cursors supported by the web browser.
`menuModeId`	The identifier passed to dynamically generated popup menus.
`moveAllowed`	Specifies whether this interactor allows mouse dragging.
`objectActionMethodBinding`	Defines a method binding to process actions on the object or on specific decorations attached to it.
`onSelectionChanged`	Specifies a JavaScript handler to be called whenever the selection changes. Deprecated in JViews TGO 8.0. See The selectionManager JSF component for an alternative.
`imageMode`	Sets the interactor to image mode. A new image will be requested every time the user interacts with the view. Deprecated in JViews TGO 8.0. See The selectionManager JSF component for an alternative.
`lineWidth`	The width of the selection border dynamically rendered by the interactor. Deprecated in JViews TGO 8.0. See The selectionManager JSF component for an alternative.
`lineColor`	The color of the selection border dynamically rendered by the interactor. Deprecated in JViews TGO 8.0. See The selectionManager JSF component for an alternative.
`forceUpdateProperties`	Forces the request of additional information when the interactor is in image mode. Used in conjunction with the `infoProviderMethodBinding` . Deprecated in JViews TGO 8.0. See The selectionManager JSF component for an alternative.
`infoProviderMethodBinding`	Defines the information provider method binding to return additional information about the selected object. Deprecated in JViews TGO 8.0. See The selectionManager JSF component for an alternative.

If you have started the bundled Tomcat web server, the following link will take you to a small sample illustrating this: http://localhost:8080/jsf-network-step-by-step/faces/example19.jsp .

Configuring an object action for the clientSelectInteractor

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

The information icon
The system icon
The expand and collapse icons

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.

In the example above, the objectAction method will override the default object action behavior (which is to react on expand, collapse, information and system icons). It is possible to extend this default behavior by overriding the method processObjectAction in class IltFacesDefaultObjectAction.

The selectionManager JSF 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 networkView tag, as follows:

<jvtf:networkView id="tgoViewId" interactorId="select">
  <f:facet name="selectionManager">
      <jvtf:selectionManager imageMode="false" [...] />
  </f:facet>
</jvtf: networkView >

The selection manager has two display modes:

image (default)

The image is refreshed after each selection. A new image is requested to the server at each selection which allows the client to get nice selection graphics.
regular

Rectangles representing the selection are displayed on top of the view. The roundtrip to the server is minimal: the generation of a new image is not required and the response time is faster but the selection feedback is limited to a selection rectangle.

Tip

Image Mode versus Regular Mode

Using one mode rather than the other depends on your criteria: performance or graphic feedback. Image mode provides a better graphic feedback but is slower because of the image generation and the need for an extra request to get additional information about the selection on the client. Regular mode offers basic graphic feedback but better performance.

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"/>

Note

The selection manager currently supports integration with the following TGO JSF interactor: clientSelectInteractor .

Configuring the selectionManager

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

Tag attributes of the selectionManager Faces component

Tag Attributes	Description
`infoProviderMethodBinding`	A method binding that respects the signature List methodName(IlpGraphView, IlpRepresentationObject). The returned value of this method is a list of additional properties associated with the selected object. A valid item of this list is a String or a list itself. As of JViews TGO 8.0, the preferred way to transfer object properties to client is via the `propertyAccessor` tag of the `selectionManager` .
`binding`	The value binding expression linking this component to a property in a backing bean. If this attribute is set, the tag does not create the component itself but retrieves it from the Bean property. This attribute must be a value binding.
`lineColor`	The color of selection rectangles lines.
`forceUpdateProperties`	Force to make additional request to query the current selection and additional properties in image mode to enable client-side selection listener.
`id`	The ID of this component.
`imageMode`	The image mode. In image mode, the image is refreshed on each selection. In regular mode, only the selected object(s) bounding box is queried and rectangles are dynamically displayed on top of the view. Note that the client-side listeners on selection and additional information on selected objects are available in image mode if and only if the `forceUpdateProperties` property is set to true. In regular mode no special configuration is needed. By default the manager is in image mode.
`lineWidth`	The width of selection rectangle lines.
`onSelectionChanged`	A JavaScript handler called when the selection has changed. The handler can use the predefined variable ' `selection` ' which is the list of current selected items. To use this handler the `selectionManager` must be in regular mode or the `forceUpdateProperties` must be set if in image mode. Refer to the user's documentation for further information.
`propertyAccessor`	The reference to the value binding expression to an `IltFacesPropertyAccessor` instance that will be used to access model properties of the selected objects.
`fillOn`	true to display filled selection rectangles. The fill color is the line color with a transparency of 50%.

Exposing selection details

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

The IltFacesPropertyAccessor contains several methods that can be overridden to configure or specialize the way it gives access to model properties. In particular, you can filter the properties that are exposed to clients by overriding the following method:

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]));
  }   
}

Note

To obtain selected object properties information on the client side while you are running the selection in image mode, you need to force an additional request by setting the property forceUpdateProperties to true . In regular mode this feature is available without any overhead.

If you have started the bundled Tomcat Web server, the following link will take you to the small sample illustrating how to use the selection manager with the property accessor: http://localhost:8080/jsf-network-step-by-step/faces/example20.jsp.

You can find more information about the sample Web application in: <installdir> /samples/faces/jsf-network-step-by-step/index.html where <installdir> is the directory in which Rogue Wave JViews TGO is installed.

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:

IlvAbstractSelectionManager.selectById
IlvAbstractSelectionManager.selectAll
IlvAbstractSelectionManager.deselectAll

Selecting and deselecting an object

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

networkView.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:

networkView.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:

networkView.getSelectionManager().selectAll();

This method call will select all visible objects.

Deselecting all objects

The deselectAll function allows you to deselect all objects:

networkView.getSelectionManager().deselectAll();

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

Note

In all cases, the object must be selectable in order to get selected.

If you have started the bundled Tomcat Web server, the following link will take you to the small sample illustrating how to use the selection manager API: http://localhost:8080/jsf-network-step-by-step/faces/example22.jsp.

Current section

Configuring a network view JSF component