Creative Modeler Architect Edition User Guide

Getting Acquainted with Creative Modeler 2

Crafting a Profile: [profile name].cmprofile. 4

When you are ready to deploy the profile, click the button in the toolbar resembling an envelope (“Deploy Profile”) and select the profile you wish to deploy.Crafting a Profile: configuration.xml 4

Crafting a Profile: configuration.xml 5

Crafting a Profile: Grammars. 9

Crafting a Profile: Recompose XSLTs. 14

Crafting a Profile: Output XSLs. 14

Crafting a Profile: Custom Classes. 15

Crafting a Profile: Automation. 15

Crafting a Profile: Demo Profile. 16

Overview

Congratulations on purchasing Creative Modeler architect edition. Creative Modeler is used for creating custom diagrams that can import and export custom file formats. Diagrams consist of symbols and relationships (collectively referred to as “interface elements”.) There is a one-to-many relationship between model elements and the interface elements that represent them. This document will instruct you on how to use Creative Modeler, including how to create and deploy profiles. You will be creating a number of XML files and a few classes in .NET. You will always create a “.profile” to describe your deployment schema, and craft “configuration.xml” to (among other things) expose your model and interface element types. You will also create a class to represent each of your model and interface element types, and XML files (grammars and XSLTs) to describe any data translations that are necessary.

The Basics

Getting Acquainted with Creative Modeler

After you launch Creative Modeler for the first time, you will need to create a project. Your project will contain your individual model and interface elements. You can do this using the “New Project” option in the “File” menu. After you create a project, you can save it (Creative Modeler projects have a “.cmproject” extension) and then re-open it another time (“Open”, “Save”, as well as “Save As…” are available from the “File” menu.)

To the right of the drawing surface, you will see a tab titled “Artifacts.” If you move your mouse cursor over this tab, you will see a hierarchy which will contain all of the model elements that you will create. You can drag model elements from the artifact tree onto the diagram, and an interface element will be created for it. By default, the artifact tree is only visible when the mouse cursor is over it, in order to maximize the visible drawing surface. You can change this by clicking the “Auto Hide” button in the upper-right hand corner of the artifact tree, and change it back by clicking it again.

To the left of the drawing surface, you will see a tab titled “Elements.” If you move your mouse cursor over this tab, you will see a toolbox containing all of the interface elements (symbols and relationships) that you can create, categorized by diagram type. If you click on one of the symbols, it will create an interface element in the current diagram and a corresponding model element in the artifact tree. If you click on one of the relationships, it will create an interface element in the current diagram, and a corresponding model element (which will not appear in the artifact tree.) You can also create elements using the “New Relationship” menu and the “New [diagram type] Object” menus, under the “Diagram” menu. For convenience, many of these menu items have keyboard shortcuts associated with them.

Above the drawing surface you will see a toolbar. The toolbar has buttons that allow you to quickly invoke custom commands, as well as built-in operations such as creating a new diagram.

Creating Diagrams

When you create a new project, Creative Modeler creates a blank free-form diagram automatically. In the diagram (also referred to as the “drawing surface”), you can drag elements around individually, or click and drag to select a number of elements to move as a group. You can modify the properties of an element by right clicking on it, in either the diagram or the artifact tree, and clicking “Properties.” Interface elements can be deleted by right clicking on them and choosing “Delete from Diagram.” This will not delete the corresponding model element from the artifact tree. If you would like to delete the model element, and all corresponding interface elements, right click on either the model element itself (in the artifact tree) or a corresponding interface element, and click “Delete from Model.”

