Public Pages Configuration¶

Starting from Mica 4.0, the administration user interface is distinct from the public pages, i.e. pages that are to be accessed by regular users. These pages are based on templates that can be customized, extended or overridden. The template engine that is used is FreeMarker which has a clean and powerful syntax.

Page Templates¶

Configuring Pages¶

The main public pages are:

Page	Description
`index`	The home page
`profile`	The user profile page for updating personal information and password
`signin`	The login page
`signup`	The user registration page
`signup-with`	The user registration page, with form pre-filled with personal information extracted from a OpenID Connect server
`forgot-password`	The page to ask for password reset
`just-registered`	The welcome page after a user has registered
`networks`	The list of networks
`network`	The network page
`studies`	The list of studies and initiatives
`study`	The study page (can be individual study or harmonization initiative)
`datasets`	The list of datasets and protocols
`dataset`	The dataset page (can be collected datasets or harmonization protocols)
`variable`	The variable page (can be collected, data schema or harmonized)
`search`	The catalog search page
`projects`	The list of approved projects
`project`	The approved project page
`data-access-process`	The data access process presentation page
`data-accesses`	The list of data access requests (restricted access)
`data-access`	The data access request main page (there are other pages for each of the data access request forms and features)
`data-access-agreement-form`	The data access request agreement form page
`data-access-amendment-form`	The data access request amendment form page
`data-access-comments`	The data access request comments page
`data-access-documents`	The data access request documents page
`data-access-feasibility-form`	The data access request feasibility form page
`data-access-form`	The data access request main form page
`data-access-history`	The data access request history page
`data-access-preliminary-form`	The data access request preliminary form page
`data-access-private-comments`	The data access request private comments page
`contact`	The “Contact Us” form to send a contact request to the administrators or data access officers
`cart`	The variables/studies/networks cart page

The templates structure is organized in a way that it should not be necessary to override these main pages definitions. Instead of that, it is recommended to change/extend the theme/style as described in this guide.

The process of configuring these pages is the following (by order of priority):

1. Alter default settings¶

Some template variables (date formats, branding, favicon etc.) are defined in libs/settings.ftl and can be altered in the file models/settings.ftl that would be added in your configuration folder as follows:

MICA_HOME
└── conf
    └── templates
        └── models
            └── settings.ftl

If enough, this is the less intrusive approach. Note that you do not need to redefine all the settings, just reassign the ones of interest.

General settings¶

Variable	Description
`defaultLang`	The default language to be used when extraction labels from documents. If no text version is found for the page’s language, this default language’s version will be looked up.
`datetimeFormat`	The format in which the date-time values should be rendered.
`date`	The format in which the date values should be rendered.
`faviconPath`	The location of the favicon, to be modified to match your own.
`brandImageSrc`	The location of your organization’s logo.
`brandImageClass`	CSS classes to apply to the logo.
`brandTextEnabled`	Logical to show/hide a text aside of the logo.
`brandTextClass`	CSS classes to apply to the text aside of the logo.
`networkIcon`	CSS classes to apply to the <i> element to render the icon that represents a network.
`studyIcon`	CSS classes to apply to the <i> element to render the icon that represents a study.
`initiativeIcon`	CSS classes to apply to the <i> element to render the icon that represents a harmonization initiative.
`datasetIcon`	CSS classes to apply to the <i> element to render the icon that represents a dataset.
`harmoDatasetIcon`	CSS classes to apply to the <i> element to render the icon that represents a harmonization dataset.
`variableIcon`	CSS classes to apply to the <i> element to render the icon that represents a variable.
`dataschemaIcon`	CSS classes to apply to the <i> element to render the icon that represents a dataschema variable.
`projectIcon`	CSS classes to apply to the <i> element to render the icon that represents a project.
`taxonomyIcon`	CSS classes to apply to the <i> element to render the icon that represents a taxonomy.
`adminLTEPath`	The location of the AdminLTE theme if this one has been modified (see the Theme section in this documentation).

Home page settings¶

