[DSpace-CRIS] Configurable Layout of Entity/Item pages#5963
Draft
FrancescoMolinaro wants to merge 7 commits into
Draft
[DSpace-CRIS] Configurable Layout of Entity/Item pages#5963FrancescoMolinaro wants to merge 7 commits into
FrancescoMolinaro wants to merge 7 commits into
Conversation
Remove DynamicLayoutConfig nesting and move urn, itemPage, metadataBox, and collectionsBox properties directly under the layout interface to eliminate unnecessary nesting levels. Changes: - Update layout-config.interfaces.ts: Remove DynamicLayoutConfig interface and add urn, itemPage, metadataBox, collectionsBox directly to LayoutConfig - Update default-app-config.ts: Move dynamicLayout properties to top level - Update environment.test.ts: Move dynamicLayout properties to top level - Update component property access from layout.dynamicLayout.* to layout.*: * dynamic-layout-loader.component.ts * dynamic-layout-collection-box.component.ts * metadata-container.component.ts * resolver-strategy.service.ts * identifier.component.ts - Update config.example.yml: Flatten structure and enhance documentation Before: layout.dynamicLayout.urn layout.dynamicLayout.itemPage layout.dynamicLayout.metadataBox layout.dynamicLayout.collectionsBox After: layout.urn layout.itemPage layout.metadataBox layout.collectionsBox Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…add missing property
…xt menu was, add min width for dynamic thumbnail component
…micRef, fix layout loader names and imports
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…ion, fix replace in string for html/longHtml rendering components
FrancescoMolinaro
added
the
DSpace-CRIS merger
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
References
Issue: DSpace/DSpace#11779
Backend: DSpace/DSpace#12789
Description
The Dynamic layout (ex CRIS layout) allows to manage the visualization and access to the item data in a more fine-grain way than the default DSpace.
The layout is organized in an excel file and the item information is organized over two levels, tabs and boxes. Each tab can contain one or more boxes organized in a sort of grid composed by rows and cells. The same box can be eventually shared between multiple tabs with a specific order in each tab. A box represents the minimal unit of information about an item that can be visualized and protected.
If an entity type is not defined in the excel file the default DSpace layout is displayed.
Basic examples:
Vertical and horizontal Layout
It is possible to have a main leading tab always visible and to organize the remaining tabs with a layout having two different orientations : vertical and horizontal. In the horizontal layout the tabs are arranged inside a top navbar, while in the vertical one they are arranged within a lateral sidebar.
Only tabs and boxes that contain data visible to the current user are listed. If a tab only contains boxes without visible data or that are flagged as minor, such tab is not listed at all.
In both vertical and horizontal layout when only one tab is available sidebar and navbar are not displayed.
It’s possible to use one of the two layout (vertical or horizontal) differently depending on the type of entity. To select the layout, the DSpace angular application provide an itemPage settings under the layout property in the environment file (src/environments/environment.common.ts), e.g.
itemPage: { Person: { orientation: 'horizontal' }, default: { orientation: 'vertical' }, },Tab grid system
In order to have a more flexible way to arrange boxes within a tab a grid system is used. The grid system uses a series of rows and cells to layout and align boxes, following these rules :
Every row can contains one or more cells
Every cell can contain one or more boxes
All cells inside the same row are displayed one next to the other
All boxes inside the same cell are displayed one below the other
Example:
Tab and Box models
The tabs are represented by the org.dspace.layout.DynamicLayoutTab java class and exposed in the REST layer via the org.dspace.app.rest.model.DynamicLayoutTabRest. The boxes are represented by the org.dspace.layout.DynamicLayoutBox java class and exposed in the REST layer via the org.dspace.app.rest.model.DynamicLayoutBoxRest and org.dspace.app.rest.model.DynamicLayoutBoxConfigurationRest. The later one, in particular, is the extension point to plug the different types of boxes in the platform.
Tabs and Boxes are bound to a specific Entity Type and share the following attributes:
shortname. It is an alias of the Id used to refer to the tab / box from configuration files, without the need to hardcode the database generated Id
label. It is the label, or the i18n key, to use to present the section to the user. In case you want to use the header as a translation key, the complete i18n key used by the system has the prefix layout.tab.header. for the tab, and layout.box.header. for the box
security. It can have one of the following values:
0 → public. Everyone can access the data contained in the tab (if the security is not overridden by the box security), or box
1 → administrator. Only system administrator can access the data
2 → owner only. Only the owner of the item can access the data. Please note that the concept of item owner is specific of DSpace-CRIS and it is different from the submitter. The item owner is defined by the dspace.object.owner metadata
3 → owner and administrator. Only the owner of the item and the system administrator can access the data
4 → custom policy. The list of people and groups that can access the data are defined in other metadata of the item itself. The metadata to use are defined in the securityMetadata attribute that contains a list of reference to metadata fields that are expected to be configured with the EPersonAuthority or GroupAuthority
leading. It can be true or false. If true, the tab is shown on the top of the item’s page and remains there even if the user browse the other tabs
priority. Attribute that is used to sort them in ascending order
rows. It contains the configuration of the grid used to display boxes beloging to the current tab. Each row is composed by cells that contains the list of boxes. Boxes have a specific order inside each cell that include them.
container. It can be true or false. If true, the box is show as a collapsible panel, otherwise it has no container and is always visible
collapsed. When true, and box container property is set to true, the box panle start collapsed, and the user need to open it to see the actual data
minor. It is true when the box should not be used to determine if a tab actually has content or not
style. It is added to the CSS classes of the generated html element that contains the tab or box to allow further customization via CSS
configuration. It contains additional information used to render the data in the appropriate way
Nested tabs
It’s possible to have two or more tabs grouped by the same top menu entry. In this case the tab entries are displayed with a dropdown in the sidebar and navbar .
To configure the nested two or more tabs, the shortname property and label may contain the parent and child tabs concatenated by ::.
Following the previous example where we have two tabs, publications and fundigs, grouped by a the top level tab outputs , the configuration is like :
shortname -> label
outputs::publications -> Outputs::Publications
When relating boxes to nested tab, the shortname of the tab to use must include also the top level ( e.g. outputs::publications).
Box types
The most simple and used is named METADATA.
A metadata box is a collection of item metadata fields and selection criteria over the item bitstreams, organized in rows, each of which can contain one or more fields. Three types of fields exist (metadata and bitstream), their additional configuration options are exposed in an attribute with the same name than the fieldType:
METADATA. The field holds the values stored in an item metadata identified with the .[.] syntax that is exposed in the metadata attribute
METADATAGROUP. The field holds the values stored in a group of nested metadata identified with the .[.] syntax that is exposed in the metadata attribute
BITSTREAM. The field holds the bitstreams in a specific item bundle optionally matching a specific value for a metadata.
IIIFVIEWER. The field holds an embedded Mirador viewer. This is showed only if the metadata dspace.iiif.enabled is set to true.
The bitstream attribute is an object containing the:
bundle, the name of the bundle
metadataField and metadataValue, optional, the value of a specific bitstream metadata that will be used to filter which bitstreams are included in the field. If the metadataValue start with a ! the filter become negative (only return bitstreams that don’t match the criteria). It is also possible specify a regex puting the metadataValue between bracket (...regex...), or a negative regex !(...regex...)
Regardless to the fieldType, each field has the following attributes:
label. The textual label or i18n key to use as label for the field. In case you want to use the header as a translation key, the complete i18n key used by the system has the prefix layout.field.header.
rendering. The rendering strategy for the field. Examples are heading, text, longtext, dynamicref, identifier, date, link etc. for metadata field, and preview, thubmnail for bitstream field
styleLabel. The style attribute allows to set arbitrary css styles to the metadata’s label
styleValue. The style attribute allows to set arbitrary css styles to the metadata’s value
labelAsHeading. If true, the metadata value is displayed below the metadata label. If false, metadata value is displayed along the metadata label
valuesInline. If true, when a metadata has multiple values, they are displayed one along the others. If false, they are displayed one below the others
Another type of box present is the RELATION box.
This box is bound to a DiscoveryConfiguration that can be parameterized with the uuid of the item. The defaultFilterQueries of the DiscoveryConfiguration can contains the placeholder {0} that will be replaced at runtime with the uuid of the item. Please refer to next paragraph for further details about how to set and configure such queries.
Discovery queries are configured via discovery.xml file (/config/spring/api/discovery.xml) , in org.dspace.discovery.configuration.DiscoveryConfigurationService bean. A map’s entry for each relation is provided, standard pattern for key is RELATION... Entity and relationName must match to what reported in xls file, box sheet, ‘ENTITY’ and ‘SHORTNAME’ entries for each relation. For example, RELATION.Project.researchoutputs identifies the relation that will be used to populate 'researchoutupts' box configured in excel file for entity 'Project'.
The core part of DiscoveryConfiguration, for relation’s set up is defaultFilterQueries. This section contains one or more filter queries to be performed, given Item’s uuid, to find linked Items. In case many filter queries are provided, such queries are executed in sequence: the second query filters first query’s results and so on.
This is the query that retrieves projects related to a person: projectinvestigators_authority:{0}, where {0} is a placeholder for UUID of the person. In case of inverse relations, queries are more complex and a subquery is needed. For exampl,e this is the query that finds Projects belonging to every person affiliated to an OrgUnit, given OrgUnit UUID: '{'!join from=search.resourceid to=projectinvestigators_authority fromIndex=search'}'person.affiliation.name_authority:{0}.
Another type of box available is the COLLECTIONS box.
The COLLECTIONS box shows the owning collection of an item, and all mapped collections:
It is possible to customise the appearance of this box through the property collectionsBox in the default.app.config.ts.
Box grid system
In a very similar way to what we have for tabs, the grid system is used also to locate metadata within a metadata box. The grid system uses a series of rows and cells to layout and align metadata, following these rules:
Every row can contains one or more cells
Every cell can contain one or more metadata
All cells inside the same row are displayed one next to the other
All metadata inside the same cell are displayed one below the other
Rendering Types
The rendering types are different ways of displaying the metadata to the user, each of them is connected to a different UI component and offers a different functionality.
The available types are descripted in the following table:
headingtextlongtextlinklabel,email[Link label](URL)with thelink.labelrendering. To add a clickable email address, insert the email address in the field with thelink.emailrendering.datebcdateidentifierhdl,doi,scopus,researcherid,mailto,rordynamicreffirst3.last1thumbnailattachmentadvancedattachmenttagvaluepair<value_pairs_name>or<vocabulary_name>orcidtableMETADATAGROUPinlineMETADATAGROUPauthoritylinkhtmllonghtmlcclicenseMETADATAGROUPcclicensefullMETADATAGROUPSecurity of the metadata
The dynamic layout allows a more granular control of the security. It is possible to configure which metadata are available to different users. Out of box the dynamic layout behavior mimic the one implemented by DSpace, metadata are generally available to any user (anonymous) with the only exception of the metadata listed in the configuration files with the key metadata.hide..[.] = true
When the dynamic layout defines tabs or boxes that have a limited access the metadata used in these tabs / boxes are checked in details and a user will be able to retrieve them via API, so in the UI, only if the user has the right to access such metadata via at least one box. This mean that metadata not used in the dynamic layout are generally public but can still be restricted to the administrators using the metadata.hide. configuration keys.
A special project named preventMetadataSecurity exists to skip the evaluation of the granular security logic where appropriate. This is the case when a large number of items are retrieved to show just a limited amount of data that are known to be not controversial. Indeed, if the client specify this projection in the REST request only the metadata listed under the configuration key metadata.publicField are returned without wasting time in further check . This mean that using such projection also authorized users are unable to retrieve potential sensible data.
The dynamic layout goes a step further and other than providing a granular security at the level of individual metadata field it is also able to define a further access rule to decide which individual metadata values are visible to a specific user.
This is configured in the metadata-security.cfg file where this feature can be enabled for all the metadata or a specific subset, defining the default configuration (usually no further restriction as in a basic DSpace) for metadata that are not explicitly mentioned. The exact meaning of the different metadata value security level is defined in the spring-dspace-security-metadata.xml file and by default offer
Dynamic Layout Tool Sheets
The Dynamic Layout configuration is organized into multiple sheets. Each sheet defines a specific aspect of the UI layout.
tabDefines all tabs that should be created.
yorn. Ify, the tab remains fixed at the top of the item page while browsing other tabs. If no tab is marked as leading, all tabs are placed below the page header and the details section scrolls out of view.boxDefines all boxes displayed within tabs. Boxes are rendered in the order they appear.
yorn. Wheny, the box is initially collapsed in the default theme.yorn. Wheny, the box is rendered with its surrounding panel and title.utilsdatasheet.yorn. Minor boxes are ignored when determining whether a tab contains visible content.col-md-6).tab2boxAssociates boxes with tabs.
tabsheet.boxsheet.box2metadataConfigures metadata boxes and the fields they display.
METADATA,BITSTREAM, orMETADATAGROUP).BITSTREAMfields only, filters bitstreams by metadata value.BITSTREAMfields only, filters by bundle. Since versions 2023.02.08, 2024.02.02, and 2025.01.00, two bundles can be specified using<VIEW_BUNDLE>.<DOWNLOAD_BUNDLE>(for exampleORIGINAL.BRANDED_PREVIEW).yorn. Wheny, the label is displayed above the value.yorn. Wheny, multiple values are shown inline; otherwise each value appears on a separate line.metadatagroupsDefines nested metadata rendered as grouped fields.
box2metadatawithFieldType = METADATAGROUP.METADATA.BITSTREAMfields only, filters bitstreams by metadata value.BITSTREAMfields only, bundle filter. Supports<VIEW_BUNDLE>.<DOWNLOAD_BUNDLE>syntax.tabpolicyandboxpolicyProvide additional configuration for tabs and boxes using CUSTOM DATA security.
cris.policy.group) containing the users or groups allowed to access the tab or box.utilsdataThis sheet is not processed by the tool.
It exists only as a reference to help populate the configuration workbook.
tab_i18n,box_i18n,metadata_i18n,metadatagroup_i18nContain i18n translations.
See the i18n conventions section for details.
Configuration Loading Process
The tool performs the following operations in order, stopping immediately if an error occurs:
Instructions for Reviewers
To import the layout you can ran the following script:
./dspace dynamic-layout-tool -f ../etc/conftool/dynamic-layout-configuration.xls
or from the process page in the UI you can select the dynamic-layout-import script.
To test the functionality you can try and start by configuring one of the entity type available in DSpace and check that the dynamic layout work properly.
A basic layout of example can be found in the rest codebase under the name dynamic-layout-configuration.xls or attached to this PR.
dynamic-layout-configuration.xls
The i18n tabs in the excel are come with a function to generate labels based on a prefix, to do so you just need to drag the AUTOGENERATED I18N keys columns.
The labels can then be copied over to the json file in the UI project in case translations or customizations are needed.
List of changes in this PR:
Added new resolver to check whether tabs are available and dynamic layout can be loaded.
Added new decorators and static map for handling and parsing of tabs, boxes and rendering types.
Ported components for rendering types visualization.
Implemented layout matrix and loader components.
Ported UI configurations for layout elements customization.
Ported different boxes components.
Checklist
This checklist provides a reminder of what we are going to look for when reviewing your PR. You do not need to complete this checklist prior creating your PR (draft PRs are always welcome).
However, reviewers may request that you complete any actions in this list if you have not done so. If you are unsure about an item in the checklist, don't hesitate to ask. We're here to help!
mainbranch of code (unless it is a backport or is fixing an issue specific to an older branch).npm run lintnpm run check-circ-deps)package.json), I've made sure their licenses align with the DSpace BSD License based on the Licensing of Contributions documentation.