Add new functional metadata structureTreeTitle for labels in metadata editor structure tree

[solth]

Discussed in #4925

^{Originally posted by solth December 27, 2021}
#4757 added a switch that allows the user to change the label of the tree nodes in the structure tree from type to specific metadata values configured as metsEditor.titleMetadata in the central config file kitodo_config.properties.

However, the menu currently displays the id of metadata defined in the ruleset (or rather just the values separated by comma after metsEditor.titleMetadata from the config file), which is not optimal, since normally the label of a metadata is used in the Kitodo metadata editor UI and the user is probably not familiar with the internal IDs of the metadata as defined in the ruleset.

...

A new functional metadata structureTreeTitle should be added which replaces the old kitodo_config.properties property key metsEditor.titleMetadata.

Currently, only one of the metadata keys defined in metsEditor.titleMetadata can be applied at a time. So if a book and its chapters each have individual titles (like "main title" and "chapter title") these titles cannot be displayed at the same time. (an awkward work-around would be to assign the same title metadata to the top level element as well as the structure element, but this is probably not correct content wise, since a chapter should contain a "chapter title" instead of a "main title")

The new menu in the structure tree should then not contain the names of individual metadata keys anymore, but rather just general options like:

• Type
• Title
• Type - Title

When selecting the second (Title) or third option (Type - Title), all functional metadata of type structureTreeTitle will be retrieved from all elements in the structure tree (except pages/media) so that different metadata with the same use can be displayed at the same time. If one structure element contains multiple functional metadata of type structureTreeTitle, the first is applied.

Optionally, the count of structure elements can be offered as an additional option (thanks to @matthias-ronge for this suggestions):

• Type - Count
• Count

[thomaslow]

Optionally, the count of structure elements can be offered as an additional option (thanks to @matthias-ronge for this suggestions):

* `Type - Count`

* `Count`

May I ask, what exactly do you mean by count? The number of ancestor children / descendant nodes in the tree? Does this include both folders and pages, or pages only? How does this relate to the setting Show assigned pages which already adds similar information to each folder (listing both first and last page), see below:

[thomaslow]

If one structure element contains multiple functional metadata of type structureTreeTitle, the first is applied.

My concern is, that this implicit priority is going to become a problem in some special scenarios. For example, let's assume there is a TitleDocMain metadata key, which is the de-facto default for all available divisions (maybe for legacy reasons). And then, there are division-specific metadata keys aaaTitle and zzzTitle. The ruleset may look like this:

<ruleset xmlns="http://names.kitodo.org/ruleset/v2" lang="en">
    <declaration>
        <key id="aaaTtitle" use="structureTreeTitle">
            <label>aaa title</label>
            <label lang="de">aaa Titel</label>
        </key>
        ...
        <key id="TitleDocMain" use="structureTreeTitle">
            <label>main title</label>
            <label lang="de">Haupttitel</label>
        </key>
        ...
        <key id="zzzTitle" use="structureTreeTitle">
            <label>zzz title</label>
            <label lang="de">ZZZ Titel</label>
        </key>
    </declaration>
</ruleset>

Because of the implicit priority based on the declaration order, if a structure node has a aaaTitle it is preferred over the default TitleDocMain (if both metadata values are available, of course). However, if a structure node has a zzzTitlte it is not preferred over the default TitleDocMain. This might be confusing to users who have no idea that this implicit priority exists?

Maybe it is not a problem after all. What do you think?

[solth]

May I ask, what exactly do you mean by count?

That is a good question. To be honest, I only considered the variation Type - Count which would make sense for long lists of identical structures if Count was interpreted as Counter:

Monograph
- Chapter - 1
- Chapter - 2
- Chapter - 3
...

Just count without the structure element type might be kind of pointless. Perhaps @matthias-ronge could weigh in on this since the idea originally came from him?

[henning-gerhardt]

A few comments:

