This tutorial explains how give your audit trail a personal (or: professional) touch by styling the document.
We are starting on the premise that you already read though Parts 1 and 2 of this tutorial, so you know how to add audit trails and tweak their settings.
What will you be learning in this tutorial
- control the output of radio groups and check lists
- tweak the width of grid tables and their columns in ODT
- create your own look-and-feel (or ask our team to do it for you)
- add MarkDown images (which may differ from those used in your live model)
- understand the policy for heading levels, and optionally revert to a legacy mode
- include the visualisations provided by our grids-to-graphs plugin
NOTE This part of the tutorial is still way incomplete. There is also to the GXSL API Reference.
Radio groups and check lists
By default only the chosen option in a radio group is shown.
You may also opt-in to showing all the available options; this is done by setting the variable
gxsl.vars.single_radio to the value
For check lists however the default is to show all the available options. You can opt-out of this (and show only the checked ones) by settings the variable
gxsl.vars.just_chosen_checkboxes to the value
1 (one). NOTE this does not affect single checkboxes, just the ones appearing within lists.
This section is relevant to odt->pdf output only.
Rendering tables in HTML is superior to that of Open Document and we have not found a need for tweaking that.
If all columns of a Question of type Grid are set to 100 pixels, the width of a table is divided equally over all columns.
This often results in a less-than-ideal layout. Therefore, authors may indicate to want to use fixed width columns in their grids or tables.
They can do so by specifying for at least one of the columns a width that is not 100 pixels, thereby deviating from the default.
Depending on things like font size, the specific width may be inappropriate in the ODT output. When using fixed widths, you may scale the actual table and column width by the factor set in the variable
Depending on things like font size, the width of the table may exceed that of the page. The variable
gxsl.tables.max_width sets a max width in inches.
Look and feel
Change the look and feel to match your brand guidelines by following the following steps.
In the HTML output, a minimalistic default stylesheet is used.
To use your own stylesheet, set the variable
gxsl.vars.stylesheet to the appriopriate URL.
The stylesheet loaded with
gxsl.vars.stylesheet does not replace the default one. To also remove the default one, set the variable
gxsl.vars.stylesheet_default to the value
In the ODT->PDF output the following layout options may be controlled by an OpenDocument template whose name is referenced with the variable
- background images
- page margins
- headers and footers
- fonts (when installed on the server)
- font size, style and color
The two-column layout for questions and answers cannot be changed.
One can also set a server-wide default template with the
PDF Creator Parameters(see PDF Creators).
The process to go about changing the styles still involves the cooperation of the team at Berkeley Bridge, but to get a rough idea, this is what they do:
- generate a PDF based on the default template;
- get the ODT that is output as part of the process of generating the PDF;
- open it in LibreOffice;
- change styles using the styles dialogue;
- sometimes: manual purging of unused images;
- saving this file, unzipping it, and registering it as a new template, to be selected with
- testing it for correctness and performance; and
- installing it on the appropriate server.
Installation on the server may require a reboot if new fonts are used because of the way the font cache of the OS and LibreOffice work.
The following templates have already been developed, more may follow:
- rijksoverheid (Dutch central government template)
- rood (unbranded, reddish, template)
- snelbalie (unbranded, blueish, template)
If you use MarkDown inline images in your texts and they are referenced as absolute URLs (i.e. they start with
https://), they will be included provided that the URL is accessible from the server, and provided that
gxsl.vars.markdown is set to
1 (see MarkDown setting).
If you provide relative links (such as
/web-folder/my-image.png or simply the ‘sibling’
my-image.npg), this is still OK with HTML: what works for you in a model on the web will also work in the audit trail on the web.
But when creating a PDF or an OpenDocument document, things are more complicated: the document will look at a local filesystem, not the internet, so relative links point to a different file, and will not be found.
This problem is easily solved by providing a base URI from which the relative images need to be resolved.
This base URI is set with the variable
If you do not supply a base URI, the image will not be inserted.
For safety reasons, if you supply a fake base URI (a non-absolute one), this will also be discarded and the image will not be inserted.
Why use relative images anyway?
So why use relative images in the first place, you may wonder. There are multiple reasons to do so:
For one, the absolute URI will depend on whether you are using a production, test or development server.
The other one is that in your model you may use partially transparent pictures. Partially transparent images are forbidden in the version of PDF/UA supported by LibreOffice. Therefore you need to supply a non-transparent version of your image for use in the document.
Besides transparency, there may be other concerns warranting different versions of images (art direction).
All ‘font-style headings’ (see below for an explanation) are rendered according to their so-called ‘intended level’, but demoted with 1, in order to be lower than the document title, with a max of 6. Anything that would be lower remains at 6. This is in line with what is done in newer presentation layers on the web, where all headings are demoted according to the context of the rest of the web page, in order to always get a proper (web) document hierarchy.
So, in your audit trail:
- Standard title becomes heading level 2
- Heading 1 becomes heading level 2
- Heading 2 becomes heading level 3
- Heading 3 becomes heading level 4
- Heading 4 becomes heading level 5
- Heading 5 becomes heading level 6
- Heading 6 becomes heading level 6
- Heading 7 becomes heading level 6
MarkDown headings are demoted the same way when occurring inside a ‘node context’, that is, when the MarkDown appears inside screen text.
When occurring outside of a ‘node context’ — such as in front matter or closing words, MarkDown headings are not demoted.
Setting the variable
gxsl.titles.policy to ‘legacy’ allows authors to
revert to the old, blunt, rendering, which was as follows:
- all ‘font-style headings’ (see below) on-screen were rendered as level 3 headings.
- MarkDown was not demoted anywhere.
With the term ‘font-style headings’ we understand headings that are headings because they use one of the following styles defined in the Studio:
Any other style starting with ‘Heading’:
The first digit in the range 1 through 6 from the left is used as the initial level. If there is no such digit in the style name, we default to ‘1’.
This means ‘Heading 2 type 3’ gets initial level 3, and then is demoted to level 4. And ‘Heading 458’ gets initial level 4, demoted to 5. Note that ‘Heading 7’ will get initial level 1, since 7 is not within the valid range, and therefore discarded.
And ‘Heading 74’? Well, 4 of course.
Note that the ‘shoehorning’ to level 6 will cause an initially deep hierarchy to flatten out from level 5 onwards for documents, and from perhaps higher levels (4 or even 3) on the web. For this reason we advise not to use levels 4 through 6 in your model, but to stick to Heading 1, Heading 2 and Heading 3 and the equivalent mark-up in MarkDown:
# Heading 1,
## Heading 2,
### Heading 3). This warning of course does not apply to
gxsl.vars.closing_wordswhere demotion never takes place.