Variable	Description
`networksLink`	The link to list the networks. Default is the Networks menu.
`studiesLink`	The link to list the individual studies. Default is the Individual Studies menu.
`initiativesLink`	The link to list the harmonization initiatives. Default is the Harmonization Initiatives menu.
`datasetsLink`	The link to list the collected datasets. Default is the Collected Datasets menu.
`protocolsLink`	The link to list the harmonization protocols. Default is the Harmonization Protocols menu.
`portalLink`	The link applied to the logo. Default is the data portal itself (same as Home menu), but it could also be the organization’s main portal.
`showSignin`	Show the link to the Sign in page. Default is true when published content is private or data access request submission is enabled or the cart is enabled.

Cart page settings¶

Variable	Description
`variablesCartEnabled`	Logical to enable the cart of variables. Default is consistent with the application’s general configuration, but can be fine-tuned to make the cart visible to users within roles or groups.
`studiesCartEnabled`	Logical to enable the cart of studies. Default is consistent with the application’s general configuration, but can be fine-tuned to make the cart visible to users within roles or groups.
`networksCartEnabled`	Logical to enable the cart of networks. Default is consistent with the application’s general configuration, but can be fine-tuned to make the cart visible to users within roles or groups.
`cartEnabled`	Logical to show/hide the cart links (Cart menu, addition/removal to/from cart buttons). Default is true when one of the variables, studies or networks cart is enabled. It can be fine-tuned to make the cart visible to users within roles or groups.
`listsEnabled`	Logical to show/hide the lists links (Lists menu, addition to list buttons). Default is consistent with the application’s general configuration, but can be fine-tuned to make the lists visible to users within roles or groups.
`showCartDownload`	Logical to allow downloading the content of the cart. Default is restricted to users with administration-related role.
`showCartViewDownload`	Logical to allow downloading the content of the cart in the format of Opal views (for creating views in Opal from a variable selection). Default is restricted to users with administration-related role.
`defaultCartType`	Link to the cart page will show the specified cart type tab (one of ‘variables’, ‘studies’ or ‘networks’). Default is not specified, i.e. the first cart type tab will be active.

Compare page settings¶

Variable	Description
`studiesCompareEnabled`	Logical to enable the comparison of studies from the search page (no authentication required) or from the cart of studies (authentication required, see `studiesCartEnabled`).
`networksCompareEnabled`	Logical to enable the comparison of networks from the search page (no authentication required) or from the cart of studies (authentication required, see `studiesCartEnabled`).

Contact Us page settings¶

Variable	Description
`contactEnabled`	Logical to show/hide the Contact menu. Default is true, but can be restricted to users within roles or groups.

User Profile page settings¶

Variable	Description
`showProfileRole`	Logical to show/hide the role to which the user belongs.
`showProfileGroups`	Logical to show/hide the groups to which the user belongs.

Repository list pages settings¶

Variable	Description
`listDisplays`	Enumerate the different ways of rendering the lists of documents (networks, studies or datasets). Possible values are lines, table and cards. Some can be omitted (at least one is required) and the order matters.
`listDefaultDisplay`	Default display of a list of documents (networks, studies or datasets). Default is lines.
`networkListDisplays`	Specific enumeration of the different ways of rendering the lists of networks. Default is the same as specified by `listDisplay`.
`networkListDefaultDisplay`	Default display of a list of the networks. Default is the same as specified by `listDefaultDisplay`.
`studyListDisplays`	Specific enumeration of the different ways of rendering the lists of networks. Default is the same as specified by `listDisplay`.
`studyListDefaultDisplay`	Default display of a list of the studies. Default is the same as specified by `listDefaultDisplay`.
`datasetListDisplays`	Specific enumeration of the different ways of rendering the lists of networks. Default is the same as specified by `listDisplay`.
`datasetListDefaultDisplay`	Default display of a list of the studies. Default is cards.

Search page settings¶

