Skip to main content

addShape()

info

The addShape() method can be used both in the diagram and in the editor.
Check the related sample: Diagram. Mindmap mode. Site map and user flow example.

Description

Creates a custom shape and sets sidebar options for its editing in the right panel of the editor

Usage

addShape(
type: string,
parameters: object
): void;

Parameters

  • type - (required) the unique name for the type of a custom shape. The name must differ from the names of default shapes
  • parameters - (required) an object with the additional parameters of the addShape() method. Here you can specify the following attributes:
    • template: function - (required) the function that takes the configuration object of the shape as a parameter and returns either an HTML or SVG template. Check the available formats of the template
    • defaults: object - (optional) the default configuration for a created shape. See the full list of the configuration properties of a shape
    • properties: array - (optional, and is available only in the editor mode) an array of objects that defines which sidebar options will be rendered in the right panel of the editor for editing a custom shape. Each object can contain a set of properties:
      • type: string - (required) the type of a sidebar option. See the list of available types below
      • label?: string - (optional) specifies the label for the sidebar option
      • property?: string - (optional) a custom property of the shape
    • eventHandlers: object - (optional) adds custom event handlers to HTML elements of the template of a shape. The eventHandlers object includes a set of key:value pairs, where:
      • key: string - the name of the event. Note, that at the beginning of the event name the 'on' prefix is used (onclick, onmouseover)
      • value: object - an object that contains a key:value pair, where
        • key is the CSS class name that the handler will be applied to
        • value is a function that takes two parameters:
          • event: object - (required) an event object
          • shape: object - (required) the shape object
        tip

        Note, we recommend that you use different CSS classes for different custom shapes when initializing custom event handlers.

Example

const diagram = new dhx.Diagram("diagram_container", {
type: "default" // or type: "org", or type: "mindmap"
});
diagram.data.parse(data);

diagram.addShape("template", {
template: config => (
`<section className='template'>
<h3>${config.title}</h3>
<ul><li>${config.text.join("</li><li>")}</li></ul>
</section>`
)
});

Types of sidebar options

While specifying sidebar options for editing custom shapes, you can apply the following values of the type property:

  • "arrange" - provides interface for editing the width, height, angle, x, y properties of a shape. The properties can't be overridden. The type is available only in the default mode of the editor
  • "position" - provides interface for editing either the x/y, or dx/dy properties of a shape. The properties can't be overridden
  • "size" - provides interface for editing the width and height properties of a shape. The properties can't be overridden
  • "title" - provides interface for editing text values of a shape. By default, this type allows editing the title property of a shape
  • "text" - provides interface for editing text values of a shape. By default, this type allows editing the text property of a shape
  • "img" - provides interface for editing an image of a shape. By default, this type allows editing the img property of a shape
  • "fill" - provides interface for editing color values of a shape. By default, this type allows editing the fill property of a shape
  • "textProps" - provides interface for editing the textAlign, lineHeight, fontStyle, textVerticalAlign, fontSize properties of a shape. The properties can't be overridden. You need to specify all of these properties in the data set for correct work of the Text sidebar option
  • "strokeProps" - provides interface for editing the stroke, strokeType, strokeWidth properties of a shape. The properties can't be overridden. You need to specify all of these properties in the data set for correct work of the Stroke sidebar option
  • "grid" - provides interface for editing the step of moving a shape. The visibility of the option is adjusted via the controls property of the editor

Formats of the shape template

The template function can return either an HTML or SVG template.

Creating an HTML template can be implemented either in ES5 or in ES6+ formats.

An example of creating an HTML template using ES6+:

const template = config => (
`<section className='template'>
<h3>${config.title}</h3>
<ul><li>${config.text.join("</li><li>")}</li></ul>
</section>`
);

Related sample: Diagram. Default mode. HTML template in ES6+ format

Related sample: Diagram editor. Default mode. Custom shape template in ES6+ format

An example of creating an HTML template using ES5:

function template(config) {
var template = "<section className='template'>"
template += "<h3>" + config.title +"</h3>";
template += "<ul><li>" + config.text.join("</li><li>") +"</li></ul>";
template += "</section>";
return template;
};

Related sample: Diagram. Default mode. HTML template in ES5 format

Related sample: Diagram editor. Default mode. Custom shape template in ES5 format

note

Note, that all HTML and SVG tags must be closed in the template.

For example, an <img src="" alt=""/> tag should look like <img src="" alt=""/></img>.

Change log:

  • The eventHandlers attribute is added in v3.1
  • The method is added in v3.0

Related articles: Custom Shape