Configuring the public user interface¶
Overview¶
The Cantabular software package includes a public user interface (UI) provided by the cantabular-ui
executable. It is designed to allow a member of the public to easily create their own query for data
supplied by cantabular-server.
There are a number of aspects of the UI that can be altered in order to customise it for a particular use case and to tie its visual appearance in with the rest of an organisation’s web presence. These are described below.
To ensure reliability and correctness, UI customisation should only performed by The Sensible Code Company. For more information on setting this up, please contact SCC.
When any aspect of the configuration or customisation of the user interface has been altered
the cantabular-ui process should be restarted for the changes to take effect.
Connecting to cantabular-metadata¶
The user interface executable can integrate with cantabular-metadata
in order to provide supplementary reference metadata to a user
and to enable additional functionality in the interface.
By default, however, it will not attempt to connect to cantabular-metadata.
The environment variable CANTABULAR_METADATA_URL
can be used to specify the URL of a running metadata service to connect to,
for example:
CANTABULAR_METADATA_URL=http://localhost:8493
When cantabular-metadata is not available at this URL,
this service will poll it regularly to detect when it becomes contactable.
When it is available it will continue to be polled
to detect any changes in the metadata content,
but by default at a lower frequency.
The polling frequencies for both up and down states can be customised using environment variables. See the command line help for this service for more information.
Standard tables in the user interface¶
As well as allowing users to build custom tables from data in cantabular-server,
cantabular-ui can also serve a searchable list of ready-made or standard tables.
Standard tables are pre-defined commonly requested queries that allow users to jump
straight to data without having to build a custom table from scratch.
These standard tables are defined via cantabular-metadata using its built-in Table
type. Each table must contain a reference to the Cantabular dataset it is for, the variables
it is built from and a name to identify it. For more information on and examples of the expected
format of these tables, please see the documentation for the metadata service.
When cantabular-ui loads tables from the metadata service, it will validate each of them
against data loaded into cantabular-server to ensure the query it is based on is valid.
Any invalid tables will be ignored and an explanatory error message will appear in the logs
for cantabular-ui.
Localization¶
All the content displayed in cantabular-ui can be translated into multiple languages,
with the exception of messages shown when an unexpected error has occurred.
Static text in the user interface can be translated via CSV files that define internationalisation messages for a set of available keys.
This same mechanism can also be used for overriding the default English language text in the UI in order to customise its content.
Dynamic text such as variable and category labels, and other reference metadata, can be localized
by supplying translations via cantabular-metadata. For more information please see the
documentation for the metadata service.
Custom templates¶
Specific parts of the user interface can have additional content inserted into them using custom templates. This allows user-defined metadata to be incorporated into UI pages and allows page furniture—such as navigation elements or footers—from other websites to be mimicked.
Themes¶
The visual appearance of the UI can be altered to tie it in with the rest of an organisation’s web presence.
When the UI is given a path to a local folder containing a theme CSS file and other files, it will serve them as static assets.
This mechanism can also be used to provide theme-specific favicons, a robots.txt file,
and any images used in the CSS or embedded in custom templates, amongst other things.
All files contained within the theme folder will be served relative to the root URL of the application,
with the exception of dotfiles (e.g. .gitignore, .env) which will be ignored.
Customising Excel downloads¶
Beyond the data itself, the content of Excel downloads can be customised with additional static content, or content from the metadata service.
By default, Excel downloads contain only a single “Table” sheet containing the data itself. Customising the file also allows the provision of a “Cover” sheet and a “Notes” sheet.
The following customisation is possible:
Cover sheet: add headings, paragraphs of text and links with both static content or metadata. The cover sheet is the first sheet seen when the Excel file is opened.
Notes: create a table of notes for the variables in the table containing text or links. The variable headings in the data table are automatically annotated with references to their related notes.
Table: additional headings, text and links can be added directly above the table of data.
Customisation of the Excel download is achieved through the provision of a special XML file that can be created by The Sensible Code Company.
Adding third-party JavaScript¶
By default, the public UI uses a Content Security Policy (CSP) that causes all scripts loaded from other origins to be blocked by the browser. This is to prevent the UI from being used as a vector for cross-site scripting attacks.
However, the UI can be configured to load third-party JavaScript, such as Google Analytics, through a combination of custom templates and by using the relevant environment variable to set a custom CSP header.
As with other aspects of UI customisation, it is recommended that this configuration be done in consultation with The Sensible Code Company.
Authentication¶
The user interface can be protected by an authentication mechanism to limit access to specific users. Two authentication mechanisms are available: credentials can be checked either against those supplied in a CSV file at startup or via integration with a LDAP server.
Access can also be limited by giving the service an allowed list of IP subnets on startup.
Details of how to configure authentication and access control are available on the command line
by running cantabular-ui -?.
Query result buffering¶
This service uses a set of memory buffers for storing output table cells
to allow data to be pulled from cantabular-server as soon as possible
to minimise the time a query result occupies memory
that could be used for processing of new queries.
The environment variable CANTABULAR_MAX_TABLE_BUFFER_MEMORY
can be used to specify the maximum amount of memory
that should be allocated for this purpose,
for example:
CANTABULAR_MAX_TABLE_BUFFER_MEMORY=4G
This variable should usually be set. It should be set as high as is feasible having taken account of other memory demands of the system.