Sparx Systems Forum

Enterprise Architect => General Board => Topic started by: JoelL on August 31, 2018, 01:01:10 am

Title: Documentation with elements and attributes from diagram
Post by: JoelL on August 31, 2018, 01:01:10 am

Hello,

I'm using version 14.0 and I want to generate a document that takes the elements from a certain diagram along with the attributes of thoes elements with the end result looking something like this:

Element name X

Attribute name   Attribute value Name x              Value y Name z              Value n

Element name Y

Attribute name   Attribute value Name x              Value y Name z              Value n

From what I can see the template builder only lets me choose element attributes from elements that are located in the same package as the diagram.
I've tried using the element tag under Diagram but that don't seem to work as it always comes up blank, and even if it did work it would only give me the name of the element, not its attributes.

It's not an option to move all elements into the same package.

Do anyone have a solution for this?

Thanks! /Joel

Title: Re: Documentation with elements and attributes from diagram
Post by: matthew.james on August 31, 2018, 09:06:49 am

I have a similar need - to create diagram / view based (rich text) documents that pull element details from wherever the elements are, i.e. a document based on a diagram and the elements on that diagram *not* based on a package.  I can't find any examples of that but I'm sure there must be a way.

Taking it further, into the HTML publishing, I'd like to achieve the following:
- Choose a front 'navigation' page, e.g. using NavigationCell elements
- Publish to HTML with that page as the landing page
- Recursively include all diagrams linked to from that page (and any linked to those diagrams etc)
- Recursively include details of all elements referenced on those diagrams
- Irrespective of what packages any of the diagrams and elements may be in (obviously within the same model)

This would seem to be a fairly common requirement so again I'm sure there must be a way to achieve this.  However everything I can find seems to be package based.
Any hints or advice appreciated

Title: Re: Documentation with elements and attributes from diagram
Post by: Geert Bellekens on August 31, 2018, 04:22:51 pm

@Matthew Maybe you should start a new topic instead of hijacking this one.

@JoelL You are right. Starting from a diagram there are only limited options with regards to documenting the contents using regular RTF templates.

Workaround include:

- Use SQL fragments that select relevant info based on its appearance in the diagram (this only works well if you have a single diagram under a package or element as the PackageID or the ObjectID is the parameter you can use in the query.)

- Use virtual documents with model documents that document a single element each, creating a model document for each element shown on the diagram. To be practical you need to script the creation of the virtual document based on the diagram.

- Use a direct scripting solution using the document generator API.

I've use the first and second approach myself on a number of occasions.

Geert

Title: Re: Documentation with elements and attributes from diagram
Post by: michielper on August 31, 2018, 11:48:04 pm

Quote from: JoelL on August 31, 2018, 01:01:10 am

Hello,

I'm using version 14.0 and I want to generate a document that takes the elements from a certain diagram along with the attributes of thoes elements with the end result looking something like this:

Element name X

Attribute name   Attribute value Name x              Value y Name z              Value n

Element name Y

Attribute name   Attribute value Name x              Value y Name z              Value n

From what I can see the template builder only lets me choose element attributes from elements that are located in the same package as the diagram.
I've tried using the element tag under Diagram but that don't seem to work as it always comes up blank, and even if it did work it would only give me the name of the element, not its attributes.

It's not an option to move all elements into the same package.

Do anyone have a solution for this?

Thanks! /Joel

It is possible to include elements outside of the current package. E.g. with this template. This template only includes name and notes of the elements but you should be able to include any attributes. The trick is to have an empty element clause in the diagram section and a filled one in the packake section. Dont forget to check the box "Include all diagram elements in report" in the Generate Document dialog. And set any other options and filters.....

package >
{Package.Name}
diagram >
Elements in diagram {Diagram.Name}:
element >
< element
< diagram
child packages >
< child packages
element >
{Element.Name} ({Element.Type}) {Element.Notes}
child elements >
< child elements
< element
< package

Title: Re: Documentation with elements and attributes from diagram
Post by: JoelL on September 01, 2018, 12:27:58 am

Thanks so much for the answers!

@Geert Bellekens I love the SQL feature but I couldn't quite come up with a solution that looked good in the document and i'm not very good at scripting so that's is a bit out of my league.

@michielper That is excally what I was after! I'm still not quite sure about the logic behind it though, leaving Diagram> Element empty seems weird to me. But hey, as long as it works I can let that one slide for now.

Again, thanks so much for the help!

