Customizing portal themes¶
The default theme of all Opendatasoft portals can be entirely customized, not only in terms of layout and colors but also regarding specific areas such as header, footer, and catalog cards. Theme configurations and managed from the Look & feel > Theme subsection of the back office.
The Theme interface comprises 3 main blocks.
The header (1) which displays not only the title of the interface but also a Current action drop-down menu to manage versioning (see Versioning themes). 3 important buttons are also displayed in the header:
Save, to save the new configurations
Preview, to open in a new tab the Opendatasoft portal with the newly applied configurations
Make live, to define the newly applied configurations as the new, live theme available on the Opendatasoft portal
The API key for offline development management block (2), which allows the use and generation of new API keys (see note right below for more information).
It is possible to create stylesheets outside the platform, with any standard web developing tool, and to push them to the platform using an API key. For an easier and quicker usage, the Opendatasoft Portal Development Kit is at disposal: it is an open-source project created by Opendatasoft that can be downloaded on Github.
To find and use a theme API key, click on the API key for offline development block to expand it. The current API key is displayed in the block, ready to be copied and used.
It is also possible to generate a new API key by clicking on the Generate new key button. However, be careful when generating new API keys: only the current one can be used, which means that generating a new API key revokes all previous ones.
A block of 6 tabs (3), each one allowing to configure a part of an Opendatasoft portal theme (see Customizing a portal theme):
Layout options, to modify the general layout of the portal
Colors, to change colors of backgrounds, texts, borders, links, etc.
Stylesheet, to add more style to the portal with CSS
Header, to modify the header with HTML code
Footer, to modify the footer with HTML code
Catalog card, to modify the catalog cards with HTML code
Portal themes are versioned, which means that each customized new theme has a version number assigned to it. Once a theme is finished and made live, another version is automatically created: it is the new draft theme on which to work until it is ready to be live.
The Current action drop-down menu displayed in the header indicates which version one is currently working on. It also allows to select previous themes that were already made live.
Once a theme is live, it is completely locked: it is not possible to make any other modifications. Only the latest draft version can be modified.
While working on the latest draft version of the portal theme, it is possible to preview what the portal will look like with this new theme. A Preview button is indeed displayed between the Make live and Save buttons to open a new tab with the portal configured with the draft theme.
Only users able to edit the domain properties can preview the latest theme version. If sharing the URL with other users who were not granted the right permissions, they would see the portal with the live theme.
Customizing a portal theme¶
The Layout options tab allows to customize the portal layout, which by default relies on a 12-columns grid system inherited from the Bootstrap CSS framework.
More specifically, in this tab, it is possible to modify:
the Gutter width, which is the space (in pixels) between the various elements that compose an interface of the portal (columns, rows, and boxes), and
the Responsive breakpoints, which are the various screen widths (in pixels) at which the layout should change to adapt to the available space (for example, the portal layout should differ depending on whether it is used from a mobile phone or a desktop because the screen of a mobile phone is much smaller than that of a desktop). A web interface that adapts depending on the screen width is indeed called "responsive". There are 3 configurable breakpoints between 4 standard screen size associated with common devices:
Mobile to tablet: to go from an extra-small screen to a small screen
Tablet to desktop: to go from a small screen to a medium screen
Desktop to large desktop: to go from a medium screen to a large screen
Mobile, Tablet, Desktop, and Large desktop are used as reference because they are common devices that illustrate quite well the 4 standard screen sizes (extra-small, small, medium, and large) that can be encountered. Keep in mind that Mobile, for example, doesn't mean that the user is actually using a mobile device, but rather that the browser used by the user only offers an extra-small display area.
To modify a layout option:
Write a new width, in pixels, in the chosen textbox.
Click on the Save button in the top right corner.
The Colors tab allows to customize the colors used in the texts and links, backgrounds, and borders of the portal.
If a custom stylesheet has been created for the portal, the CSS rules that it contains will have precedence over the colors defined in the Colors tab.
The color of the following elements of an Opendatasoft portal can be configured in this tab:
To modify a theme color:
In the chosen textbox, write the hexadecimal code of the new color, or click the color button to choose a new color using either the Nice colors or the Color wheel.
Click on the Save button in the top right corner.
Theme colors can be used in the domain stylesheet, as CSS variables:
The available variables are:
These CSS variables are compatible with all browsers because the Opendatasoft platform automatically replaces all variables with their real theme color values.
The Stylesheet tab displays an editor in which to add pure CSS style rules. It allows the push even further the customization of a portal theme. All rules added in this tab will have precedence over the configurations defined in the other theme tabs.
To change the style of an element, find the element's class and change the desired CSS property. Class names are written as block, element, modifier:
When using specific images and fonts for the customization of the domain, don't hesitate to upload them as assets in the platform (see Adding assets). It allows to easily copy the assets URLs and paste them into the CSS code.
The Catalog card tab displays an editor in which to add pure HTML. It allows to customize the catalog cards displayed in the catalog of the portal, which represent the published datasets of that portal (see Exploring a dataset from the catalog).
The following directives allow to retrieve information related to a dataset, which could be included in the catalog card.
Directives used in the Catalog card tab come with a standard style, which can be modified in the Stylesheet tab.
||Mandatory. Wraps the whole catalog card for the other directives to work|
||Retrieves the dataset's theme and includes the related icon|
||Provides useful style and behavior handling edge cases (for example, datasets without records)|
||Retrieves the title of the dataset|
||Retrieves the description of the dataset|
||Retrieves the keywords defined for the dataset|
The table below lists all available metadata item keys: