These Templates Are Driving Me Crazy

[Stephen Kropp]

I have been messing with various template options for a couple days and I can't seem to get something to work 100% so please help me get this solved! I feel like I am very close but everything I try breaks something else or gets me worse off.

I am trying to display one template when showing requirement details, and another for everything else.

The content I am trying to display is arranged in multiple packages like this:
<root package>
<package 1><package 1 notes></package 1>
<package 2><package 2 notes><Behavioral Diagram 1><Behavioral Diagram 1 Notes><Behavioral Diagram 1 Embedded Blocks><Behavioral Diagram 1 Embedded Block Notes></package 2>
<package 3><package 3 notes><Use Case Diagram 1><Use Case Diagram 1 Notes><Use Case Diagram 1 Embedded Use Cases><Use Case Diagram 1 Embedded Use Case Notes></package 3>
<package 4><package 4 notes><Requirements Diagram 1><Requirements Diagram 1 Notes><Requirements Diagram 1 Embedded Requirements><Requirements Diagram 1 Embedded Requirement Notes></package 4>
<package 5><package 5 notes></package 5>
</root package>

Below is the structure to what seems to be getting all of the content I want but it is displaying State Diagrams (appears to be considering "StateNodes" as "Requirement" elements) and Block Definition Diagrams twice.
---------------------------------------------------
package >
{Pkg.Name}
{Pkg.Notes}
{Template - Activity Diagram Template Fragment}
{Template - Requirement Diagram Template Fragment}
package element >
linked document >
< linked document
< package element
element >
< element
child packages >
< child packages
< package>
--------------------------------------------------------

The Activity Template Fragment has an Exclude Filter for
1) "Exclude details for" "Requirement"
2) "Exclude diagram type" SysML1.3::Requirement
Below is the structure of the Activity Template Fragment:
------------------------------------------------------
package >
diagram >
{Diagram.DiagramImg}
Figure 1: {Diagram.Name} Diagram (version {Diagram.Version})

{Diagram.Notes}
element >
< element
<diagram
element >
{Element.Name} - {Element.Notes}
< element

< package
-------------------------------------------------------

The Requirement Template Fragment has an Exclude Filter for
1) "Exclude details for" eveything except "Requirement"
2) "Exclude diagram type" everything except "SysML1.3::Requirement"
Below is the structure of the Requirement Template Fragment:
------------------------------------------------------
package >
diagram >
{Diagram.DiagramImg}
Figure 1: {Diagram.Name} Diagram (version {Diagram.Version})

{Diagram.Notes}
element >
< element
<diagram
element >
(Table Header)
(Table Row){Element.Name} - {Element.Notes}
< element

< package
----------------------------------------

 I have tried following the example to make a Template Selector but I am getting lost in the Section loops and am missing content that I can get to display with the previous templates... Why do these Sections need to be this convoluted?

Attempt 1)
----------------------------
package >
{Pkg.Name}
{Pkg.Notes}
{Template - Template Selector} <------ Putting here does not get any of the embedded content, only displays package name and package notes.
package element >
linked document >
< linked document
< package element
element >
< element
child packages >
< child packages
< package>
--------------------------------------------------------

Attempt 2)
----------------------------
package >
{Pkg.Name}
{Pkg.Notes}
package element >
linked document >
< linked document
< package element
element >
{Template - Template Selector} <------ Putting here gets some of the content I want but not all of it like the non-template selector did.
< element
child packages >
< child packages
< package>
--------------------------------------------------------

Attempt 3)
----------------------------
package >
{Pkg.Name}
{Pkg.Notes}
package element >
linked document >
< linked document
< package element
diagram >
{Diagram.DiagramImg}
Figure 1: {Diagram.Name} Diagram (version {Diagram.Version})

{Diagram.Notes}
element >
< element
< diagram
element >
{Template - Template Selector} <------ Putting here gets some of the content I want but not all of it like the non-template selector did. It is missing the embedded elements for Activity Diagrams, it misses all states in a State Diagram except for the two StateNodes (initial and final), it misses all blocks except for embedded ports on a block. Also all tables now show up with a table header in each table row.
< element
child packages >
< child packages
< package>
--------------------------------------------------------

Attempt 4)
----------------------------
package >
{Pkg.Name}
{Pkg.Notes}
package element >
linked document >
< linked document
< package element
diagram >
{Diagram.DiagramImg}
Figure 1: {Diagram.Name} Diagram (version {Diagram.Version})

{Diagram.Notes}
element >
{Template - Template Selector} <---- Same results as Attempt 3
< element
< diagram
element >
{Template - Template Selector} <---- Same results as Attempt 3
< element
child packages >
< child packages
< package>
--------------------------------------------------------

Attempt 5)
----------------------------
package >
{Pkg.Name}
{Pkg.Notes}
package element >
linked document >
< linked document
< package element
diagram >
{Diagram.DiagramImg}
Figure 1: {Diagram.Name} Diagram (version {Diagram.Version})

{Diagram.Notes}
element >
{Template - Template Selector} <---- Same results as Attempt 3
< element
< diagram
element >
{Template - Template Selector} <---- Same results as Attempt 3
< element
embedded elements >
{Template - Template Selector} <---- Same results as Attempt 3
< embedded elements
child packages >
< child packages
< package>
--------------------------------------------------------

The Template Selector Fragment has the following Custom Query text:
1) Requirement::Requirement Template Testing
2) Requirement: Customer : Requirement Template Template Testing
3) default::Element Template Testing

Below is the structure of the Template Selector Fragment:
-------------------------------------------------------
custom >
< custom
--------------------------------------------------------

The Requirement Template Testing Fragment doesn't have an Exclude Filter

Below is the structure of the Template Testing Fragment:
------------------------------------------------------
package >
diagram >
element >
< element
<diagram
element >
(Table Header)
(Table Row){Element.Name} - {Element.Notes}
child elements >
< child elements
< element
child packages >
< child packages

< package
-------------------------------------------------------

The Element Template Testing Fragment  doesn't have an Exclude Filter
(I have tried multiple arrangements of the the Element Tags but nothing seems to get the same content as the previous templates do)

Below is the structure of the Element Template Testing Fragment:
------------------------------------------------------
package >
diagram >
element >
< element
<diagram
element >
{Element.Name} - {Element.Notes}
child elements >
< child elements
< element
child packages >
< child packages

< package
----------------------------------------

[PeterHeintz]

Hi Stephen,
it is not uncommon that the template stuff make users crazy in case of non-primitive templates.

For me it seems that you want to treat each package more or less individually.
If you really want to treat those packages individually you should stereotype your packages and your template selector should fire on the package stereotypes rather than on stereotyped requirements.
If you do not have the need to filter out diagrams e.g. because your package 1 has no diagrams at all and e.g. package 2 has only behavioral diagrams and so on, your template selector should fire on the elements having the embedded diagrams (e.g. Activity, Requirement, ...).

In the first case you should call the selector on package level and in the second one on element level.

[Geert Bellekens]

I found that using virtual documents is a great help in keeping my sanity.
Use only small templates and if needed create a model document (or even more then one) for each element that needs to be documented.

If the virtual document becomes too complex to create manually, use a script to create it.

Trying to put everything into a single template is almost impossible. I decided to leave that road a long time ago, and I've been much happier since.

Geert

[Stephen Kropp]

Thank you both for the replies!

Peter, I don't necessarily want to treat each package as a stereotype because anything could be in the package despite my example. Many of my diagrams have requirements that justify whatever is in the diagram but maybe that wouldn't cause a problem with stereotyping the folder.

Geert, I am intrigued by the virtual document concept but I find that whenever I start down the path of complexity, it often fails me right before a meeting. I do anticipate trying your example (and another I found on the sparxsystems website) but I am trying to hit my breaking point with these templates before I start down that path. What I am currently doing is very basic and shouldn't require anything fancy.

After working on this issue most of the day I think I've got something that works how I want but here are some questions:

1) What is the "Package > Element > Diagram"? Is this the diagram(s) that contain the element within the package?
2) What is the "Package > Element > Child Elements"?  Is this an element placed within (not embedded) another element that resides within the package?

Some setbacks I've discovered:
1) Exclude Filters and other filtering options (e.g. Hide Note-less elements) don't seem to work on Template Selector Sub-Templates.
2) There is apparently a bug with the Template Selector not displaying table header rows aggregated correctly, or maybe this is by design? (http://sparxsystems.com/forums/smf/index.php/topic,25835.msg233596.html#msg233596) Is there any way I can work around this, I can't believe I've made it full circle back to this problem again!

Thanks again!

Steve

[Geert Bellekens]

Hi Steve,

1) Are the diagram(s) owned by an element in the package (you have to click the element open in the project browser in order to see the diagram
2) Are the elements owned by an element in the package (same level as the diagram), except that child elements will recursively repeat your Element> section for each sub-sub-sub element in finds, often decreasing the header level.

