This page explains how to use the excel configuration tool, the main concepts of the REST API and Angular UI are explained here: Item details: layout & security

To speedup the configuration of the layout and data security aspects of DSpace-CRIS administrators can use the script named “cris-layout-tool”.

That script requires the following parameters:

f (file) → the source file with the full cris layout configuration

In the folder dspace-install/bin run

./dspace cris-layout-tool -f ../etc/conftool/cris-layout-configuration.xls

In the folder dspace/etc/conftool it is included the excel file cris-layout-configuration.xls representing the default configuration of DSpace-CRIS. The file has several tabs.

Cris Layout Tool Sheets

tab

It contains the details about all the tabs that need to be created.

- Entity: it is the label of the Entity Type to which the tab belong. A tab’s shortname must be unique for a specific entity
  - this column can also contain a custom filter (check the custom filter section for more info) Item details: layout & security
- Shortname: it is an unique name assigned to the tab, used to refer to it in the other sheets and configuration
- Label: it is the human readable name of the tab or the i18n key (see paragraph i18n keys conventions)
- Priority: the tabs are sorted by priority in ascending order
- Leading: It can be y (yes) or n (no). If set to yes the tab is shown on the top of the item’s page and remains there even if the user browse the other tabs. In order for the profile details tab to always remain visible even when you scroll through the other tabs (e.g. publication or projects tab) the leading column must have marked y, and in this case it will always be placed at the top.
  If no tab is chosen as leading (hence column with n), they will all be placed at the bottom, but since there is no leading tab, every time user scrolls to the tabs the details info will not be visible.
- Security: it defines who has access to the tab

box

It contains the details about all the boxes that need to be created. The order in which they are listed will be respected for each entity type in the UI.

- Entity: it is the label of the Entity Type to which the box belong. A box’s shortname must be unique for a specific entity
  - this column can also contain a custom filter (check the custom filter section for more info) Item details: layout & security
- Collapsed. It can be y (yes) or n (no). When collapsed is y the box is shown as a closed panel in the default theme
- Container. It can be y (yes) or n (no). When container is y the outline of the box is shown, including the section at the top with the name.
- Type. It is the box’s type available options are listed in the utilsdata sheet
- Shortname: it is an unique name assigned to the box, used to refer to it in the other sheets and configuration
- Label: it is the human readable name of the box or the i18n key (see paragraph i18n keys conventions)
- Minor. It can be y (yes) or n (no). Minor box are not used to determine if a tab actually has content to show to the user.
- Security: it defines who has access to the box
- Style. It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the box panel and can be used to bind the box to the bootstrap grid (i.e. col-md-6 to size the box to half page)

tab2box

It links box to a specific tab.

- Entity and Tab colums are used to lookup in the tab sheet (Tab → Shortname).
- Entity and Boxes colums are used to lookup in the box sheet (Box → Shortname). The Boxes column is a comma separated list of boxes name.
- Row: The row of the tab where place the given boxes. If the same row is specified for the same tab, the boxes are placed in a new cell with the given cell style
- Row_style: The row’s style where the boxes are placed. Same row must have the same style (or at least empty)
- Cell_style: The cell’s style where the boxes are placed in the given row.

box2metadata

It provides extra configuration details for metadata box such as the list of metadata (fields) included.