Variable	Description
`defaultSearchState`	The state of the interface when entering the search page. Default is showing the list of studies or the list of variables when there is only one study.
`defaultIndividualSearchState`	The state of the interface when entering the individual search page. Default is showing the list of individual studies or the list of variables when there is only one study.
`defaultHarmonizationSearchState`	The state of the interface when entering the harmonization search page. Default is showing the list of harmonization initiatives or the list of variables when there is only one initiative.
`downloadQueryEnabled`	Logical to show/hide the button for downloading the results of the query. Default is true, but can be restricted to users within roles or groups.
`showCopyQuery`	Logical to show/hide the button for copying the query string, that can be used in the R or Python API. Default is restricted to users with administration-related role.
`mapName`	Map name to be used in the graphic geographical-distribution-chart. Default is world, possible values are world, europe, north-america, south-america, asia, africa or oceania.
`searchCharts`	Show/hide and order the graphics by specifying their name. Possible values are geographical-distribution-chart, study-design-chart, number-participants-chart, bio-samples-chart or study-start-year-chart.
`searchVariableListDisplay`	Logical to show/hide the list of variables resulting from the search. Default is consistent with the application’s general configuration.
`searchDatasetListDisplay`	Logical to show/hide the list of datasets resulting from the search. Default is consistent with the application’s general configuration.
`searchStudyListDisplay`	Logical to show/hide the list of studies resulting from the search. Default is consistent with the application’s general configuration.
`searchNetworkListDisplay`	Logical to show/hide the list of networks resulting from the search. Default is consistent with the application’s general configuration.
`searchVariableColumns`	Show/hide and order the column names for the list of variables. Possible values are label, label+description (variable label with a tooltip that shows the description), valueType, annotations, type, study, population, data-collection-event/dce, initiative, dataset or protocol. This configuration will be used when on the `/search` path.
`searchVariableColumnsHarmonization`	Same as the `searchVariableColumns` configuration but will be used when on the `/harmonization-search` path.
`searchVariableColumnsIndividual`	Same as the `searchVariableColumns` configuration but will be used when on the `/individual-search` path.
`searchDatasetColumns`	Show/hide and order the column names for the list of datasets. Possible values are name, type, networks, studies, initiatives or variables.
`searchDatasetColumnsHarmonization`	Same as the `searchDatasetColumns` configuration but will be used when on the `/harmonization-search` path.
`searchDatasetColumnsIndividual`	Same as the `searchDatasetColumns` configuration but will be used when on the `/individual-search` path.
`searchStudyColumns`	Show/hide and order the column names for the list of studies. Possible values are name, type, study-design, data-sources-available, participants, networks, individual or harmonization.
`searchStudyColumnsHarmonization`	Same as the `searchStudyColumns` configuration but will be used when on the `/harmonization-search` path.
`searchStudyColumnsIndividual`	Same as the `searchStudyColumns` configuration but will be used when on the `/individual-search` path.
`searchNetworkColumns`	Show/hide and order the column names for the list of networks. Possible values are name, studies, datasets, harmonization, individual or variables.
`searchNetworkColumnsHarmonization`	Same as the `searchNetworkColumns` configuration but will be used when on the `/harmonization-search` path.
`searchNetworkColumnsIndividual`	Same as the `searchNetworkColumns` configuration but will be used when on the `/individual-search` path.
`searchVariableFields`	List of the variable fields to be extracted from search results.
`searchDatasetFields`	List of the dataset fields to be extracted from search results.
`searchStudyFields`	List of the study fields to be extracted from search results.
`searchNetworkFields`	List of the network fields to be extracted from search results.
`searchVariableSortFields`	List of the variable fields to be used for sorting the search. Default is to sort by study, dataset, index (i.e. order in the dataset’s data dictionary) and name.
`searchDatasetSortFields`	List of the dataset fields to be used for sorting the search. Default is to sort by study, population, data collection event and acronym.
`searchStudySortFields`	List of the study fields to be used for sorting the search. Default is to sort by acronym.
`searchNetworkSortFields`	List of the network fields to be used for sorting the search. Default is to sort by acronym.
`searchCoverageDisplay`	Logical to show/hide the Coverage search results tab.
`searchGraphicsDisplay`	Logical to show/hide the Graphics search results tab.
`searchListDisplay`	Logical to show/hide the List search results tab.
`searchCriteriaMenus`	Show/hide the search criteria in the sidebar by specifying their type (possible values are variable, dataset, study, network).

