Adding new decorations to predefined business objects

How to add new decorations to network and equipment nodes

This use case illustrates how you can extend the predefined business object representation by adding new decorations. It applies to the network and equipment components.

The network and equipment node representation of predefined business objects cannot be replaced, but you can extend it by adding new decorations.

The following properties are available to add a new decoration:

children : An indexed property each element of which is an IlvGraphic. Each IlvGraphic is a new decoration that will be added to the graphic representation.
constraints : An indexed property each element of which is an attachment constraint. The attachment constraint indicates how the new property is attached to the object base. It is an instance of ilog.views.graphic.composite.layout.IlvAttachmentConstraint .

The following application is provided as part of the JViews TGO demonstration software at <installdir> /samples/network/decoration.

It illustrates how to extend a predefined business object representation with a new decoration. In this use case, the following customization is notable:

object."SampleNetworkElement" {
  children[0]: '';
  constraints[0]: '';
  children[1]: '';
  constraints[1]: '';
}

object."SampleNetworkElement"[comments] {
  children[0]: @+commentIcon;
  constraints[0]: @+commentIconConstraint;
}

The selectors in this extract indicate that a new decoration will be added to the object representation when the attribute comments is set in the object. When the attribute is set, an icon is attached to the bottom left side of the base as illustrated by the following CSS extract.

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// This selector creates an icon decoration.
//
// Here we show the use of built-in properties:
//  * ILPATTRIBUTE
//  * ILPDECORATIONNAME
//
// 1. To associate a decoration to an IlpAttribute
// specify the 'ILPATTRIBUTE' property as illustrated 
// below.
//
// This property is used to associate a graphic decoration
// to an attribute in the business model. 
//
// The ILPATTRIBUTE property type is String. Its value 
// should be an attribute name.
//
// Once this association is done, tooltips and interactors
// can be defined in CSS for the business attribute
// and will be displayed/triggered when the event 
// occurs in the decoration graphic.
//
// 2. To associate a decoration to a name specify
// the 'ILPDECORATIONNAME' property as illustrated
// below.
//
// The ILPDECORATIONNAME property type is a String.
// Its value should be a ilog.tgo.graphic.IltGraphicElementName 
// value.
// 
// Once this association is done, it will be possible
// to customize the layer policy and zoom policy to
// take into account your new decorations.
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Subobject#commentIcon {
  class: 'ilog.views.graphic.IlvIcon';
  image: '@|image("commentIcon.png")';
  ILPATTRIBUTE: "comments";
  ILPDECORATIONNAME: "Comments";
}

Subobject#commentIconConstraint {
  class: 'ilog.views.graphic.composite.layout.IlvAttachmentConstraint';
  hotSpot: BottomLeft;
  anchor: BottomLeft;
}

New decorations can be added to all predefined business objects, either nodes or links. The attachment locations vary depending on whether the object is a node or a link.

In the case of nodes, new decorations can be added to the following attachment locations, relative to the object base (see IlvAttachmentLocation):

TopLeft , TopCenter , TopRight
LeftCenter
Center
RightCenter
BottomLeft , BottomCenter , BottomRight
HotSpot

In the case of links, new decorations can be added to the following attachment locations, relative to the link shape (see IlvLinkAttachmentLocation) :

NearFromLink
NearToLink
FromLink
ToLink
MiddleLink

For details about creating and customizing composite graphics, see the section on developing composite nodes in Developing with the JViews Diagrammer SDK.

You can use the following features when new decorations are added to the predefined business object representation:

Define a tooltip to be displayed when the mouse is over the new decoration
Define interactors to be executed when events occur on the new decoration
Specify in which layer the decoration will be placed
Specify a visibility threshold that will make the decoration disappear depending on the zoom level of the view

To customize the new decoration and make use of these features, you need to declare the following two properties with the new decoration:

ILPATTRIBUTE : This property associates the decoration with a business attribute in the object. It is used to customize the decoration tooltip and interactor.
ILPDECORATIONNAME : This property associates the decoration with a decoration name, which is the identifier used by the layer policy and zoom policy configurations in the network and equipment components.

The following sections provide examples of how to use these properties to achieve the desired configurations.

How to customize the tooltip and Interactor of a new decoration added to a predefined business object

This use case illustrates how you can configure new decorations added to predefined business objects to display tooltips and react to events. It applies to the network and equipment components.

The following application is provided as part of the JViews TGO demonstration software at <installdir> /samples/network/decoration.

You can add new decorations to the graphic representation of a predefined business object through cascading style sheets.

To configure a tooltip and an interactor for a new decoration, you need to associate the new decoration with a business attribute of the object that is represented. This configuration is performed using property ILPATTRIBUTE, as follows:

Subobject#commentIcon {
  class: 'ilog.views.graphic.IlvIcon';
  image: '@|image("commentIcon.png")';
  ILPATTRIBUTE: "comments";
  ILPDECORATIONNAME: "Comments";
}

The ILPATTRIBUTE value is the attribute name as it has been defined in the business model. In this example, the new decoration is associated with the attribute " comments " from the business class SampleNetworkElement .

Once the decoration has been associated with a business attribute, you can customize a tooltip and an interactor using attribute selectors and properties toolTipText , toolTipGraphic and interactor .

For example:

object."SampleNetworkElement/comments"[comments] {
  interactor: @+showCommentInteractor;
  toolTipText: '@|concat(@name, " Comments")';
}
Subobject#showCommentInteractor {
  class: 'ilog.cpl.interactor.IlpDefaultObjectInteractor';
  action[0]: @+commentButton;
}
Subobject#commentButton {
  class: 'ilog.cpl.interactor.IlpGestureAction';
  gesture: BUTTON1_CLICKED;
  action: @+toggleCommentAction;
}
Subobject#toggleCommentAction {
  class: 'ToggleCommentWindowAction';
}

