addShape()
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 shapesparameters
- (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 templatedefaults: object
- (optional) the default configuration for a created shape. See the full list of the configuration properties of a shapeproperties: 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 belowlabel?: string
- (optional) specifies the label for the sidebar optionproperty?: 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, wherekey
is the CSS class name that the handler will be applied tovalue
is a function that takes two parameters:event: object
- (required) an event objectshape: object
- (required) the shape object
tipNote, 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, 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