Property Mapping

A common use case is the requirement to temporarily paint a set of nodes/groups/ports and/or edges with some set of styles. Since the original release of the Toolkit the surface has supported this requirement via the concept of UI States - named sets of configuration that can be applied to specific data objects or to the dataset as a whole. UI States are very useful, but they operate in a "push" rather than a "pull" mode, ie. it is up to the user to tell the surface what state some object should be in.

Property Mappings is a new concept introduced in 5.11.0 which was built as part of the Flowchart builder component in jsPlumb's Components product, and which we considered to be something that could be useful for Toolkit licensees.

A Property Mapping allows you to match specific values for a given property to a set of config - it's related to the concept of UI States, but it's a "pull" rather than "push": when you update the model, the surface figures out what config to apply for a given object, rather than you having to tell it.

note

As of 5.11.2 this functionality is available only for edges. We are investigating options for how this could be usefully extended to nodes, groups and ports.

Example

This example is drawn from the Flowchart Builder's source code:

import { ArrowOverlay } from "@jsplumb/core"

const ARROW_WIDTH = 5
const ARROW_LENGTH = 10
const CLASS_DASHED_EDGE = "some-css-class"

const PROPERTY_LINE_STYLE = "lineStyle"

const EDGE_TYPE_SOURCE_ARROW = "source"
const EDGE_TYPE_TARGET_ARROW = "target"
const EDGE_TYPE_PLAIN = "plain"
const EDGE_TYPE_DASHED = "dashed"

toolkitInstance.render(someElement, {
    ...
    propertyMappings:{
        edgeMappings:[
            {
                property:PROPERTY_LINE_STYLE,
                mappings:{
                     [EDGE_TYPE_SOURCE_ARROW]:{
                         overlays:[ 
                             { 
                                 type:ArrowOverlay.type, 
                                 options:{
                                     location:0, 
                                     direction:-1, 
                                     width:ARROW_WIDTH, 
                                     Length:ARROW_LENGTH
                                 } 
                             } ]
                     },
                     [EDGE_TYPE_TARGET_ARROW]:{
                         overlays:[ 
                             { 
                                 type:ArrowOverlay.type, 
                                 options:{
                                     location:1, 
                                     width:ARROW_WIDTH, 
                                     length:ARROW_LENGTH
                                 } 
                             } 
                         ]
                     },
                     [EDGE_TYPE_PLAIN]:{},
                     [EDGE_TYPE_DASHED]:{
                         cssClass:CLASS_DASHED_EDGE
                     }
                 }
             }
        ]
    }
})

Each mapping consists of a property name and a map of values to configs. Here we have declared a set of mappings for the property lineStyle in the backing data for an edge:

     property:PROPERTY_LINE_STYLE,
     mappings:{
         [EDGE_TYPE_SOURCE_ARROW]:{
             ...
         }
         ...
    }

So if you had an edge with this definition:

{
  source: "1",
  target: "2",
  data:{
      lineStyle:"source"
  }
}

Then the corresponding connection would have an arrow overlay at location 0.

Updating data

When you call updateEdge the property mappings are inspected. Any that are no longer valid are removed, and any that are now valid are added:

toolkit.updateEdge(someEdge, {
    lineStyle:EDGE_TYPE_DASHED
})

This would result in the arrow overlay being removed, and "some-css-class" being added to the connection's class list, because there is a mapping for EDGE_TYPE_DASHED:

mappings:{
    
    ... 
    
    [EDGE_TYPE_DASHED]:{
        cssClass:CLASS_DASHED_EDGE
    }
}    

Wildcard mappings

You can use "*" or WILDCARD from @jsplumb/common as the value for some property, which will instruct the surface that the given config should be applied regardless of the value of the mapped property (as long as it is present, not null):

import { WILDCARD } from "@jsplumb/common"

{
    property:"label",
    mappings:{
        [WILDCARD]:{
            overlays:[
                {
                    type:LabelOverlay.type,
                    options:{
                        label:"{{label}}",
                        location:0.5,
                        cssClass:"some-label"
                    }
                }
            ]
        }
    }
}

Here, we have instructed the Toolkit to show a label whenever an edge's backing data has a label property. Incidentally, this specific requirement can actually be neatly handled by another new feature in 5.11.0 - Edge labels.