After you create a relationship, you can drag each end onto a symbol, and then moving that symbol will also move the associated vertex of the relationship. To un-associate the relationship, simply drag the vertex off of the element, or click on the relationship and move it away individually. You can print the diagram, or export it to an image file using the “Print…” and “Export…” menu items under the “Diagram” menu. The drawing size of the diagram, as well as the name, and what type of diagram it is (which determines what symbols can be added) can be set by clicking on the “Diagram Properties” menu item under the “Diagram” menu (or alternatively, you can right click on the drawing surface and click “Properties.”) You can create a new diagram by choosing “New Diagram” under the “Diagrams” menu (or alternatively, you can click the button on the toolbar that looks like a blank sheet of paper.) You may switch between diagrams using the tabs between the drawing surface and the toolbar.

Importing and Exporting Files

There are three commands that are used for importing and exporting files, all of which are available from the “Artifact” menu, or by right clicking on the “Files” node under the root project node in the artifact tree. “Add Existing File…” imports a file into your project. “Generate code” updates a previously-imported file with any relevant changes that have been made in Creative Modeler. “Refresh Model” updates your project with any changes that have been made to a previously-imported file by an external program (such as a text editor.)

Creating Software Diagrams

Creative Modeler architect edition comes with built-in support for UML and Entity/Relationship diagrams, as well as round-trip engineering (importing and exporting) of C# source files and T/SQL scripts (although only a subset of T/SQL is supported.) Microsoft Visual Studio .NET 2003 project files (“.csproj” files, referred to as “components” in Creative Modeler) can be imported using the “Add Component…” command, available from either “Artifact” menu, or the button resembling a puzzle piece in the toolbar. Microsoft Visual Studio .NET 2003 solution files (“.sln” files, referred to as “component groups” in Creative Modeler) can also be imported, using the “Add Component Group…” command, invoked in the toolbar using the button resembling two overlaid puzzle pieces.

Extensibility

Creating a Profile

Profiles are customized versions of Creative Modeler that are created by architect edition users, and deployed to basic edition users. To create one, invoke the “Create Profile…” command by clicking on the button in the toolbar that resembles an asterisk. In the dialog box that comes up, enter the name of the profile you would like to create. After clicking “Ok”, a project is created for you in a sub-directory with the same name as the project, under the main Creative Modeler directory.

Crafting a Profile: [profile name].cmprofile

Under the profile directory that was created by Creative Modeler, there is a file with the same name as the profile, and a “.cmprofile” extension that contains details about deployment targets. You will need to customize this file to contain the particulars of your deployment schema. The file that is created looks like the following:

<installation name="Sample Install"

computer="localhost"

path="c:\SampleProfile" />

</installations>

</profile>

For each deployment target, there will be an “installation” node under “profile/installations.” The value in the “name” attribute should describe the target, (for example, “Bill Smith’s Workstation”.) The value in the “computer” attribute should be the actual name of the computer, or “localhost” to create a test installation on the development workstation. The value in the “path” attribute should be the path to the installation directory on the deployment target.

When you are ready to deploy the profile, click the button in the toolbar resembling an envelope (“Deploy Profile”) and select the profile you wish to deploy.
Crafting a Profile: configuration.xml

In the profile directory, an instance of configuration.xml is created which will be propagated to the basic edition users. The configuration file contains information about available symbols, relationships, translations and commands, as well as the structure of the artifact tree. The structure for the latter is as follows:

<nodes>

<menu>

<item name="Add Existing"

command="AddExisting" />

</menu>

</node>

</node>

</node>

</node>

</nodes>

…

For every node in the artifact tree (except the root), there is a “node” node under the “/configuration/nodes” node. “node” nodes can be contained within other “node” nodes to represent the hierarchical structure of the tree. The value in the “name” attribute of the “node” node contains the text of the node. The value in the “icon” attribute is the name of the 16x16 pixel icon in the “i” directory under the installation directory. Each “node” node may contain a “menu” node, which contains all of the verbs that are available by right clicking on that node. Each verb is represented by an “item” node under the “menu” node. The “item” node has a “name” attribute, whose value is the text displayed in the context menu, and a “command” attribute, whose value is the name of the command that will be executed if the user clicks on that verb.