• the ruleset.xsd file must be extended for this new attribute value (already mentioned in the pull request). Maybe the discussions Ruleset validator #6168 and Umgang ruleset.xsd #6008 should be more discussed and maybe somehow implemented so only a change on the ruleset.xsd is needed to add new valid values or other changes.
• on release it is necessary to inform the users that this value is moved from the global configuration file kitodo_config.properties to every used ruleset file.
• the existing rule set files in the repository should be extended to use the new attribute on the right places so users have some examples how to use

[solth]

My concern is, that this implicit priority is going to become a problem in some special scenarios. For example, let's assume there is a TitleDocMain metadata key, which is the de-facto default for all available divisions (maybe for legacy reasons). And then, there are division-specific metadata keys aaaTitle and zzzTitle. The ruleset may look like this:

<ruleset xmlns="http://names.kitodo.org/ruleset/v2" lang="en">
    <declaration>
        <key id="aaaTtitle" use="structureTreeTitle">
            <label>aaa title</label>
            <label lang="de">aaa Titel</label>
        </key>
        ...
        <key id="TitleDocMain" use="structureTreeTitle">
            <label>main title</label>
            <label lang="de">Haupttitel</label>
        </key>
        ...
        <key id="zzzTitle" use="structureTreeTitle">
            <label>zzz title</label>
            <label lang="de">ZZZ Titel</label>
        </key>
    </declaration>
</ruleset>

Because of the implicit priority based on the declaration order, if a structure node has a aaaTitle it is preferred over the default TitleDocMain (if both metadata values are available, of course). However, if a structure node has a zzzTitlte it is not preferred over the default TitleDocMain. This might be confusing to users who have no idea that this implicit priority exists?

Maybe it is not a problem after all. What do you think?

I think this is less an issue of this specific use case and more a general problem concerning how rulesets are validated at the moment. Ideally it shouldn't be possible to define more than one functional metadata of each type for each defined division. Functional metadata like recordIdentifier or higherLevelIdentifier can be especially critical if configured multiple times for one division.

As far as I know that is the reason why RulesetManagementInterface only contains a method definition getFunctionalKeys(FunctionalMetadata functionalMetadata) (plural!) and no corresponding getFunctionalKey(FunctionalMetadata functionalMetadata) (singular), even though the later would be preferable.

Because of that there are already several other places in the code like the one you described above, where a collection of functional metadata is retrieved, but only one (random) element of that collection is actually used.

I am afraid until we find a way to impose restrictions like unique functional metadata of specific types for individual structure in rulesets the administrator or author of that ruleset will be responsible for configuring it correclty.

[BartChris]

What does not work in the current config-file based approach is to define the LABEL of the division as to be displayable as the text of the structure tree node. One can enter LABEL as value in the configuration, but it does not work (when selecting LABEL, nothing is displayed, although there is a LABEL)

So my preferred solution would be, that when selecting one of

• Title
• Type - Title

to first display the content of the LABEL as Title, and only if this is not set, rely on the configured key (structureTreeTitle) in the ruleset. This would also align the display during the workflow more closely with presentation systems like DFG viewer, which present the division's LABEL in the document's outline.

