Frustrated with Document Templating (help)?

[speedco]

Hi all,

Can anyone help me? I'm a contractor working for my client that have Sparx EA. I've been helping them automate their documentation through the use of good structures and packages in the tool. I can technically understand how to get the results required, however, I keep tripping over some REALLY annoying issues. Can anyone help me determine best approach?

I've tried multiple solutions, the first being a package of packages, including diagrams/rtf's that are compiled into a document through a Template. Secondly, I've created a Virtual Document (Report Master -> Model Document) structure and also have it generating the documents.

What is my problem?

My client are using the tool with a common shared repository, across multiple business units. Each unit has different needs with cover pages. Why can't the cover page use Tags/Properties of the package? I appreciate there are Report Constants, which are a fixed list, i.e. I need additional ones OR project constants. Project constants don't seem to make any sense to me as they are set by the user and stored in their profile. I appreciate it is possible to export and import, but my client need them pinned to the package that contains the document.

Is there any other option to me?

The above problem becomes more painful when I tried to factor in 'Table of Contents'. I'm trying to use a Cover that picks up tags/details from the top level package because the ONLY WAY I can include a ToC is via the additional template on the Generate Document page. No matter which way I create a template, the 'Insert Table of Contents' is ALWAYS greyed out. Should I be able to add a table of contents to a template or fragment? If so, is there a setting or a step I need to follow to do so?

If I could get a ToC into a template, I would prefer to create a Virtual Document that includes a Cover, ToC and then body fragments that would produce a Single document from a top level document package. IS this possible?

Any advice or help would be appreciated as I've read, searched and watched lots of youtube videos. There have been occasions when it looks possible, but I can't get it to work. Incidentally, we are on EA13.

Kind regards

Speedco

[PeterHeintz]

Hi,
here is some information about your two main questions.
You are right, cover pages unfortunately cannot use tagged values coming from a package that the template is used for.

I miss that feature as well, I already did several feature request and I am pretty sure implementing this, is a easy thing, but it is just not there and I have no idea if it ever comes. So you have to do it somehow else (scripting, several cover pages,…) with all its disadvantages.

I am not sure if I understand your second issue right, but for the TOC you do not need to define a separate TOC template, you can put the TOC in any template that you might uses for other things as well. To do that, just add e.g. the string “Table of Contents” at the right place in your template and assign the font style TOC1 to it.

[Geert Bellekens]

I don't think I understand your problem. The cover page has quite a large number of fields available
- name, title, alias, version, status, author, ...
all these fields are coming directly from the tagged values on the virtual document package (master document)
So when creating a new virtual document you just need to make sure to fill in those tagged values with the appropriate values from your source content.
Also when generating a document you can choose for a separate TOC template. There are two standard ones (landscape and portrait) which in most cases where good enough for me.

So in the end if you use virtual documents you have to press F8, select the appropriate cover page and TOC, and generate, and everything comes together in one document.

This has been working quite well for me for many different clients with very complex requirements.

I've documented my approach in this article

Geert

[PeterHeintz]

Hi Geert,
Regarding to you comments about "large number of fields", what is there is just not large enough.

To comply with our company documentation standard we would have to add e.g. things like:
Project Number
Project Part Number
System Level
Customer
Verifier
Validator
…
to the cover page.

These things are related to a package and could be added to package tags, but package tags cannot be used on cover page level.

[speedco]

Thanks Peter,

I've tried putting the 'TOC1' and 'TOC Heading' font styles, but no joy. Further to this, Under Document/Edit->Insert->Table of Contents, this is ALWAYS greyed out. I'm beginning to wonder if there is a configuration/installation problem with this.

Thanks Geert,

I've not come across your article, so will read it. I've already created a Virtual Document structure and the Master Document has a set of Report tags, such as ReportAlias, ReportAuthor, ReportName, ReportStatus, ReportTitle and ReportVersion. However, our cover needs to also have a 'Division' and 'Department' set of values, that are specific to this master document.

