{"id":96,"date":"2008-02-29T00:05:02","date_gmt":"2008-02-28T22:05:02","guid":{"rendered":"http:\/\/www.ticklishtechs.net\/2008\/02\/29\/connectors-between-compartment-shape-entries-with-dsl-tools-part-2\/"},"modified":"2020-08-13T20:46:56","modified_gmt":"2020-08-13T18:46:56","slug":"connectors-between-compartment-shape-entries-with-dsl-tools-part-2","status":"publish","type":"post","link":"https:\/\/www.ticklishtechs.net\/2008\/02\/29\/connectors-between-compartment-shape-entries-with-dsl-tools-part-2\/","title":{"rendered":"Connectors between compartment shape entries with DSL Tools &#8211; part 2"},"content":{"rendered":"<p>[<strong>Update (2008-05-21): <\/strong>This code is now hosted at CodePlex as part of <a href=\"http:\/\/www.codeplex.com\/JaDAL\">JaDAL<\/a>. And a <a href=\"http:\/\/www.ticklishtechs.net\/2008\/05\/21\/connectors-between-compartment-shape-entries-with-dsl-tools-version-2\/\">follow-up article<\/a> was published.]<\/p>\n<h3>Previously on&#8230;<\/h3>\n<p>This article is part of a series. A table of contents can be found at the end of the <a href=\"http:\/\/www.ticklishtechs.net\/2008\/02\/29\/connectors-between-compartment-shape-entries-with-dsl-tools-part-1\/\">first article<\/a>. In that article you can also find a brief overview.<\/p>\n<ul><\/ul>\n<h3>User guide<\/h3>\n<p>If you read this article to this point you will properly use or at least evaluate the CompartmentMapping library. I will provide you with a step-by-step tutorial. There are pretty some steps, but its the shortest way I could imagine to create my solution. Please give it a try. \ud83d\ude42<\/p>\n<ol>\n<li>You need <a href=\"http:\/\/code.msdn.microsoft.com\/TTxGen\">TTxGen<\/a> to generate some code from my templates. See <a href=\"http:\/\/www.ticklishtechs.net\/2008\/02\/28\/codegeneration-with-codesmith-and-orcas-t4\/\">my last article<\/a> for more information and a workaround for an installation problem.       <\/li>\n<li>I assume you have a DSL solution and at least two <em>Domain Classes<\/em> mapped to two compartment shapes and two more <em>Domain Classes<\/em> used as entries of the compartment shapes created. In my example these classes are called <code>Parent1<\/code>, <code>Entry1<\/code>, <code>Parent2<\/code> and <code>Entry2<\/code>.       <br \/>The entries need a unique identifier. You could use a name property for this, but there will be some difficulties if the user creates two entries in one shape with the same name, so I will use a guid. (Don&#8217;t forget to create a new guid in the constructor or another proper place.)       <\/li>\n<li>Create a <em>Reference Relationship<\/em> from <code>Parent1<\/code> to <code>Parent2<\/code>. This will be automatically named <code>Parent1ReferencesParent2<\/code>. We will use this reference to present the relationship from one entry to the other. I would like to create <em>Reference Relationships<\/em> from this relationship to the entries, but relationships of relationships are not supported. We have to store the guids of the entries in the relationship and add two <em>Domain Properties<\/em> for this purpose to it. I named them <code>fromEntry<\/code> and <code>toEntry<\/code>.       <br \/><a href=\"http:\/\/www.ticklishtechs.net\/wp-content\/uploads\/2008\/02\/dsldefinition.png\"><img loading=\"lazy\" style=\"border-top-width: 0px; border-left-width: 0px; border-bottom-width: 0px; border-right-width: 0px\" height=\"298\" alt=\"DslDefinition\" src=\"http:\/\/www.ticklishtechs.net\/wp-content\/uploads\/2008\/02\/dsldefinition-thumb.png\" width=\"440\" border=\"0\" \/><\/a>&#160; <\/li>\n<li>Set the <code>Allows Duplicates<\/code> property of the <code>Parent1ReferencesParent2<\/code> relationship to <code>true<\/code>.       <\/li>\n<li>Set the <code>Is Custom<\/code> property of the <em>Connection Builder<\/em> (<code>Parent1ReferencesParent2Builder<\/code>) in the <em>DSL Explorer<\/em> to <code>true<\/code>.       <\/li>\n<li>Add a reference to <code>CompartmentMapping.dll<\/code> to both the <code>Dsl<\/code> and <code>DslPackage<\/code> project.       <\/li>\n<li>Add a new xml file (in my example <code>CompartmentMappings.xml<\/code>) to your solution and write the following code in it:\n<pre class=\"code\"><span style=\"color: blue\">&lt;?<\/span><span style=\"color: #a31515\">xml <\/span><span style=\"color: red\">version<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">1.0<\/span>&quot; <span style=\"color: red\">encoding<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">utf-8<\/span>&quot; <span style=\"color: blue\">?&gt;\r\n&lt;<\/span><span style=\"color: #a31515\">CompartmentConnections\r\n    <\/span><span style=\"color: red\">xmlns:xsi<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>&quot;\r\n    <span style=\"color: red\">xsi:noNamespaceSchemaLocation<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">CompartmentMappings.xsd<\/span>&quot;\r\n    <span style=\"color: red\">namespace<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">BenjaminSchroeter.CompartmentMappingExample<\/span>&quot; <span style=\"color: blue\">&gt;\r\n  &lt;<\/span><span style=\"color: #a31515\">CompartmentConnection<\/span><span style=\"color: blue\">&gt;\r\n    &lt;<\/span><span style=\"color: #a31515\">CompartmentSource<\/span><span style=\"color: blue\">&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">DomainClass <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">Parent1<\/span>&quot;<span style=\"color: blue\">\/&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">EntryDomainClass <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">Entry1<\/span>&quot;<span style=\"color: blue\">\/&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">Shape <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">CompartmentShape1<\/span>&quot; <span style=\"color: blue\">\/&gt;\r\n    &lt;\/<\/span><span style=\"color: #a31515\">CompartmentSource<\/span><span style=\"color: blue\">&gt;\r\n    &lt;<\/span><span style=\"color: #a31515\">CompartmentTarget<\/span><span style=\"color: blue\">&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">DomainClass <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">Parent2<\/span>&quot; <span style=\"color: blue\">\/&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">EntryDomainClass <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">Entry2<\/span>&quot; <span style=\"color: blue\">\/&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">Shape <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">CompartmentShape2<\/span>&quot; <span style=\"color: blue\">\/&gt;\r\n    &lt;\/<\/span><span style=\"color: #a31515\">CompartmentTarget<\/span><span style=\"color: blue\">&gt;\r\n    &lt;<\/span><span style=\"color: #a31515\">Connection <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">Parent1ReferencesParent2<\/span>&quot;<span style=\"color: blue\">&gt;\r\n      &lt;<\/span><span style=\"color: #a31515\">Shape <\/span><span style=\"color: red\">name<\/span><span style=\"color: blue\">=<\/span>&quot;<span style=\"color: blue\">Connector<\/span>&quot; <span style=\"color: blue\">\/&gt;\r\n    &lt;\/<\/span><span style=\"color: #a31515\">Connection<\/span><span style=\"color: blue\">&gt;\r\n  &lt;\/<\/span><span style=\"color: #a31515\">CompartmentConnection<\/span><span style=\"color: blue\">&gt;\r\n&lt;\/<\/span><span style=\"color: #a31515\">CompartmentConnections<\/span><span style=\"color: blue\">&gt;<\/span><\/pre>\n<p>(If you place the xsd file in the same directory you get IntelliSense and error checking for free.)<\/p>\n<\/li>\n<li>Place the <code>CompartmentConnections.tt<\/code> file in the same directory and right-click on the xml file and choose <em>Generate xGen Template<\/em>. A <code>CompartmentMappings_xGen.tt<\/code> file will be created below the xml file and there you have to add the following lines:\n<pre class=\"code\"><span style=\"background: gold\">&lt;#@<\/span><span style=\"color: red\"> ParentFileInjector processor=<\/span>&quot;<span style=\"color: blue\">TTxGenDirectiveProcessor<\/span>&quot; \r\n    <span style=\"color: red\">requires=<\/span>&quot;<span style=\"color: blue\">fileName='CompartmentMappings.xml'<\/span>&quot; <span style=\"background: gold\">#&gt;\r\n&lt;#@<\/span><span style=\"color: red\"> <\/span><span style=\"color: brown\">include <\/span><span style=\"color: red\">file=<\/span>&quot;<span style=\"color: blue\">CompartmentConnections.tt<\/span>&quot; <span style=\"background: gold\">#&gt;<\/span><\/pre>\n<p>(Be sure you use the right xml file name here.)<\/p>\n<p>Now press the <em>Transform All Templates<\/em> Button in the <em>Solution Explorer <\/em>to generate the the code from this template.<\/p>\n<\/li>\n<li>Now you have to write code by yourself (nearly by yourself, the frames are generated, too). Take a look at the generated cs file <code>CompartmentConnections_xGen.cs<\/code>.\n<p>At the top you will find commented code. Copy this code to a new cs file and remove the comments. All code you will write for the compartment mappings you will write in this file.<\/p>\n<\/li>\n<li>Complete the <code>CreateElementLink()<\/code> method in this file. Here you have to add code to store the selected compartment entries for source and target in the properties of the relationship (see 3).\n<pre class=\"code\"><span style=\"color: blue\">protected override <\/span><span style=\"color: #2b91af\">ElementLink <\/span>CreateElementLink(<span style=\"color: #2b91af\">Parent1 <\/span>source,\r\n  <span style=\"color: #2b91af\">SelectedCompartmentPartType <\/span>sourcePartType,\r\n  <span style=\"color: #2b91af\">Entry1 <\/span>sourceEntry,\r\n  <span style=\"color: #2b91af\">Parent2 <\/span>target,\r\n  <span style=\"color: #2b91af\">SelectedCompartmentPartType <\/span>targetPartType,\r\n  <span style=\"color: #2b91af\">Entry2 <\/span>targetEntry)\r\n{\r\n    <span style=\"color: #2b91af\">Parent1ReferencesParent2 <\/span>result = \r\n        <span style=\"color: blue\">new <\/span><span style=\"color: #2b91af\">Parent1ReferencesParent2<\/span>(source, target);\r\n<strong>    result.fromEntry = sourceEntry.Guid;\r\n    result.toEntry = targetEntry.Guid;<\/strong>\r\n    <span style=\"color: blue\">return <\/span>result;\r\n}<\/pre>\n<\/li>\n<li>In the <code>CreateElementLink()<\/code> method you have stored the source and target entry information somewhere; my library does not know about this location. So we need two more methods to compare an entry with a relationship and answer the question &quot;Is this entry the source of a given relationship?&quot; and the same for the target. These code resists in the same file:\n<pre class=\"code\"><span style=\"color: blue\">public override bool <\/span>IsEntryConnectionSource\r\n    (<span style=\"color: #2b91af\">Entry1 <\/span>entry, <span style=\"color: #2b91af\">Parent1ReferencesParent2 <\/span>connection)\r\n{\r\n<strong>    <span style=\"color: blue\">if <\/span>(entry == <span style=\"color: blue\">null<\/span>)\r\n        <span style=\"color: blue\">return false<\/span>;\r\n    <span style=\"color: blue\">return <\/span>connection.fromEntry.Equals(entry.Guid);<\/strong>\r\n}\r\n<span style=\"color: blue\">public override bool <\/span>IsEntryConnectionTarget\r\n    (<span style=\"color: #2b91af\">Entry2 <\/span>entry, <span style=\"color: #2b91af\">Parent1ReferencesParent2 <\/span>connection)\r\n{\r\n<strong>    <span style=\"color: blue\">if <\/span>(entry == <span style=\"color: blue\">null<\/span>)\r\n        <span style=\"color: blue\">return false<\/span>;\r\n    <span style=\"color: blue\">return <\/span>connection.toEntry.Equals(entry.Guid);<\/strong>\r\n}<br \/><\/pre>\n<p>Always care for <code>entry == null<\/code> this will be used to check whether the head of the shape is meant. Even if you do not allow the head as source or target this method will be called with a <code>null<\/code> parameter from time to time.<\/p>\n<\/li>\n<li>Create a <code>partial class<\/code> for your <em>Domain Model <\/em>(<code>CompartmentMappingExampleDomainModel<\/code>) and add the following methods.\n<pre class=\"code\"><span style=\"color: blue\">protected override <\/span><span style=\"color: #2b91af\">Type<\/span>[] GetCustomDomainModelTypes()\r\n{\r\n  <span style=\"color: blue\">return <\/span><span style=\"color: #2b91af\">CompartmentMappingUtil<\/span>.AllCompartmentMappingRules(<span style=\"color: blue\">this<\/span>);\r\n}<\/pre>\n<p>(If you have already some custom rules, you can use an overloaded version of the <code>AllCompartmentMappingRules()<\/code> method.)<\/p>\n<\/li>\n<li>\n<p>In the <code>DslPackage<\/code> project create a <code>partial class<\/code> for the generated <em>Command Set<\/em> and add the following code:<\/p>\n<pre class=\"code\"><span style=\"color: blue\">protected override <\/span><span style=\"color: #2b91af\">IList<\/span>&lt;<span style=\"color: #2b91af\">MenuCommand<\/span>&gt; GetMenuCommands()\r\n{\r\n    <span style=\"color: blue\">return <\/span><span style=\"color: #2b91af\">CompartmentMappingUtil<\/span>.RemoveRerouteCommand\r\n                                (<span style=\"color: blue\">base<\/span>.GetMenuCommands());\r\n}<\/pre>\n<p><a href=\"http:\/\/11011.net\/software\/vspaste\"><\/a><a href=\"http:\/\/11011.net\/software\/vspaste\"><\/a><\/p>\n<\/li>\n<\/ol>\n<p>That&#8217;s all. Only 13 steps, a few settings and conventions and 10 lines of C# code to write. I know it is not very easy but I think it is ok. And the best: as you will see it is working.<\/p>\n<p>Now compile and start you solution. You can now create connectors from one entry of the <code>Parent1<\/code> shape to an entry of the <code>Parent2<\/code> shape. Great &#8211; isn&#8217;t it?<\/p>\n<p><img loading=\"lazy\" style=\"border-top-width: 0px; border-left-width: 0px; border-bottom-width: 0px; border-right-width: 0px\" height=\"319\" alt=\"mapping\" src=\"http:\/\/www.ticklishtechs.net\/wp-content\/uploads\/2008\/02\/mapping.png\" width=\"462\" border=\"0\" \/>&#160;<\/p>\n<p>Take a look at the properties in the <em>Properties window<\/em> when selecting a connector. You see the guids of the corresponding entries and can use them in your code when working with this connections for code generation or whatever you need to do.<\/p>\n<h3>Advanced options<\/h3>\n<p>There are some more options besides the basics described above to configure and extend the compartment mappings.<\/p>\n<p>Some of them can easily turned on in the xml file:<\/p>\n<ul>\n<li>For <code>CompartmentSource<\/code> and <code>CompartmentTarget<\/code> you can specify an attribute called <code>allowHeadAsSource<\/code> (and <code>allowHeadAsTarget<\/code> respectively) and set it to <code>true<\/code>, to allow the head of the compartment shape as source or target. Remember, if you do this the <code>CreateElementLink()<\/code> method will be called with <code>null<\/code> values for the entries and you have to handle this. <\/li>\n<li>On the <code>Connection<\/code> element there are two more optional attributes, too.\n<p>If you set <code>allowSelfReference<\/code> to <code>true<\/code> the user can create connections from one entry of one shape to another (or the same) entry of the same shape (source = target). This makes only sense if you specify <code>CompartmentSource<\/code> and <code>CompartmentTarget<\/code> to be the same <em>Domain Class <\/em>and the same shape.<\/p>\n<p>With the <code>suppressEntryDeletePropagation<\/code> attribute set to <code>true<\/code> you suppress the deletion of the connection when a corresponding compartment entry is deleted. Be careful with this setting: Wrong connections will remain in your model and produce ugly diagrams.<\/p>\n<\/li>\n<li>One of source and target can be a regular shape (that is a geometry or image shape and not a compartment shape). Replace either <code>CompartmentSource<\/code> with <code>Source<\/code> or <code>CompartmentTarget<\/code> with <code>Target<\/code>. For these elements you don&#8217;t need to define a <code>EntryDomainClass<\/code> element since regular shapes do not have entries. <\/li>\n<\/ul>\n<p>You can add even more code to the C# file from step 9 to 11. There are two more methods you can override: <code>CanAcceptAsCompartmentSource()<\/code> and <code>CanAcceptAsCompartmentSourceAndTarget()<\/code>. If you do so, the DSL editor will ask your code while the user moves the mouse over shapes when creating the connection to identify the current shape and entry as a valid source or target in you scenario. It is pretty much the same pattern as used in the DSL Tools itself. But remember, this method will be called very often und should have a very short running time.<\/p>\n<h3><stroke>Download<\/stroke><\/h3>\n<p><stroke>The archive contains the library both as a compiled dll and as source code and the Example DSL created in this article.<\/stroke><\/p>\n<h3>Update<\/h3>\n<p>This code is now part of the <a href=\"http:\/\/www.codeplex.com\/JaDAL\">JaDAL &#8211; Just another DSL-Tools Addon Library<\/a> project. Please download the current version from that page. The download over at <a href=\"http:\/\/www.codeplex.com\">CodePlex<\/a> contains the source code described here, an example DSL language and the library as a binary. Future enhancements of the code will be published there, too.<\/p>\n<div class=\"wlWriterSmartContent\" id=\"scid:fb3a1972-4489-4e52-abe7-25a00bb07fdf:1f1d4156-e123-40e6-bec0-9bfe126fbf7e\" style=\"padding-right: 0px; display: inline; padding-left: 0px; padding-bottom: 0px; margin: 0px; padding-top: 0px\">\n<p><a href=\"http:\/\/www.ticklishtechs.net\/wp-content\/uploads\/2008\/03\/compartmentmapping.zip\" target=\"_blank\" rel=\"noopener noreferrer\">CompartmentMapping.zip<\/a><\/p>\n<\/div>\n<h3>Upcoming articles<\/h3>\n<p><a href=\"http:\/\/www.ticklishtechs.net\/2008\/03\/01\/connectors-between-compartment-shape-entries-with-dsl-tools-part-3\/\">Part 3<\/a> and <a href=\"http:\/\/www.ticklishtechs.net\/2008\/03\/01\/finding-and-removing-a-default-command-in-dsl-tools-part-4-of-compartment-mappings\/\">part 4<\/a> of this series will give an in depth view into the internals of the library.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>[Update (2008-05-21): This code is now hosted at CodePlex as part of JaDAL. And a follow-up article was published.] Previously on&#8230; This article is part of a series. A table of contents can be found at the end of the first article. In that article you can also find a brief overview. User guide If [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[1],"tags":[18,33,50,31,25,32],"_links":{"self":[{"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/posts\/96"}],"collection":[{"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/comments?post=96"}],"version-history":[{"count":2,"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/posts\/96\/revisions"}],"predecessor-version":[{"id":471,"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/posts\/96\/revisions\/471"}],"wp:attachment":[{"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/media?parent=96"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/categories?post=96"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.ticklishtechs.net\/wp-json\/wp\/v2\/tags?post=96"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}