Institutions right now use the export XSLT to derive the LABEL e.g. from the TitleDocMain during export. (see: #5016 (comment)) because the LABELS are very important for presentation. Applying a similar Logic inside of Kitodo by: a) constructing the display label from another metadatum or b) if it is already present taking it directly from the divsion's LABEL would bring the editor behaviour a little bit inline with the desired structure for the presentation.

@kitodo/kitodo-community-board Do you agree?

[BartChris]

We probably also have to specify if the desired change also has an effect on the display of parent processes in the editor. The linked children have a "display label", which is constructed slightly different than the one of "normal" processes' divisions:

#4925 (reply in thread)

I just optimized the display of linked child processes. Their displayed "name" always contains the type of the linked division:
#6185

I would really like to explore whether we can display more information (e.g., the volume number for 200 linked volumes) on linked child processes. However, implementing this might be more complex than it is for non-parent processes.

[thomaslow]

@BartChris By LABEL you mean the METS xml attribute of a division, right? Is this something that can be specified using the metadata editor at the moment?

[BartChris]

@thomaslow Yes, i mean the METS xml attribute of the division. And yes, you can list LABEL as a allowed key in any division:

<permit key="LABEL" minOccurs="1" maxOccurs="1"/>

In the key declaration we assign it a domain of mets:div which declares this metadatum as one which appears in the LOGICAL structure of the METS file and not in the DMDSec.

<key id="LABEL" domain="mets:div" use="displaySummary">
  <label>Label</label>
  <label lang="de">Label</label>
</key>

In the metadata editor you can work with LABEL as if it is a "normal" metadatum, but it actually gets stored in the LOGICAL structure of your METS file.

The story of LABEL (and also ORDERLABEL), is unfortunately a quite complicated if you search the repo, but especially the LABEL is important for every presentation system (METS or IIIF based). So it would be good if we can increase the usability of Kitodo at that point.

[thomaslow]

What does not work in the current config-file based approach is to define the LABEL of the division as to be displayable as the text of the structure tree node. One can enter LABEL as value in the configuration, but it does not work (when selecting LABEL, nothing is displayed, although there is a LABEL)

I tested this. Yes, defining LABEL as structureTreeTitle (or previously in the config file) still does not have any effect, because the LABEL is not included in the metadata object. However, a few years ago the LABEL was loaded as a fallback in case no other metadata title is available. Unfortunately, a minor mistake in the code prevents the LABEL from being displayed as a fallback right now:

kitodo-production/Kitodo/src/main/java/org/kitodo/production/services/dataeditor/DataEditorService.java

Line 125 in bc0970f

return metadataTitle.orElse(" - ");

getTitleValue returns - if no metadata title is available which disables the fallback detection in

kitodo-production/Kitodo/src/main/java/org/kitodo/production/forms/dataeditor/DataEditorForm.java

Lines 949 to 955 in bc0970f

	title = DataEditorService.getTitleValue(logicalDivision, structurePanel.getTitleMetadata());
	if (StringUtils.isBlank(title)) {
	title = logicalDivision.getLabel();
	if (StringUtils.isBlank(title)) {
	title = " - ";
	}
	}

I fixed this in my pull request. The LABEL is now again shown as a fallback title. I updated the demo video in #6264.

We probably also have to specify if the desired change also has an effect on the display of parent processes in the editor. The linked children have a "display label", which is constructed slightly different than the one of "normal" processes' divisions

I did not change the way the label is generated for linked processes. Their label remains the same regardless of the current setting. I guess there would need to be a separate config option that defines how those labels are built, especially if additional information beyond the type and title are interesting.

[thomaslow]

@solth Regarding the count option. I like your suggestion to add a count for each structure type individually (e.g. Kapitel 1, Kapitel 2, Abschnitt 1, Abschnitt 2). However, the implementation is not trivial and has some disadvantages. We could implement the count either as:

1. stateful information - meaning the count is stored inside of the treenode elements. Unfortunately, this would make the drag & drop update code even more complex, because those counts would need to be updated, too.

2. stateless information - meaning the counts are calculated on every JSF render. However, this would mean that for every structure node the whole structure tree needs to be traversed. In total, this would be a calculation with quadratic costs (with respect to the number of nodes in the tree). Since the tree already loads quite slowly for large processes, I don't think it is a good idea to add this cost merely for a nice count label.

I will look into option 1 again when implementing the multi drag & drop of the structure tree.

[solth]

@thomaslow thanks for the explanation. I understand and think the "count" option was optional (ha!) from the beginning. The important options "Title", "Type" and "Title - Type" have been implemented so I see this issue as closed.