/Joel

Title: Re: Documentation with elements and attributes from diagram
Post by: michielper on September 03, 2018, 09:42:16 pm

Quote from: JoelL on September 01, 2018, 12:27:58 am

Thanks so much for the answers!

@Geert Bellekens I love the SQL feature but I couldn't quite come up with a solution that looked good in the document and i'm not very good at scripting so that's is a bit out of my league.

@michielper That is excally what I was after! I'm still not quite sure about the logic behind it though, leaving Diagram> Element empty seems weird to me. But hey, as long as it works I can let that one slide for now.

Again, thanks so much for the help!

/Joel

The empty element clause in the diagram section is a bit weird (and badly documented) indeed but it sort of indicates that you want the elements but postpone the details. Compare it to the declaration of only an interface in a programming language where the specification of the function is in another place. I do wonder why Geert did not give this example.

Title: Re: Documentation with elements and attributes from diagram
Post by: Geert Bellekens on September 03, 2018, 10:06:26 pm

Quote from: michielper on September 03, 2018, 09:42:16 pm

I do wonder why Geert did not give this example.

I didn't really think about it.  :-[
Very often I have no choice but to use SQL fragments for that kind of stuff because of complicated requirements.

Geert

Title: Re: Documentation with elements and attributes from diagram
Post by: matthew.james on September 04, 2018, 09:18:42 am

WRT to my 'hijack' request, the first part anyway ...

Quote from: matthew.james on August 31, 2018, 09:06:49 am

I have a similar need - to create diagram / view based (rich text) documents that pull element details from wherever the elements are, i.e. a document based on a diagram and the elements on that diagram *not* based on a package.  I can't find any examples of that but I'm sure there must be a way.

The advice above gives me part of what I'm looking for - I can now generate a document and include elements from outside the package the diagram is in (and with filtering I can control which of those I include) :-)

But, is there a way to limit the scope of the document to the currently selected diagram ?
If the diagram is in it's own package I get what I'm after, however if I move it into a shared package the document includes all diagrams within that package.

So, specifically, what controls the 'scope' field - the first field of the Generate Documentation dialog?
- If I choose a package that field name is Package and I can select any package I want; the document is generated based on the full package
- If I choose an element on a diagram or in the browser, that field name is Element and has the name of the currently selected Element; the document is generate on the element only
- If I choose a diagram (click on the diagram itself or select on the browser) then the selection changes to Package when choose Generate rich Text Document and does the whole package not just the diagram

Title: Re: Documentation with elements and attributes from diagram
Post by: michielper on September 07, 2018, 11:28:14 pm

Quote from: matthew.james on September 04, 2018, 09:18:42 am

WRT to my 'hijack' request, the first part anyway ...

Quote from: matthew.james on August 31, 2018, 09:06:49 am

I have a similar need - to create diagram / view based (rich text) documents that pull element details from wherever the elements are, i.e. a document based on a diagram and the elements on that diagram *not* based on a package.  I can't find any examples of that but I'm sure there must be a way.

The advice above gives me part of what I'm looking for - I can now generate a document and include elements from outside the package the diagram is in (and with filtering I can control which of those I include) :-)

But, is there a way to limit the scope of the document to the currently selected diagram ?
If the diagram is in it's own package I get what I'm after, however if I move it into a shared package the document includes all diagrams within that package.

So, specifically, what controls the 'scope' field - the first field of the Generate Documentation dialog?
- If I choose a package that field name is Package and I can select any package I want; the document is generated based on the full package
- If I choose an element on a diagram or in the browser, that field name is Element and has the name of the currently selected Element; the document is generate on the element only
- If I choose a diagram (click on the diagram itself or select on the browser) then the selection changes to Package when choose Generate rich Text Document and does the whole package not just the diagram

If you need to exclude a diagram from your reports, check the box "Exclude image from documentation" in the Diagram Properties.

Another way is to place diagrams that wil always be in- or excluded in a report together in their own package.
To create flexible reports, what you need is a "virtual document", this is created with Model documents and possibly Master documents to assemble multiple Model documents in one document. Begin wit a Model document and drag Packages into it. This gives you complete control over which packages to include in your report. The template to use is selected via a tag in the Model Document properties. When using Master documents, that have multiple Model documents, you can have a report using multiple templates by using a different template in each Model document.

The documentation options in EA are many and it takes some time and experimentation to use them comfortably but you can create large good looking reports with it.