Difference between revisions of "BPMN2-Modeler/DeveloperTutorials/ToolPaletteFragments"

Revision as of 16:08, 29 February 2016

Tool Palette Fragments

The BPMN2 Modeler's Tool Palette is extremely flexible and can be extended with user-defined "snippets" or compound tool items. The "Workflow Patterns" Tool Drawer is an example of this type of extension. Please use the Core Extension Points document as a reference.

In this tutorial we will be using the BPMN2 Modeler's ".bpmn2config" configuration folder to define some BPMN2 snippets for the Tool Palette, simply because this will be an iterative process and changing some XML in a file is much faster than rebuilding and running an editor extension plugin.

Create a new "General Project" and then create a folder named ".bpmn2config" in the project root. In this folder, create a new file named "snippets.xml" - this is where we will define the BPMN2 snippets. Copy and paste the following text into snippets.xml:

<?xml version="1.0" encoding="UTF-8"?>

<runtime id="org.eclipse.bpmn2.modeler.runtime.none">
		<toolPalette
			id="org.bpmn2.modeler.toolpalette.my.full"
			profile="Full">

			<category id="org.bpmn2.modeler.toolpalette.default.categories"/>
			<category id="org.bpmn2.modeler.toolpalette.my.snippets" name="Snippets">
				<tool name="Two Tasks" description="Two Tasks connected by a SequenceFlow">
					<object type="Task 1" id="task1"/>
					<object type="Task 2" id="task2"/>
					<object type="SequenceFlow[source='task1',target='task2']"/>
				</tool>
			</category>
			
		</toolPalette>
		
</runtime>

This XML deserves some explanation:

• Since we are not too concerned about defining our own extension plugin at this time, we will simply extend the "None" or default runtime behavior of the editor. This is identified by the first element (runtime) in this example - the id "org.eclipse.bpmn2.modeler.runtime.none" is the unique ID for the "None" runtime. Once we have finalized our Tool Palette extension, we can copy the XML from here into our extension's plugin.xml which, presumably, defines its own runtime ID.
• The next element (toolPalette) defines a Tool Palette extension. The id is required and uniquely identifies this Tool Palette. The profile is also required and references a Tool Profile defined in the "None" runtime.
• The category elements correspond to Tool Palette "drawers". These are the groupings of tool items, for example "Tasks", "Gateways" and "Events" and are identified in the Tool Palette by a folder icon. The first category in the above XML references a default set of Tool Palette Drawers which includes all of the BPMN2 modeling elements. Whether or not a tool item is visible in its tool drawer depends on the modelEnablement extension. See the Extension Point Schema document for more information.
• The second category element is where we will add our tool items. Again, an id and name are required for this element.
• The tool element defines a tool drawer tool that, when clicked and dragged onto the canvas, will create one or more BPMN2 modeling elements on the canvas. Note that the id and tool name are required. The name will appear in our Tool Palette Drawer. An optional description may also be provided - this will be displayed in a tooltip when hovering the mouse over the tool name. An optional icon can also be specified here.
• Since a tool drawer may contain many tool items, our category element will contain one or more tool item definitions, but for now we will concentrate on only one tool entry.
• Each tool will have one or more object definition elements. These are the elements that are used to define the BPMN2 model object (or objects) that the tool will create. In this example, the "Two Tasks" tool simply creates two Task elements connected with a SequenceFlow