Working with Links

In Diagram links are connectors that represent relations between visual blocks. From this article you will learn how to manipulate links and customize them.

Loading links

Links are loaded into Diagram via the dedicated links property of the configuration object. As links you can provide:

  • plain JSON array or an XML string
  • a URL to load links from
  • a Data Collection with links.
{
  view:"diagram",
  data: [/*block data*/],
  links: "remote/data/links"
  // or 
  links: [
    /* link objects */
  ]
}

Keep in mind, that if the incoming data for links and blocks is in XML format, you need to add the datatype property passing "xml" as its value:

webix.ui({
  view: "diagram",
  datatype: "xml",   links: "remote/links.xml"
  url: "remote/data.xml"
});

Note, that all the incoming data (blocks and links) should be in one and the same format: either JSON or XML.

Link settings

Links define the relations between blocks, so each of them must have the following fileds:

  • source (string, number) - obligatory. Source of the link (where the link comes from)
  • target (string, number) - obligatory. Destination point of the link (where the link comes to)

Additionally, you can provide the following parameters to each link:

  • mode (string) - defines mode of the link. The possible values are:
    • "edges" - default. Elbow-like connector going from and to the center of top/side edge of the block
    • "direct" - a straight line going from the center of one block directly to the center of another
    • "child" - a line that connects parent with a child element. Used in block list structures.
    • "sibling" - a line that connects sibling elements (e.g. children of the same parent). Used in block list structures.
  • from (string) - defines the edge of the block the link is headed from. Possible values are:
    • "top"
    • "right"
    • "bottom"
    • "left".
  • to (string) - defines the edge of the block the link is headed to. Possible values are the same as in the from field described above.
  • line (array) - an array of coordinates according to which the link is drawn. Each segment of the link is defined as [[x, y], ...] or ["x, y", ...]
  • $css (string, function) - CSS class name or a template function to apply a class name to the link line
  • lineWidth (number) - defines the width for the link line. 1 by default. The property is applied to the line of the link (not arrow)
  • lineColor (string) - defines color for the link line (color name or HEX code). #ccd7e6 by default. The property is applied to the line of the link and arrow stroke
  • lineStyle (string, number) - stroke-dasharray for the link line (not its arrow). Possible values are:
    • "dotted"
    • "dashed"
    • numeric value. The higher value is, the more space in between dashes of the link line.

And a set of parameters that are applicable to a link arrow:

  • arrow (boolean, string, array) - defines whether to paint an arrowhead for the link. Can take the following values:
    • boolean to enable (default) or disable an arrowhead for link
    • "triangle" to draw a triangle instead of the arrow
    • an array of custom coordinates according to which the arrow is drawn. Each segment of the arrow is defined as [[x, y], ...] or ["x, y", ...]
  • $arrowCss (string, function) - CSS class name or a template function to apply a class name to the link arrow
  • arrowSize (string, number) - defines the size of the link arrow. It is 6px by default
  • backgroundColor (string) - defines color for the link arrow (color name or HEX code)
  • fillOpacity (string, number) - opacity of the arrow fill. Ranges from 0.0 to 1 or percentage from "0%" to "100%".

You can configure each link individually or tune all the links at once. To configure links separately, add the fields from the list above into the link data object and provide the desired values for them:

webix.ui({
  view: "diagram",
  data: [/* blocks */],
  links: [
    {
      source: "1",
      target: "1.2",
      lineColor: "#2d9bf0"
    },
    // other links
  ]
});

To provide settings globally for all links at once, define the linkItem property in the diagram object constructor. Common properties include css, mode (only "edges" or "direct"), arrow, arrowCSS and arrowSize:

webix.ui({
  view: "diagram",
  data: [/* blocks */],
  links: "remote/data/links",
  linkItem: {
    css: "cssForLinks",
    mode: "direct",
    arrow: false,
    arrowCss: "cssForArrows"
    arrowSize: 5
  }
});

Please note that the properties defined within separate link items have a higher priority than those set globally.

Defining link mode

Diagram offers 4 default types of links: "edges", "direct", "child", and "sibling".

Edges

The "edges" links are elbow-like connectors that go from the center to the top/side edge of another block.