Please note that the interactor customization can only be achieved if the Interactor renderer is enabled. Be sure to enable the renderer if this feature is to be used:

Network {
  interactor: true;
}

How to define a decoration name for a new decoration added to a predefined business object

This use case illustrates how you can define a new decoration name and associate it with a new decoration that is added to a predefined business object. It applies to the network and equipment components.

The following application is provided as part of the JViews TGO demonstration software at <installdir> /samples/network/decoration.

You can add new decorations to the graphic representation of predefined business objects through cascading style sheets.

The decoration name is an instance of IltGraphicElementName. New decoration names can be created by the application, as follows:

IltGraphicElementName comments = new IltGraphicElementName("Comments");

Note that the decoration name is an enumeration. Therefore, when creating new values for the enumeration, they must be uniquely identified within the application.

You can also use any of the existing decoration names:

AlarmBalloon
AlarmCount
Base
ContainerStatus
Family
Function
Icon
InformationIcon
InformationWindow
InState
Media
Name
OutState
Plinth
PSRIFromEnd
PSRIToEnd
SecondaryStateModifiers
SystemIcon
SystemWindow
Generic

Once the decoration name has been created, you can associate it with the new decoration in the cascading style sheet file by defining the value of property ILPDECORATIONNAME :

Subobject#commentIcon {
  class: 'ilog.views.graphic.IlvIcon';
  image: '@|image("commentIcon.png")';
  ILPATTRIBUTE: "comments";
  ILPDECORATIONNAME: "Comments";
}

If the ILPDECORATIONNAME property is not defined, the decoration name is set by default to Generic.

How to customize the layer of a new decoration added to a predefined business object

This use case illustrates how you can configure new decorations to be displayed in specific layers. It applies to the network and equipment components.

The following application is provided as part of the JViews TGO demonstration software at <installdir> /samples/network/decoration.

You can add new decorations to the graphic representation of a predefined business object through cascading style sheets.

To configure the layer where a new decoration is to be placed, specify the decoration name to be used as the identifier of the decoration by the network or equipment component layer policy (see Network component). See also How to define a decoration name for a new decoration added to a predefined business object.

You can then create a custom layer policy which defines specific layers for the decoration names.

The following application is provided as part of the JViews TGO demonstration software: <installdir> /samples/network/decoration/srchtml/decoration/CustomLayerPolicy.java.html.

The layer policy implementation must provide at least the following methods: attach, detach and getElementLayer.

/**
   * Attaches the layer policy to the manager.
   */
  public void attach(IltcCompositeManager manager) {
    super.attach(manager);
    this.commentsLayer = manager.addLayerOnTop(this.getSystemWindowLayer());
    this.commentsLayer.setName("Comments");
  }

The attach method is called whenever the layer policy is attached to a network component. This method should be used to perform any initialization required, for example, creating the layers that will be used by the layer policy implementation.

/**
   * Detaches the layer policy from the manager. 
   * 
   */
  public void detach(IltcCompositeManager manager) {
    super.detach(manager);
    manager.removeLayer(this.commentsLayer);
    this.commentsLayer = null;
  }

The detach method is called whenever the layer policy is removed from the network component. This method should be used to perform cleanup operations on the resources created by the layer policy implementation.

/**
   * Returns the layer where the elements with the given name
   * should be placed.
   */
  public IltcLayer getElementLayer (IltcCompositeGraphic graphic, 
IltGraphicElementName elementName) {
    if (elementName.getName().equals(COMMENTS_DECORATION_NAME)) {
      return this.commentsLayer;
    } else
      return super.getElementLayer(graphic, elementName);
  }

The getElementLayer method is used to specify in which layer the decoration with a given name should be placed. This method should verify whether the decoration name passed as argument is the one that you have created, and, if so, return the appropriate layer.

Finally, the custom layer policy is associated with the network or equipment component as follows:

CustomLayerPolicy policy = new CustomLayerPolicy();
networkComponent.getView().getCompositeGrapher().setLayerPolicy(policy);

How to customize the visibility threshold of a new decoration added to a predefined business object

This use case illustrates how you can configure new decorations added to predefined business objects to have specific visibility thresholds below which the decorations become invisible when the network component is configured with the physical or mixed zoom policies. It applies to the network and equipment components.

The following application is provided as part of the JViews TGO demonstration software: <installdir> /samples/network/decoration.

You can add new decorations to the graphic representation of a predefined business object through cascading style sheets.

To configure the visibility threshold for a new decoration, first specify the decoration name to be used as the identifier of the decoration by the network or equipment component zoom policy (see Network component). See also How to define a decoration name for a new decoration added to a predefined business object.

Once the decoration name has been defined and associated with the decoration using the ILPDECORATIONNAME property, you can specify the visibility threshold in the network component configuration. The visibility threshold information applies to the physical and mixed zoom policies.

You have to enable the Zooming renderer in the network component configuration as follows to achieve the desired result:

Network {
  zooming: true;
}

Configure the zoom policy to be used, for example, the physical zoom policy and specify the visibility threshold for the new decoration name by using the indexed properties decorationNames and visibilityThresholds :

Zooming {
  type: "Physical";
  decorationNames[0]: Comments;
  visibilityThresholds[0]: 0.5;
}

For more information on zoom policy configuration, refer to Network component.