- Entity and Box colums are used to lookup in the box sheet (Box → Shortname).
- Row. The number of the row where the field will be added.
- Cell. The number of the cell where the field will be added.
- Row_style. The style of the row where the field will be added.
- Cell_style. The style of the cell where the field will be added.
- FieldType. The field’s type such as METADATA or BITSTREAM or METADATAGROUP
- Metadata. The metadata key of the field
- Value. For bitstream field only, limit the bitstream to list to the one where the metadata has such value
- Bundle. Required for bitstream field only, limit the bitstream to list to the one that belong to a bundle with the specified name. Since the 2023.02.08, 2024.02.02 and 2025.01.00 versions, two bundles can be used to declare from which bundle the bitstream to be shown should be retrieved, and from which bundle the same bitstream can be downloaded: <VIEW_BUNDLE>.<DOWNLOAD_BUNDLE> (e.g. ORIGINAL.BRANDED_PREVIEW).
- Label: it is the human readable name of the field or the i18n key (see paragraph i18n keys conventions)
- Rendering. A custom display strategy to apply to the field
- Style. It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the field container.
- Style_label: It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the label.
- Style_value: It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the value.
- Label_as_heading: It can be y (yes) or n (no). If yes the label is shown above the value rather than to the left
- Values_inline: It can be y (yes) or n (no). If yes the values of the same metadata field are shown inline, if no are shown in column

metadatagroups

It provides extra configuration details for nested metadata that should be visualized as a group.

- Entity : it is the label of the Entity Type to which the neted metdata belong.
- Parent: The name of main metadata which all the nested metdata are related to. This metadata must be present also in the box2metadata tab with type METADATAGROUP
- FieldType. The field’s type must be always METADATA.
- Metadata. The metadata key of the field
- Value. For bitstream field only, limit the bitstream to list to the one where the metadata has such value
- Bundle. Required for bitstream field only, limit the bitstream to list to the one that belong to a bundle with the specified name. Since the 2023.02.08, 2024.02.02 and 2025.01.00 versions, two bundles can be used to declare from which bundle the bitstream to be shown should be retrieved, and from which bundle the same bitstream can be downloaded: <VIEW_BUNDLE>.<DOWNLOAD_BUNDLE> (e.g. ORIGINAL.BRANDED_PREVIEW).
- Label: it is the human readable name of the field or the i18n key (see paragraph i18n keys conventions)
- Rendering. A custom display strategy to apply to the field
- Style_label: It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the label.
- Style_value: It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the value.

box2metrics

It provides configuration details for box displaying metrics.

- Entity : it is the label of the Entity Type to which the neted metdata belong.
- Box: name of the box, as defined in “Box” sheet.
- Metric_type. List of metrics to be displayed in the box. Currently supported metrics are: scopus-author-h-index, scopus-author-coauthor-count, scopus-author-cited-count, scopus-author-citation-count, scopus-author-document-count, view, embedded-view, google-scholar, plumX, altmetrics (only for publications), dimensions (only for publications), download (only publications), embedded-download, scopusCitation, wosCitation, wosPersonCitation

tabpolicy and boxpolicy

They provide extra information for tab and box configured to have custom security policy (security = CUSTOM DATA)

- Entity and Shortname colums are used to lookup in the tab and box sheet
- Metadata. It contains the metadata key in the format schema.element[.qualifier] (i.e. cris.policy.group) that holds the information about which groups or users can access the linked tab or box
- Group: is alternative to metadata. It is used to check if the current user belongs to this group in order to display certain boxes/tabs
- Alternative_to: it contains the name of the tab/box to be displayed is the current user is not allowed to access the box/tab defined in Shortname

utilsdata

The sheet is not really used by the tool. It is intended to help with the filling out of the excel

tab_i18n, box_i18n, metadata_i18n, metadatagroup_i18n

see last paragraph

The tool performs the following actions in subsequent order stopping in case of failure

validate the excel configuration file reporting any identified inconsistency such as, undefined entity types, metadata, missing tabs or boxes referenced in the association sheets, etc.
completely wipe the current layout configuration
load the configuration

Available rendering strategies

I18n key conventions

When file reports i18n keys references to be used as labels, following conventions are followed

Type of label

Prefix

Example (to be added to translation files)

Tab

layout.tab.header.<tabShortName>

layout.tab.header.<boxShortName> still works as fallback value

"layout.tab.header.OrgUnit.details": "Organization Details",

"layout.tab.header.details": "Details", (fallback value)

Box

layout.box.header.<entityType>.<boxShortName>

layout.box.header.<boxShortName> still works as fallback value

"layout.box.header.OrgUnit.altmetrics": "Organization alternative Metrics",

"layout.box.header.altmetrics": "Alternative Metrics", (fallback value)

Metadata / Metadatagroups

layout.field.label.<entityType>.Metadata

"layout.field.label.Equipment.dc.type": "Cost Type",

Utility sheets to generate keys to be added to internationalization files (en.json etc...):

tab_i18n, box_i18n, metadata_i18n, metadatagroup_i18n

are available on cris-layout-configuration.xls file, with following formulas used (from B2 cell):

Sheet	Formula
`tab_i18n`	=IF(OR(ISBLANK($tab.$C2);EXACT(MID($tab.$C2;1;LEN($A$2));$A$2));"";""""&$A$2&$tab.$A2&"."&$tab.$B2&""": """&SUBSTITUTE($tab.$C2;""""; """")&""",")
`box_i18n`	=IF(OR(ISBLANK($box.$E2);EXACT(MID($box.$E2;1;LEN($A$2));$A$2));"";""""&$A$2&$box.$A2&"."&$box.$D2&""": """&SUBSTITUTE($box.$E2;"""";"""")&""",")
`metadata_i18n`	=IF(ISBLANK($box2metadata.$I2);"";""""&$A$2&$box2metadata.$A2&"."&IF(ISBLANK($box2metadata.$F2);$box2metadata.$E2;$box2metadata.$F2)&""": """&SUBSTITUTE($box2metadata.$I2;"""";"""")&""",")
`metadatagroup_i18n`	=IF(ISBLANK($metadatagroups.$D2);"";""""&$A$2&$metadatagroups.$A2&"."&$metadatagroups.$D2&""": """&SUBSTITUTE($metadatagroups.$G2;"""";"""")&""",")

Tabs and boxes

In the case of boxes, one of the following values will be showed, from highest to lowest priority:

The translation of layout.***.header.<entityType>.<shortName>
The translation of layout.***.header.<shortName>
The translation of the LABEL field, if it is a valid i18n key (it should have the same prefix layout.***.header.)
The content of the LABEL field

Tabs, metadata and metadata groups

One of the following values will be showed, from highest to lowest priority:

The translation of the automatically generated i18n key
The translation of the label, if it is a valid i18n key
The content of the label

Custom layout for the same Entity type using a custom filter

In some cases we might want to define a custom layout for certain items identified by a specific criteria. The column ENTITY for both tab & box sheets allow to add some criteria to define a custom layout.

The standard/default layout is defined by simply using the Entity type in the ENTITY columns for the tab & box sheets. For a customized layout the following rules can be followed to achieve the desired layout configuration.

For values under the ENTITY column the following criteria can be followed:

<entity-type>.<submission-definition>.<metadata-authority>
<entity-type>.<submission-definition>.<metadata-value>
<entity-type>.<submission-definition>
<entity-type>

<metadata-authority> & <metadata-value> are retrieved from the item using the metadata defined in dspace.metadata.layout.tab on dspace.cfg set by default to dc.type

The order above represents also the priority followed to match the custom layout. This means that if we have all the four matching layout configuration the first one is the one that is used.

If the first condition/custom filter is not matched and there’s a match for the second custom filter the layout with the second custom filter is used ans so on.

Example

We have the following custom filters configured:

Publication.collection1_submission.c_ddb1
Publication.collection1_submission.test_value
Publication.collection1_submission
Publication

Matching example

A Publication Item using a submission with name collection1_submission and with a dc.type whose authority field is set to c_ddb1 and value set to test_value will match the first layout case
A Publication Item using a submission with name collection15_submission and with a dc.type whose authority field is set to c_ddb1 and value set to test_value will match the fourth layout case
A Publication Item using a submission with name collection1_submission and with a dc.type whose authority field is set to c_ddb55 and value set to test_value will match the second layout case
A Publication Item using a submission with name collection1_submission and with a dc.type whose authority field is set to test_authority2 and value set to value2 will match the third layout case