Tweaking the content

This part of the audit trail tutorial explains how to fine-tune or tweak the contents of such an audit trail. Part 3 will teach you how to create your own design.

We are starting on the premise that you already have the audit trail set up as explained in Part 1 of this tutorial.

Tweak the audit trail

The output of the audit trail may be fine-tuned. To give you an idea, the following is possible (roughly categorized from easy to advanced):

  1. set the document title (this differs from the filename)
  2. set the creator field
  3. exclude questions, texts (>= 4.5), nodes and entire graphs
  4. opt-in to MarkDown
  5. adding text before or after the audit trail itself
  6. re-order nodes
  7. (>= 4.5) opt-in include the ‘current node’
  8. set the language and the number format for representation of numbers
  9. add link destination URLs when they differ from the link text

And (explained in Part 3):

  1. control the output of radio options
  2. tweak the width of grids (tables)
  3. create your own look-and-feel (or ask our team to do it for you)
  4. add MarkDown images (which may differ from those used in your live model)
  5. include the visualisations provided by our grids-to-graphs plugin

So, how does one go about tweaking the audit trail? Well, basically you provide your own tweaks as formulas in a special graph called gxsl, which needs to be called before generating an audit trail.

Getting started

Before reading any further, please download our sample model and copy the gxsl graph to your own model to get started.

Once you open the downloaded model, you will see that the graph gxsl contains multiple nodes. This is done to group the ever-growing options, making it easier to find things.

  • exclude: excludes stuff
  • include: includes stuff
  • tables: settings for tables
  • titles: settings for titles
  • vars: the rest of the options; in hindsight, this one should have been split up (markdown, looknfeel, include, the rest…)

Inside these nodes, you will see fx formula actions; these formulas define your specific tweaks.

The documentation below may tell you to set 'variable gxsl.something.something_else’ to the value 1.

This means you have to find the fx something_else formula in the node something that can be found in the graph called gxsl, and change its value field to 1.

With the library all ’gxsl variables’ are mapped to the node libgraph_gxsl (Cf. Libraries):

node__variable maps to gxsl.node.variable.

So if the documentation tells you to set 'variable gxsl.something.something_else’ to the value 1, you have to navigate to your node called libraph_gxsl, and change the value of the formula called something__something_else.

Calling the gxsl graph multiple times

At any time the audit trail is generated, it will look for the last occurrence of the formulas in the gxsl graph. This means you can change the gxsl settings as models progress and output multiple variations of the audit trail by calling the gxsl graph again but providing different settings.

Use cases for calling the gxsl graph multiple times:

  1. It may be that at the start of a case some settings are yet unknown (such as document language).
  2. Or you may want to output quite different documents.

Set document title

Set the variable gxsl.vars.title to your preferred document title.

It will be used for two things:

  1. the level 1 heading at the top of your document, and
  2. the meta information in the document specifying the title (e.g. the HTML <title> tag inside the <head> section). In ODT->PDF, this value can also be used in headers and footers.

If you fail to set this field, the model description (pretty model name) is used instead.

Set the creator field

Set the variable gxsl.vars.creator to whatever you wish.

This one is only used for meta data information.

One can also set a server-wide creator with the -c argument in PDF Creator Parameters (see PDF Creators).

Exclude part of the trail

The audit trail already categorically exludes remarks and links from the output, but more fine-grained control is possible here.

If you do want remarks to show up, create and use a font style that does not use the word “remark” in it anywhere.

The gxsl.exclude node contains instructions to exclude questions, texts, links, nodes and entire graphs from the audit trail. The formulas used for this purpose are named after what type of thing they exclude. So we have:

  • gxsl.exclude.questions
  • gxsl.exclude.texts (>= 4.5)
  • gxsl.exclude.links (>= 4.5)
  • gxsl.exclude.nodes
  • gxsl.exclude.graphs

These formulas need all be newline ('\n') separated list of things to be excluded. So if you want to exclude the graphs “main” and “irrelevant”, you give gxsl.exclude.graphs the value 'main\nirrelevant'.

A note on links: as said, these are excluded categorically from the audit trail. This was actually an earlier oversight. So as not to introduce backwards incompatibilty, inclusion of links is now governed by an opt-in. Set gxsl.include.links to 1, and any normal links will show up in the audit trail. Once this switch is turned on, you may exclude individual links with gxsl.exclude.links. Links to generated documents or (other) relative links will not be rendered, even with the switch turned on. This is because, when taken out of context, relative or session-specific links will not work.