I've noticed that the filters are indeed sometimes not working correctly.  Definitely not when trying to show only a sub-element of a specific type. The flag "show child elements even if parent is filtered out" doesn't always seem to work as it is supposed to.

I find that using virtual documents is in fact decreases the level of complexity because I can make very simple small templates for a very small part of the document. All those little parts after each other then make up the big document.

Geert

[bockfu]

I'm with Geert.  This is a bit simplified, but unless an existing template suits your needs AND all packages are under a single parent package, use virtual documents.

It is another level of abstraction you have to manage, but you can baby step the transition.  For example, start with one master document with one model document.  Apply the current template you are using.  Then make incremental changes as needed.  Using the MVC pattern as an analogy, create more model documents, breaking apart the single package (as a model in MVC) into different packages (models in MVC) and apply different templates (views in MVC).

Disclaimer:  as you know, EA quirks come along for the ride.

[Stephen Kropp]

Ok, you convinced me to try virtual documents but I think I am running into the need that Geert pointed out, that if the virtual documents become too complicated then I need to script its creation.

Here is my situation:

• Nearly half of the report can be displayed using a very simple template that gets the package name and package notes.
• Within the packages I have shallow-copied the model diagrams that I want to include within the report section.
• The diagrams within the packages then report on their elements contained within the diagram. I would prefer to remove these copied diagrams and report directly from the master diagram but I have changed some diagram options to declutter the diagram for my stakeholders... this is a trade-off because I have to copy and apply those declutter changes each time something drastically changes in the diagram. Maybe there is a way to script these diagram options being applied?
• I have noticed that a lot of the virtual document examples rely on the stereotype being populated for each element, so far I have not utilized the stereotype field because I haven't needed to filter my elements to that level of granularity (beyond knowing the type of element).

Here is what I think I need to do:

• Create a template for displaying the simple package name and package note for all packages but exclude any packages that contain diagrams. (I don't want to manually create this list via the drag-and-drop method of virtual documents because I am constantly moving things after each peer review so I'd like an exclude filter for this. Can anyone help me create an exclude filter or SQL statement that would achieve this?)
• Create a template for displaying each diagram (some diagrams will use the same template while others I would like to display in a certain order and group some of the elements together).
• Order the model documents. I am not sure how to do this since I don't want the report structure to be dependent on the model document order (e.g. Packages, Use Cases, Block Diagrams, etc.). It feels like I might need to continue using the Template Selector if I want to traverse down the package structure and apply the appropriate model template when a corresponding model element (diagram) is found within a package... or script the creation of the virtual documents that would achieve this?

[Stephen Kropp]

I decided to just move ahead and create a model document the manual way so my model document structure looks something like this (Folders, Block Diagram, Use Case, Requirements, Folders, Requirements, Folders, Requirements, State Mode, Activity Diagrams, Requirements, Folders, Block Diagram, Folders, etc.) so I'm basically telling EA to process the report in the order and template specified by the model documents... it doesn't seem efficient to do it this way but I'm sure a script would help and I won't need to completely rely on the Template Selector and worry about it messing up my tables.

The good news is that it works, but as bockfu pointed out, there are EA problems all along the way.

Some things I've noticed so far:

• I had to remove the Child Packages option in my templates so it only processes the folders that I pass to it via the Model Documents.
  This had a side effect of making by Table of Contents display everything at the same level rather than showing sub-folders in a different font via the style sheet. I will need to fix this at some point but any help on what I need to do would be helpful.
  
  
• I had to convert my Template Fragments into Templates.
  This was a pain because I had created almost everything I wanted as a Template Fragment before but when I was forced to change because the Virtual Templates only accept a Template, I then started grouping all of the virtual document templates via the Template Group field but this doesn't show up in the drop-down when applying the template to the model document.
  
  
• I had to re-verify everything was included in the report, which I didn't have to worry about with the other documentation generation method but do it once and (in theory) everything should be ok after that .
  
  
• I also have a problem with my Master Template in that it doesn't get applied like it did before the virtual documents change.
  My Master Template Includes a Cover Page, Table of Contents, and I have a "End of Document" line of text that is added to the bottom of the last page. Before the virtual document change everything would show up correctly and the last line of text was on the last page of the report, now the "End of Document" text shows up as the last line of text after the Table of Contents. Any ideas on how I can get this to work again?
  
  

[bockfu]

For item 2, I've had to reload the EA project to get the UI synced up with some template name and grouping changes made. 

The disclaimer was more about buggy behavior I've observed.  In some cases it may not be a bug, but as a user it has been poor user experience.  But this is a EA template thing and not unique to virtual documents.