# Sirius – Provide custom bundled image shape

## Goals

- Sirius provides a basic image style for node mappings. This style offers a selection of five different shapes. This extension point is used to allow specifiers to provide their own shapes defined in a SVG file.
- This extension point is an improvement on the org.eclipse.sirius.diagram.bundledImageShape extension point that has limitation and is now deprecated. Both extension points work but only this one will remain in future versions of Sirius.

## Define a bundled image shape extension

- This extension point is identified as `org.eclipse.sirius.diagram.customBundledImageShape`. In this extension, there are three required fields:
  - The Id of the extension is for once required as it will be used to identify the provided shape in the models (VSM and graphical models).
  - The image path, that needs to start with the plug-in name as it is possible to define a bundled image shape extension using an image in a different plug-in.
  - The image label displayed in VSMs (suffixed with the plug-in name where the bundled image shape extension is declared).

- There are 6 optional parameters in this extension point. These parameters are used to provide the identifier or attribute name concerning the color, border color and border size used in the given SVG file. Here is a list of these parameters:
  - colorIdentifier, the identifier of the tag defining the inner color of the figure.
  - colorAttribute, the attribute of the tag defining the inner color of the figure.
  - borderColorIdentifier, the identifier of the tag defining the border color of the figure.
  - borderColorAttribute, the attribute of the tag defining the border color of the figure.
  - borderSizeIdentifier, the identifier of the tag defining the border size of the figure.
  - borderSizeAttribute, the attribute of the tag defining the border size of the figure.
- As a color or the border size can be defined in a multi-valued property (see example below), on colorAttribute, borderColorAttribute and borderSizeAttribute it is possible to add a subAttributeIdentifier in order to identify this property among the list.

Note that it is possible to provide a non SVG file (like a JPEG) but the colors and border size will not be synchronized with the selected information in the VSM.

## Examples

As examples, we will use the sample provided in this feature corresponding bugzilla

circle.svg defines a ring figure thanks to the following ellipse tag:

    <ellipse
         cx="242.58475"
         cy="254.23729"
         id="circle4"
         style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:44.9;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
         rx="217.21455"
         ry="214.03659" />

For this file, the extension point is specified as follows:

    	<extension
            id="custom.circle.svg"
            name="Circle"
            point="org.eclipse.sirius.diagram.customBundledImageShape">
         <image
               imagePath="/542678.design/images/circle.svg"
               label="custom.circle">
            <colorIdentifier
                  colorIdentifier="circle4">
            </colorIdentifier>
            <colorAttribute
                  colorAttribute="style">
               <subAttributeIdentifier
                     subAttributeIdentifier="fill">
               </subAttributeIdentifier>
            </colorAttribute>
            <borderColorIdentifier
                  borderColorIdentifier="circle4">
            </borderColorIdentifier>
            <borderColorAttribute
                  borderColorAttribute="style">
               <subAttributeIdentifier
                     subAttributeIdentifier="stroke">
               </subAttributeIdentifier>
            </borderColorAttribute>
            <borderSizeIdentifier
                  borderSizeIdentifier="circle4">
            </borderSizeIdentifier>
            <borderSizeAttribute
                  borderSizeAttribute="style">
               <subAttributeIdentifier
                     subAttributeIdentifier="stroke-width">
               </subAttributeIdentifier>
            </borderSizeAttribute>
         </image>
      </extension>

The three properties are defined in a single tag. In the extension point each, colorIdentifier, borderColorIdentifier and borderSizeIdentifier have the same identifier: “circle4”.
Then, the color, border color and border size are all defined in the multi-valued property “style” of the ellipse tag. Likewise, in the extension point, colorAttribute, borderColorAttribute and borderSizeAttribute have the same value: “style”.
Finally, in this “style” property, the color is identified by the attribute “fill”, the border color is identified by the attribute “stroke” and the border color is identified by the attribute “stroke-width”. This is why there is a subAttributeIdentifier with these values under colorAttribute, borderColorAttribute and borderSizeAttribute.

Now let’s take the sample circle2.svg. The result is also a ring but in the svg it uses the tag circle as follows:

     <circle id="circle" cx="250" cy="250" r="210" fill="#fff" stroke="#000" stroke-width="8"/>

Here there is no multi-valued properties, but the 3 properties we are looking for are separated. For this image, the extension point will be specified as follows:

    <extension
            id="custom.circle2.svg"
            name="Circle2"
            point="org.eclipse.sirius.diagram.customBundledImageShape">
         <image
               imagePath="/542678.design/images/circle2.svg"
               label="custom.circle2">
            <colorIdentifier
                  colorIdentifier="circle">
            </colorIdentifier>
            <colorAttribute
                  colorAttribute="fill">
            </colorAttribute>
            <borderColorIdentifier
                  borderColorIdentifier="circle">
            </borderColorIdentifier>
            <borderColorAttribute
                  borderColorAttribute="stroke">
            </borderColorAttribute>
            <borderSizeIdentifier
                  borderSizeIdentifier="circle">
            </borderSizeIdentifier>
            <borderSizeAttribute
                  borderSizeAttribute="stroke-width">
            </borderSizeAttribute>
         </image>
      </extension>

This time, there is no subAttributeIdentifier, however colorAttribute, borderColorAttribute and borderSizeAttribute have different values.