Variable page settings¶

Variable	Description
`showHarmonizedVariableSummarySelector`	For a dataschema variable, allow the possibility to display the summary statistics of a specific harmonized variable. Default is true.

Data Access pages settings¶

Variable	Description
`dataAccessInstructionsEnabled`	Show/hide the instructions panel on the side of the data access form. Default is true.
`dataAccessCalloutsEnabled`	Show/hide the callout panels on the head of the data access pages. Default is true.
`dataAccessReportTimelineEnabled`	Show/hide the report timeline in the dashboard page when the data access is approved. Applies only when a project end date can be found. Default is true.
`dataAccessArchiveEnabled`	Show/hide the Archive button, to users with appropriate permissions and when the data access request is completed. Default is true.
`showDataAccessEventsInComments`	List of each data access form type which events are to be included in the life line of the comments, so that users can contextualize the comments with the changes of the data access forms status. Possible values are request, preliminary, feasibility, amendment and agreement, default is all.

Charts settings¶

Variable	Description
`barChartBackgroundColor`	Background color of the chart elements (the bars or the countries for instance).
`barChartBorderColor`	Border color of the chart elements.
`colors`	List of colors to be used for a set of chart elements (portions of a pie chart for instance).

Files settings¶

Variable	Description
`showFiles`	Logical to show/hide the files that are associated to the documents (networks, studies, populations, data collection events, datasets). Default is true, but can be restricted to users within roles or groups. Note that the files can themselves require permissions.
`showNetworkFiles`	Logical to show/hide the files that are associated to the networks. Default is the same as what specified by `showFiles`.
`showStudyFiles`	Logical to show/hide the files that are associated to the studies. Default is the same as what specified by `showFiles`.
`showStudyPopulationFiles`	Logical to show/hide the files that are associated to the study populations. Default is the same as what specified by `showFiles`.
`showStudyDCEFiles`	Logical to show/hide the files that are associated to the study data collection events. Default is the same as what specified by `showFiles`.
`showDatasetFiles`	Logical to show/hide the files that are associated to the datasets. Default is the same as what specified by `showFiles`.

Variables classifications charts settings¶

Variable	Description
`variablesClassificationsTaxonomies`	Enumerate the taxonomy names to render the charts of variables classifications coverage (count of variables annotated with each vocabulary). Default is Mlstr_area. If the list is empty, no chart will be displayed.
`networkVariablesClassificationsTaxonomies`	Enumerate the taxonomy names to render the charts of variables classifications coverage in the network page. Default value is `variablesClassificationsTaxonomies`.
`studyVariablesClassificationsTaxonomies`	Enumerate the taxonomy names to render the charts of variables classifications coverage in the study page. Default value is `variablesClassificationsTaxonomies`.
`datasetVariablesClassificationsTaxonomies`	Enumerate the taxonomy names to render the charts of variables classifications coverage in the dataset page. Default value is `variablesClassificationsTaxonomies`.

2. Override one of the page model templates¶

The model templates are to be found in the models folder. This allows to alter some portions of the pages, without affecting the general layout.

The override of the template is done by installing a file with same name, at the same relative location in the application’s configuration folder.

MICA_HOME
└── conf
    └── templates
        └── models
            └── <template name>.ftl

This is the preferred approach when a document’s model was modified (new fields added/removed to the network, study, dataset etc.).

3. Override the main page templates¶

These templates are located at the templates’ root folder. This gives full control of the page content but may ignore enhancements or break when upgrading the application.

The override of the template is done by installing a file with same name, at the same relative location in the application’s configuration folder.

MICA_HOME
└── conf
    └── templates
        └── <template name>.ftl

Adding Pages¶

It is possible to add new pages, for providing additional information or guidance to the regular user. This can be done as follows:

Install a new page templates
Add a new menu entry

1. Install custom page template¶

The new template page is to be declared in the configuration folder:

MICA_HOME
└── conf
    └── templates
        └── custom.ftl

You can check at the provided templates to make your template fit in the site theme and structure. The profile page template could be a good starting point.

FreeMarker will look at its context to resolve variable values. For a custom page the objects available in the context are:

Object	Description
`config`	The Mica configuration
`user`	The user object (if user is logged in)
`roles`	The list of user roles: `mica-administrator`, `mica-reviewer`, `mica-editor`, `mica-data-access-officer` or `mica-user` (if user is logged in)
`query`	The URL query parameters as a map of strings

This custom template page can load any CSS or JS file that might be useful. These files can be served directly by adding them as follows (there are no restrictions regarding the naming and the structure of these files, as soon as they are located in the static folder):

MICA_HOME
└── conf
    └── static
        ├── custom.css
        └── custom.js

The URL of this custom page will be for instance: https://mica.example.org/page/custom.

Theme and Style¶

Theme¶

The default theme is the one provided by the excellent AdminLTE framework. It is based on Bootstrap and JQuery. In order to overwrite this default theme, the procedure is the following:

Build a custom AdminLTE distribution
Install this custom distribution
Change the template settings so that pages refer to this custom distribution instead of the default one

1. Build custom AdminLTE

This requires some knowledge in CSS development in a Node.js environment:

Download AdminLTE source (source code or a released version)
Reconfigure Sass variables
Rebuild AdminLTE (see instructions in the README file, contributions section)

2. Install custom AdminLTE

The objective is to have the web server to serve this new set of stylesheet and javascript files. This is achieved by creating the folder MICA_HOME/conf/static and copying the AdminLTE custom distribution in that folder. Not all the AdminLTE are needed, only the dist and plugins ones. The folder tree will look like:

MICA_HOME
└── conf
    └── static
        └── admin-lte
            ├── dist
            └── plugins

3. Template settings

Now that the custom AdminLTE distribution is installed in the web server environment, this new location must be declared in the page templates. The default templates settings are defined in the libs/settings.ftl template file. See the adminLTEPath variable. This variable can be altered by defining a custom settings.ftl file as follows:

MICA_HOME
└── conf
    └── templates
        └── models
            └── settings.ftl

In this custom settings.ftl file the new AdminLTE distribution location will be declared:

adminLTEPath = "/admin-lte"/>

Style¶

As an alternative to theming, it is also possible to alter the style of the pages by loading your own stylesheet and tweaking the pages’ layout using javascript (and JQuery). The procedure is the following:

Install custom CSS and/or JS files
Custom the templates to include these new CSS and/or JS assets

1. Install custom CSS/JS

The objective is to have the web server to serve this new set of stylesheet and javascript files. This is achieved by creating the folder MICA_HOME/conf/static and copying any CSS/JS files that will be included in the template pages. The folder tree will look like:

MICA_HOME
└── conf
    └── static
        ├── custom.css
        └── custom.js

2. Custom templates

For the CSS files, the models/head.ftl template allows to extend the HTML pages “head” tag content with custom content. For the JS files, the models/scripts.ftl template allows to extend the HTML pages “script” tags. The folder tree will look like:

MICA_HOME
└── conf
    └── templates
        └── models
            ├── head.ftl
            └── scripts.ftl

Where the head.ftl template will be:

<link rel="stylesheet" href="/custom.css"/>

And the scripts.ftl template will be:

<script src="/custom.js"/>

Translations¶

The translations are performed in the following order, for a given locale:

check for the message key in the messages_<locale>.properties (at different locations)
check for the message key in the <locale> JSON object as defined the Administration > Translations section of the administration interface

For the messages_* properties, the translations can be added/overridden as follows:

MICA_HOME
└── conf
    └── translations
        ├── messages_fr.properties
        └── messages_en.properties

Note that you can declare only the messages_* properties files that are relevant (locales available from the website) and the content of these files can contain only the translation keys that you want to override.