Defining the links appearance

The Diagram component generates instances of the Link class to represent the relations between items. IBM® ILOG® Dojo Diagrammer provides a built-in styling mechanism that allows you to customize the graphical representation of the links.

Defining the link template

To define the link template:
  • Use the linkTemplate property. The value is a JSON string or an object that describes the node as a hierarchy of GFX shapes. It follows the same rules as the nodeTemplate property. For more information, see Defining the nodes appearance.
    A diagram.Link is composed of three dojox.gfx.Shape subcomponents:
    • main path (mandatory)
    • start arrow (optional)
    • end arrow (optional)
    The link template must conform to this structure. Each shape in the link template must include a specific identifier with a dojoAttachPoint property that specifies which subcomponent each shape corresponds to. Depending on the subcomponent, the dojoAttachPoint property must be one of the following subcomponent specifications: _path, _startArrow, or _endArrow.
The following example is a simplified version of the default link template (with bindings removed for the sake of simplicity):
[{
      dojoAttachPoint: '_path',
      shape: {
         type: 'polyline',
         points: [{
            x: 0,
            y: 0
         }, {
            x: 100,
            y: 100
         }]
      },
      stroke: {
         width: 2
      }
   }
   ,
   {
      dojoAttachPoint: '_endArrow',
      shape: {
         type: 'polyline',
         points: [{
            x: -8,
            y: 4
         }, {
            x: 0,
            y: 0
         }, {
            x: -8,
            y: -4
         }]
      },
      fill: '#00'
   }
]
The following code defines a link with a circle as the start arrow, and a polyline as the link path and an end arrow:
var linkTemplate = "[{
      dojoAttachPoint: '_path',
      shape: {
         type: 'polyline',
         points: [{
            x: 0,
            y: 0
         }, {
            x: 100,
            y: 100
         }]
      },
      stroke: {
         width: 2
      }
   }
   ,
   {
      dojoAttachPoint: '_startArrow',
      shape: {
         type: 'circle',
         r: 4
      },
      fill: 'white',
      stroke: 'black'
   }
   ,
   {
      dojoAttachPoint: '_endArrow',
      shape: {
         type: 'polyline',
         points: [{
            x: -8,
            y: 4
         }, {
            x: 0,
            y: 0
         }, {
            x: -8,
            y: -4
         }, {
            x: -8,
            y: 4
         }]
      },
      fill: 'black'
   }
]";

Defining the link style

To customize the link style:
  • Use the linkStyle property. The value is a plain JavaScript object that contains definitions for the corresponding link properties that you want to be set. It is valid for any link property if a setter exists for the property and its name follows the Java naming convention (for a property named a_property, a setter setAProperty must exist).
    The Link class defines the following properties that can be used to change the appearance of the link with the linkStyle property:
    Property Type Description
    strokeColor string or dojo.Color
    Sets the link stroke color.
    strokeWidth int
    Sets the link stroke width.
    selectedStrokeColor string or dojo.Color
    Sets the link stroke color when selected.
    selectedStrokeWidth int
    Sets the link stroke width when selected.
    startArrowVisible boolean
    Sets whether the start arrow is visible.
    startArrowFill dojox.gfx.fill
    Sets the start arrow fill.
    startArrowStroke dojox.gfx.stroke
    Sets the start arrow stroke.
    endArrowVisible boolean
    Sets whether the end arrow is visible.
    endArrowFill dojox.gfx.fill
    Sets the end arrow fill.
    endArrowStroke dojox.gfx.stroke
    Sets the end arrow stroke.
    For example, the following code sets the link stroke width to 4:
    <div id="canvas" dojoType='ibm_ilog.diagram.widget.Diagram' style="width:900px;height:700px" movableNode="true"
              linkStyle="{strokeWidth:4}">
       </div>

Defining custom links programmatically

To define custom links:
  • Set the onLinkCreated or createLinkFunction attributes of the Diagram widget, if the mechanisms described in this topic are not sufficient to customize the links.
    The onLinkCreated is called each time a link has been created. It enables you to customize the link as required. The function must conform to the following prototype:
    function linkCreated(link, start, end, diagram){
        // summary: Called after a Node is created by the Diagram widget
        // link: ibm_ilog.diagram.Link: The newly created Link.
        // start: ibm_ilog.diagram.Node: The start node of the link.
        // end: ibm_ilog.diagram.Node: The end node of the link.
        // diagram: ibm_ilog.diagram.widget.Diagram: The Diagram widget
    };
    The createLinkFunction enables you to change the way a link is created. It is called to create each link and must conform to the following prototype:
    function createLink(item, start, end, template, onGraph, diagram){
        // summary: Creates a Link for a given data store item.
        // item: The item contained in the linksStore, or null if the link is not created from a linksStore item.
        // start: ibm_ilog.diagram.Node: The start node of the link.
        // end: ibm_ilog.diagram.Node: The end node of the link.
        // template: The suggested node template.
        // onGraph: The parent Graph in which the node must be created.
        // diagram: ibm_ilog.diagram.widget.Diagram: The Diagram widget.
        ...
        return link; // ibm_ilog.diagram.Link
    };
    The suggested template is the template specified by the linkTemplate or linkTemplateFunction attributes. The createLinkFunction can use a different template. To create the custom link, the createLinkFunction must call the createTemplatedShape function of the Diagram widget.
    The following example creates an instance of the class MyLink, which must be a subclass of ibm_ilog.diagram.Link:
    function createLink(item, start, end, template, onGraph, diagram){
        return diagram.createTemplatedShape(MyLink, template, onGraph, diagram.linkStyle, diagram.linksStore, item);
    };
    If the createLinkFunction does not connect the Link to the start and end nodes (by calling link.setStartPort/setEndPort), it is done automatically by the Diagram widget after the createLinkFunction is called. However, the createLinkFunction can connect the link, for example, to customize the connection points or to use custom ports. In this case, the widget does not override the ports set by the function.