With the Virtual Document structure and assigning Fragments, all works here, I see Beautiful documents with our stylesheet. However, this is where I can't find a way to insert a ToC. I can, if I select a Cover and ToC from the Generate Document option, but, as stated earlier, I can't define all the parameters I need in cover. I "could" just code them into the Cover, however, we'd then need a cover for each different department/division (maybe that's the answer). This therefore then leads me to create a cover in the Virtual Document structure, but I then fall foul of NOT being able to create ToC fragment.

I had planned to create a toolbox with example diagram/structure, including the 'Virtual Document' structure, allowing for Architects to create a new Document type for their division; with them only having to change the tag inside the Master package.

I might not be explaining what I'm trying to do well enough and I'm probably NOT THINKING in the way the tool requires me to implement it. Thus, I REALLY APPRECIATE any of your advice/tips.

Kind regards

Carl

[Geert Bellekens]

I understand.
It seems like a very reasonable feature request to allow all tagged values on the master package to be used on the cover page. That would give everyone the flexibility they need to create cover pages according to the company standards.

For now I'm afraid the only option is to create cover pages for each department, or else combine some of the info into something like the alias.
e.g. that could contain: Project: MyProject Project Number: 123 Department: Accounting
Or last resort, have the users fill that in manually after generating the document.
In most cases there will always be some post-processing needed in Word after the document has been generated, so adding those fields manually shouldn't be too much of an issue.

Geert

[speedco]

Thanks Geert,

That really would be a good solution, but for now, leaving the fields in the Cover Page as values to change is probably the best solution all round for my client. They'd only have to change the front page in my scenario.

I still, for the life of me, can't get a Table of Contents to pop-out of a simple Template. IS it possible that our configuration/installation is bad? I can't add via the insert ToC option, nor does setting the Font type to TOC Heading or TOC1 as suggested. Any thoughts for this?

Kind regards

Carl

[Geert Bellekens]

TOC templates are a special kind of templates.
The easiest to create a new one is to copy one of the standard ones and start from there.

We have also updated all the TOC styles in our stylesheet, and that worked fine as well.

Geert

[PeterHeintz]

To be honest, it’s some years ago that I defined my template having the TOC inside. And for new things I do copy and paste.

But looking on that, I assume to understand what “speedco” means.
When having a template and using the Edit Ribbon you can choose insert and within that menu there is the Item “Table of Contents” and this seem to be always greyed out (at least it is greyed out when it should not).
Maybe a bug!?

[speedco]

I've tried pretty much everything with ToC. I appreciate the ToC template is a special entity, which I can copy/extend and call by supplying it as one of the options in the generate document options (alongside cover).

However, I really wanted to incorporate a ToC into a virtual document template. Peter eluded above that is is possible, but no matter what I do, nothing works (i.e. setting the font type and I can't insert Table of Contents as it is greyed out)! I therefore assume this isn't possible in EA13; clearly ToC can only be generated by using the Generate Document option.

Kind regards

Carl

[speedco]

In fact, thinking about this logically. What is the point of the Ribbon insert Table of Contents if it is ALWAYS greyed out?? Doesn't have a purpose as I can NEVER unlock it. This does sound like a bug to me.

[speedco]

This:

https://postimg.org/image/4kyeckq7t/

[Geert Bellekens]

You can actually copy/paste the "Table of contents" part from a TOC template into another template and it will effectively add a TOC to that template.

Geert

[speedco]

Geert, you are a genius! I don't get why this works, but it does! Given the ribbon insert is greyed out and trying to manually set the Table Heading font type fails to, but simply cut and paste from a templated ToC does; smacks of a bug somewhere to me. HOWEVER, I DONT CARE

Thank you ever so much.

Kind regards

Carl

[Geert Bellekens]

In time you learn to expect this type of "weirdness" from EA 

Geert