All commands that can be directly invoked by the user are represented by a “command” node within the “/configuration/commands” node. The command node has an “id” attribute, whose value is the name that is referenced in the “name” attribute of the “menu/item” node. The command node also has an “icon” node, whose value is the filename of the 16x16 pixel icon contained in the “i” directory under the installation directory. Lastly, the command node contains a “class” node that references a class that implements the “SDA.ICommand” interface, and contains the logic of the command. The class node has a “component” attribute whose value represents the name of the .NET assembly containing the class. The value in the “name” attribute represents the fully qualified (namespace and name) of the class. An example of the syntax is below:

…

</command>

<class component="SDA.Commands"

name="SDA.Commands.GenerateCode" />

</command>

</command>

</commands>

…

Each symbol (an interface element) type is represented by a “symbol” node under the “/configuration/symbols” node. The “symbol” node has a “name” attribute whose value is the name that will represent the symbol type in the toolbox. The value in the “icon” attribute is the filename of the 16x16 pixel icon in the “i” directory under the installation directory. There is an optional “shortcut” node, whose value is a textual representation of the keyboard shortcut (accepted values are members of the “Shortcut” enumeration in the .NET 1.1 Framework) that can be used to create an instance of the symbol in the current diagram. Each symbol also has a “view” and a “model” node under it. The “view” node contains a class node (see above paragraph for details on the structure of the class node) that describes the class which contains the logic for the interface element (and implements the interface “SDA.ISymbol.”) The “model” node contains a class node that describes the class which contains the logic for the underlying model element (and extends the base class (“SDA.ArtifactModel.”) An example of the syntax is below:

…

<view>

</view>

<model>

</model>

</symbol>

</symbols>

…

Each relationship that can be used in a diagram is represented by a “relationship” node under the “/configuration/relationships” node. The relationship node has a “name” attribute whose value is the name that will represent the relationship in the toolbox. The value in the “shortcut” node is a textual representation of the keyboard shortcut that can be used to create an instance of the relationship in the current diagram. The value in the “icon” node is the filename of the 16x16 pixel icon contained in the “i” directory under the installation directory. The relationship node also contains a class node that describes the class that contains all of the logic for the relationship (and extends the base class “SDA.Relationship.”) An example of the syntax is below:

…

<relationship name="Association"

shortcut="Ctrl2" icon="Association.jpg">

</relationship>

</relationships>

…

Each diagram type is represented by a “diagram” node under the “/configuration/diagrams” node. The diagram node has a “name” attribute, the value of which is the name that will appear in the diagram type drop down in the diagram properties window. The diagram node also contains a “symbol” node for each symbol that is allowed in the diagram. The symbol node has a “name” attribute, which refers to the value in the “name” attribute of a symbol node under the “symbols” node. An example of the syntax is below:

…

</diagram>

</diagrams>

…

Each custom translator is represented by a “translator” node under the “/configuration/translators” node. The translator node has a “namespace” attribute and a “name” attribute, whose concatenated values, together with a delimiting period, represent the fully qualified name that is referenced by the “name” attribute of a “translator” node, indirectly under a “language” node (which is described in the next paragraph.) The translator node also contains a class node that describes the class that contains the translation logic (and implements the interface “SDA.ITranslator.”) An example of the syntax is below:

…

</translator>

</translators>

…

Each file format that can be imported or exported is represented by a “language” node under the “/configuration/languages” node. The language node has a “name” attribute, whose value will appear as the description in the file type drop down when importing a source file. The value in the “language-type” attribute can either be “Source”, “Component” or “ComponentGroup”. A value of “Component” means that the language represents a list of source files. A value of “ComponentGroup” means the language represents a list of components. The extensibility interface does not yet support components and component groups. A value of “Source” means the language is a normal source language. The language node contains an “extensions” node, which in turn contains one or more “extension” nodes, whose contained text refer to a file extension that is associated with that language. These values are also used by the file type drop down you will see when importing a source file. Each “language” node will also contain a “builder” node, which in turn contains an “import” and an “export” node. The import node contains one or more translator nodes that are used for importing a source file. The input to the first translator is the original file, and the input to each subsequent translator is the output from the previous translator. Each translator node has a “name” attribute that refers to either a built-in translation, or is the fully qualified name of a custom translator (see previous paragraph for details on custom translators.) The “argument” attribute of the translator node is an optional single, textual argument that will be passed to the translator. The built-in translator “SourceTransform” is used for translating non-XML data into XML data. The argument that is passed to it is the filename of the XML grammar file that describes the source language’s structure. The built-in translator “XslTransform” is used for translating XML data into either a different XML format, or a non-XML format. The argument that is passed to it is the name of the XSL file. The “export” node has the same format as the “import” node, and is used for exporting the source files. An example of this syntax is the following:

…

</extensions>

<translator name="SourceTransform"

argument="sql.xml" />

</import>

</export>

</builder>

</language>

</languages>

</configuration>

Crafting a Profile: Grammars

In order to translate a non-XML file into XML, you will create a grammar to describe the structure of the language. Grammars are themselves XML documents with a “.cmgrammar” extension, and are located in the “grammars” directory under the main Creative Modeler directory. In Creative Modeler, grammars are based on the concept of context-free grammars, which are a hierarchy of symbols that describe the rules of the language. The root node of a grammar document is the “cfg” node, which contains an unordered set of “symbol” nodes. It also has a “KEYWORDS_SENSITIVE” attribute, which is either “true” or “false”, depending on whether or not keywords in the described language are case sensitive. An example of this syntax is below:

...

Symbol nodes come in a variety of formats. The one you see below describes the format of comments (data which should not be interpreted) within the source language. Symbol nodes always have a “name” attribute. For this particular type of symbol, the value of the name attribute is always “Ignore.” The ignored symbol is a specialized version of the variable symbol (more on these later), and thus it has a “variable” attribute and an “allowChars” attribute, that for this type, are always set to “Nothing” and “ “, respectively. This type of symbol also contains an “Ignore” node, which in turn contains one or more “DataBetween” nodes. Each “DataBetween” node describes a pair of character strings which encapsulate a comment in the described language. If data falls in between the start and end markers of any of the “DataBetween” nodes, it will be ignored. The start marker is represented by the value in the “start” attribute, and the end marker is represented by the value in the “end” attribute.

…

<symbol name="Ignored"

variable="Nothing" allowChars=" ">

</Ignore>

</symbol>

…

All grammars have a top level symbol, whose name is always “SOURCEFILE.” This node can conform to any of the symbol types which are described hereafter, including the “delegate” type (shown below.) A delegate symbol is simply an alias for another symbol, which can optionally attach a “meaning” or “capture” (these are described later.) Also note that delegate symbols will have unique, user-defined names when used outside of the root “SOURCEFILE” node. The name of the aliased symbol is represented by the value in the “name” attribute of the contained subordinate “symbol” node.

…

</symbol>

…

Another type of symbol is the “sequence” type. These symbols are used to represent a sequence of two other symbols (a logical “AND”.) Sequence symbols have unique, user-defined names, as do all of the other symbol types described hereafter (represented by the value in the “name” attribute.) They contain a “sequence” node, which in turn contains exactly two subordinate symbol nodes. The ordering of the nodes determines the ordering of the symbols in the sequence. The example below shows a sequence symbol, which also has a “meaning” attached to it. Meanings can be attached to any symbol type, and are represented by the “meaning” attribute. Attaching a meaning to a symbol will cause any XML generated farther down the parse tree to be enclosed in a node that will have the name that is specified in the value of the meaning attribute.

…

</sequence>

</symbol>

…

To represent two symbols, of which either one, but not both, will be accepted (a logical “OR”), use a “choice” symbol. Choice symbols contain a “choice” node, which in turn contains exactly two subordinate symbol nodes. The ordering of the nodes determines the order in which the parser will try each choice. The example below shows a choice node, where one of the choices is a special value called “Nothing.” This is how symbols can be made optional. First, the parser will try the first choice, and if it is not a match, the outer symbol will still be satisfied. Note that an actual symbol name can be specified for the second subordinate symbol, instead of “Nothing”. In that case, the parser will require that one of the two subordinate symbols be satisfied in order to satisfy the outer symbol.

…

</choice>

</symbol>

…

To represent data that should be captured in an XML node, use a “variable” symbol. Variable symbols have a “variable” attribute, whose value is the name of the XML node that will be created. These type of symbols also contain either an “allowChars” attribute, or a “disallowChars” attribute, but not both. The value in the allowChars attribute is a string, which indicates what characters are allowed in the contained data. The string is a set of comma delimited character ranges and characters. The disallowChars attribute works the same way as the allowChars attribute, except it specifies the characters which are not allowed in the contained data. The parser will cease processing the current symbol when it encounters a character which is not allowed. Variable symbols do not contain any other nodes. An example of this syntax is shown below:

…

<symbol name="FILEGROUP" variable="file-group"

allowChars="a-z,A-Z,0-9,_,[,]" />

…

To represent a keyword, use a “constant” symbol. Constant symbols have a “constant” attribute, whose value is the text of the keyword. Constant symbols do not contain any other nodes. An example of this syntax is shown below:

…

…

To represent a recursive symbol, a “sequence” node may appear in a choice symbol in place of the second subordinate symbol. The sequence node will contain exactly two subordinate symbols, the second of which is generally the outer symbol itself. Logically, the example below says “match on either the symbol ‘GO’, or ‘GO’ followed by ‘GOS.’”

…

</sequence>

</choice>

</symbol>

…

To capture all of the data that is processed farther down the parse tree, attach a “capture” attribute to any of the aforementioned symbol types. The value in the capture attribute specifies the name of the XML node that will encapsulate the captured data. This functionality is generally used when you want to capture a block of data, but the delimiting character string may appear in the data itself. An example of this syntax is shown below:

…

</choice>

</symbol>

</sequence>

</choice>

</symbol>

</sequence>

</symbol>

</sequence>

</symbol>

</sequence>

</symbol>

</choice>

</symbol>

</cfg>

Crafting a Profile: Recompose XSLTs

In order to translate XML data (for example: the output resulting from parsing a non-XML file using a grammar) into a set of model elements, you will create a recompose XSLT (XML Style sheet Language Transform) and put it into the “XSLs” directory under the main Creative Modeler directory. Recompose XSLTs will create XML documents like the one shown below. The root node is always “SourceFile”, and all directly contained nodes will have names that correspond to an artifact name that is defined in configuration.xml (see Crafting a Profile: configuration.xml.) When Creative Modeler imports this “model-ready” XML, it will create a new instance of the correct artifact (model element) for each node directly contained by the root node. It will then set [ArtifactType].Xml to the text of the node, and it is the job of the artifact to populate all of its attributes based on the XML. Recomposes are also used to creation relationships between the model elements.

<Table>

<file-group><![CDATA[DEFAULT]]></file-group>

</columns>

</Table>

<identifier>Table A</identifier>

<type>Table</type>

</participant>

<identifier>Table B</identifier>

<type>Table</type>

</participant>

</participants>

</relationship>

</SourceFile>

Crafting a Profile: Output XSLs

Regardless of whether or not a language’s native format is XML-based, you will create an output XSL (XML Style sheet Language) to transform it from its model-ready format (see above) back into its native format. This file goes into “XSLs” directory under the main Creative Modeler directory.

Crafting a Profile: Custom Classes

For each model element that you make, you will create a class which extends the base class “SDA.ArtifactModel.” Model elements that are referred to by other model elements should implement the interface “SDA.IRelatedArtifact”. Model elements that can be imported and exported, but their order within the source file is of no consequence, should implement the interface “SDA.ISourcableArtifact”. If the order within the source file matters, the model element should implement the interface “SDA.IOrderedArtifact” instead.

For each simple interface element that will represent a model element, you will create a class which extends the base class “SDA.BaseSymbol” (called a “symbol type.”) For symbols which must have non-rectangular boundaries, you must implement the interface “SDA.ISymbol” instead and populate the Controls collection with each piece of the interface (each of which must have rectangular boundaries.)

For each custom command that you would like to execute from within Creative Modeler, you will create a class which implements either the “SDA.ICommand” interface or the “SDA.ILongCommand” interface. Commands which take a short amount of time to execute will implement “SDA.ICommand”, while longer commands will implement “SDA.ILongCommand”, which has members that support interaction with the translation dialog (which illustrates progress to the user during execution.)

For each custom translator that will be used to import or export data (such as the “SDA.GoTranslator”, employed in Crafting a Profile: configuration.xml) you will create a class that extends the base class “SDA.Translator.” Custom translators are used to perform a translation which cannot be accomplished using a built-in translator.

Crafting a Profile: Automation

The automation interface allows developers to perform translations from within their own .NET applications and batch files.

.NET Automation: Translations can be performed dynamically by calling one of the Import or Export methods in the SDA.Automation.Automation class (which resides in the SDA.Automation component.) There are two flavors of each method. The first one takes the input data and the language name, and returns the output data. The second one takes a list of input data, a list of corresponding languages, and returns a list of output data. The second flavor is provided to minimize the amount of time spent checking registration when translating multiple source documents. The Import methods execute the “import” portion of the referenced language, as defined in configuration.xml (see Crafting a Profile: configuration.xml.) The Export methods execute the “export” portion. You must copy the contents of the main Creative Modeler directory (and all sub-directories) to the working directory of your application, and reference SDA.Automation.dll.

Command-line Automation: Translations can also be performed dynamically by using the command-line tool “Translate.exe”. The command-line tool has a “/import” and a “/export” switch, which execute the “import” and “export” portion of the referenced language (see above.) Both switches are followed by the language name, the path to the input file, and the path to the output file.

Crafting a Profile: Demo Profile

The demo profile is a sample implementation of Creative Modeler, and is available for download on our website. It allows the user to import and export a simple project plan in CSV (comma-delimited) format. Importing a project plan creates a set of Task artifacts (model elements) and relationships between them (representing task dependencies.) The following is a list of some of the files provided:

configuration.xml: A sample configuration file including only things related to project plans.

DemoProfile.cmprofile: A sample profile for deploying to basic edition users

DemoProfile.csproj: A .NET project containing all C# files, except for TestProjectPlan.cs

DemoProfile.csv: A sample project plan in CSV format (input file)

DemoProfile.sln: A .NET solution containing DemoProfile.csproj

projectplan.cmgrammar: A sample grammar for importing tasks

projectplan.xsl: A sample output XSL for exporting project plans

projectplan_recompose.xslt: A sample recompose XSLT for importing tasks and dependency relationships.

Task.cs: A sample model element representing a task

TaskDependencyRelationship.cs: A sample relationship representing a task dependency

TaskSymbol.cs: A sample interface element representing a task

TaskCommand.cs: A sample command

TestTranslator.cs: A sample translator

TestProjectPlan.cs: A sample NUnit unit test for importing and exporting project plans

When compiling DemoProfile.csproj, you must add the main Creative Modeler directory as a referenced path. After you build the DLL, you must copy it into the main Creative Modeler directory. Additionally, you should copy Task.jpg into the “i” sub-folder, and projectplan.cmgrammar goes into the “grammars” sub-folder. Next, copy projectplan.xsl and projectplan_recompose.xslt into the “XSLs” sub-folder. Backup configuration.xml in the main Creative Modeler directory, and copy in the configuration.xml provided in the demo profile. Now, when you launch creative modeler, you will be able to import and export project plans, and create new tasks and dependency relationships.