Design

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

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 icon 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 0 (zero).

For check list icon 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.

Fixed-width tables

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 gxsl.tables.factor.

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.

HTML

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 0.

OpenDocument (ODT)

In the ODT->PDF output the following layout options may be controlled by an OpenDocument template whose name is referenced with the variable gxsl.vars.template

  • 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 -t argument in 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 gxsl.vars.template;
  • 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)

MarkDown images

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 gxsl.vars.markdown_baseuri.

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).

Heading policy

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.

Legacy

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.

Font-style headings

With the term ‘font-style headings’ we understand headings that are headings because they use one of the following styles defined in the Studio:

  • Standard title

  • Heading 1

  • Heading 2

  • Heading 3

  • Heading 4

  • Heading 5

  • Heading 6

  • 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.front_matter and gxsl.vars.closing_words where demotion never takes place.