Direct

The "direct" link is a straight line that goes from one block to another.

Child

The "child" link can help forming list structures by setting a connector between a parent and its child that is placed under its parent. On the picture below the "child" links are highlighted with purple.

Sibling

The "sibling" link is also a helper type for list structure being a connector between sibling blocks (e.g. children of the same parent). On the picture below the "sibling" links are highlighted with green.

webix.ui({
  view: "diagram",
  linkItem: {
    mode: "direct", //for all links that do not have their own mode
  },
  links: [
    { source:"1.2.1", target:"1.2.1.1", mode:"child"},
    { source:"1.2.1.1", target:"1.2.1.2", mode:"sibling"},
    // ... other links
  ],
});

Related sample:  Diagram: Link Mode Priority

Styling links

You can provide the desired link width, color and style. The color and width will be shared with a link arrow.

These parameters can be defined in the dataset:

// links dataset
[
  {
    source: "1", 
    target: "1.2",
    lineColor: "#61b578",
    linkStyle: "dotted",
    lineWidth: 2
  }
]

To provide common styles for all links, define the linksItem object inside Diagram constructor. Set the name of the CSS class as a value for the css field:

{
  view: "diagram",
  links: [/* link objects */],
  linkItem: {
    css: "common_links"   }
}

If you want to style a particular link, add the $css field to its data object setting a CCS class name as its value:

// links dataset
[
  {
    source: "1",
    target: "1.2",
    $css: "styles_for_link"   }
]

Styling arrows

Diagram allows you to render classic arrows (default) or empty or filled triangles to indicate the direction of a process.

You can provide the desired arrow type of disable an arrow for each separate link:

view:"diagram",
links:[
  //empty triangle
  { source: "1",  target: "1.2", arrow: "triangle" },
  //filled triangle
  { source: "1",  target: "1.2", arrow: "triangle", backgroundColor:"#CCD7E6" },
  // no arrow
  { source: "1.2", target: "1.2.2",  arrow: false},
]

You can also define arrow size and background opacity:

{  
   source: "1",  target: "1.2"
   arrow: "triangle",  
   arrowSize: 4
   backgroundColor:"#CCD7E6", fillOpacity: "50%",
}

To provide common styles for all arrows, define the linksItem object inside Diagram constructor. Set the name of the CSS class as a value for the arrowCss field:

{
  view: "diagram",
  links: [/* link objects */],
  linkItem: {
    arrowCss: "common_arrows"   }
}

If you want to style a particular arrow, add the $arrowCss field to its data object setting a CCS class name as its value:

// links dataset
[
  {
    source: "1",
    target: "1.2",
    $arrowCss: "styles_for_arrow"   }
]

Related sample:  Diagram: Styling Links

Fixed coordinates for links and arrows

If your project requires links and arrows to be drawn by fixed coordinates you can provide them in the corresponding line and arrow arrays.

Each element of the arrays is a segment of a line/arrow. It can be either another array with two numbers representing x and y coordinates or a string with numbers, separated by comma. The rule is the same for both cases - define segments of a line/arrow sequentially one by one.

// links dataset
[
  { 
    source:"core", 
    target:"query", 
    line:["300,230", "180,205", "100,205"],
    arrow:["300,101", "298,104", "292,98", "285,100",]
    // or
    line:[[300,230], [180,205], [100,205]],
    arrow:[[300,101], [298,104], [292,98],]
  },
  // other links
]

Related sample:  Diagram: Custom Links

The starting point for arrows and lines is the left top corner of the widget (0, 0).

Accessing links storage

On the client side links are stored in a view-less storage called DataCollection. To access the collection, call the getLinks method on Diagram:

const links = $$("diagram1").getLinks();

You can work with the collection using the dedicated API. For example, you can get the links array by serializing the collection:

const linksArray = $$("diagram1").getLinks().serialize();
/*
[
  { id: 161968034646, source: "core", target: "diagram" },
  { 
    $arrowCss: "batman", 
    arrow: ["300,101", "298,104"], 
    id: 1619680346462
    source: "core"
    target: "kanban"
  }
  // ...
]
*/
Back to top