The test for ‘normal links’ is this: does it either include a protocol (tests for ://, so https:// and friends work), or is it an email link (mailto:someone@example.com).

MarkDown

If you are already using MarkDown in your model and it is turned on in your presentation layer, chances are you will want it in your Audit Trail too.

We have implemented a subset of MarkDown for use in the Audit Trail.

Do use this subset, set the variable gxsl.vars.markdown to the value 1.

Not in our subset

The subset includes most things you’d expect, but currently excludes the following:

  • blockquotes;
  • code blocks (fenced or without fences);
  • ordered lists (rendered as unordered ones);
  • reference-style images and links (inline ones are OK).

Add texts before or after the audit trail

Adding texts before or after the actual audit trail is done by adding text fragments called (literally) gxsl.vars.front_matter and gxsl.vars.closing_words.

It is advised to output these two text fragments only inside the node gxsl.vars.

Before 4.5, all text fragments with the same graph iteration number will be lumped together. From version 4.5 onwards, it does not really matter where in the model you output a gxsl text fragment; The last text fragment along with its namesakes in the same node will be used. That being said, it is still considered good practice to only output this fragment in the node gxsl.vars: It keeps your things together.

Markdown may be used in these text fragments if gxsl.vars.markdown is set to 1.

It may be good to note that ^{variables} in text fragments are resolved (replaced) the moment text fragments are declared. This means you should take care not to declare a text fragment ahead of time, i.e. before the referenced formulas, texts, or questions have run. This is — admittedly — a limitation that the standard document assembly templating does not have.

Debugging: I have the text fragments but they do not show up!

This may happen when you have a variable defined with the same name as you intended to use as a the text fragment identifier (e.g. gxsl.vars.front_matter): since the Studio is very smart, it then replaces the identifier with the contents of that variable.

Solution: remove the variable in question.

In all honesty, you may also use formulas instead of text fragments, and in fact, this is how these tweaks were first developed - which is why, in earlier versions of the sample model and library, these variables were present and messing with our text fragment. It is advised to use a text fragment here (and not a formula), for the sheer reason that this is currently the easiest way to output multiline text and intersperse variables in the Berkeley Studio. Please do not use both a text fragment and a variable at the same time.

Front matter: gxsl.vars.front_matter

Front matter, such as an introductory text, that we do not want in the interactive model. The front matter will be inserted after the title, but before the questions and answers.

Closing words: gxsl.vars.closing_words

Closing words, such as a disclaimer, that we do not want in the interactive model. It will be inserted after all other questions.

Re-ordering nodes

It is often the case that you want a node placed further on in the model — such as a conclusion node — at the very beginning of your output document. Or the other way around.

Re-ordering nodes is possible with the variable gxsl.vars.order_by: the value you give to this variable can be used as a variable name in individual nodes that you want re-ordered. The value you in return give to that variable (which must be a whole number) is used to order the individual nodes amongst each other.

For example, if you set the variable gxsl.vars.order_by to the value 'order_in_doc_a', and the variable main.conclusion.order_in_doc_a to the value -1, the node main.conclusion will be output before all other nodes in the model. Likewise, if you set main.signature.order_in_doc_a to 1, it will be output after all other nodes (defaulting to order 0 — which signifies the middle). Other whole numbers are possible too, of course, opening the gate to a massive shuffle.

Current node

To include the current node (the step the user is at when a text is generated), set the variable gxsl.include.currentgroup to 1.

This feature has been made available in version 4.5 of the Berkeley Web Server.

Language

The Audit Trail will use the language as it is set for the model.

It is possible to override this setting on a per-document basis by assigning the appropriate code to gxsl.vars.lang.

One can also set a server-wide default language with the -l argument in PDF Creator Parameters (see PDF Creators).

Number format

There are currently two types of number formats implemented for use in the the Audit Trail, defaulting to ‘european’, unless the language is set to ‘en-us’, in which case the ‘us’ format will be used:

  • ‘european’: period as radix point, comma as thousands (grouping) separator
  • ‘us’: comma as radix point, period as thousands (grouping) separator

If your use case needs a different style, or different grouping, let us know!

The variable to assign these values to is gxsl.vars.decimal_format.

Links become inaccessible when printed if the link text differs from the link destination.

The Audit Trail will show the link destination after the link text if you set the variable gxsl.urls.show to the value 1. This setting is smart in that it will not add the destination url if the link text and link destination are actually the same.

The format of that text depends on two variables:

  1. gxsl.urls.before — defaulting to ' (' (including the space).

    If you want to insert nothing before the URL, use 0 (zero).

  2. gxsl.urls.after — defaulting to ')'.

    If you want to insert nothing after the URL, use 0 (zero).