This page is a subpage of [[CMDI 1.2]]

= Extended display information = 

[[PageOutline(1-4)]]

== The issue ==

CMDI profiles provide the blueprint for a logical structuring of metadata instances. They provide very little information about ''how'' the information contained in the records should be presented (with the notable exception of the displayPriority attribute, which has not proven to be a very popular or well understood feature). It would be desirable to have some unified (and preferably extensible) way of providing (sets of) display cues related to but physically separate from the description of the logical structure - think of a model like (conceptually) CSS and XML, although the display information should probably go beyond styling (otherwise plain CSS might as well be used).

Display aspects that might be included:

* Grouping information 
 * Grouping of elements within components
 * Merging of components on one level
 * Merging of components contained within one other
* Salient element selection - an alternative/replacement for display priorities allowing the client to select one or  elements representing the component in which they are contained for summarised display (e.g. in a tree). Logic might be more sophisticated than a single priority number.
* Field status, see #139

== Proposed solution ==

A '''separate namespace''' is used for display cues (e.g. http://www.clarin.eu/cmdi/cues/display/1.0). In this namespace attributes are defined (in an independent XSD) for all kinds of display and interaction cues.

The general component specification allows any attributes from this namespace on all components, elements and attributes. To define a 'style' for a given component or profile, an '''XSLT''' stylesheet has to be created that '''augments''' the component specification with these cue attributes with the desired values (for an example, see below).

The component-to-schema XSLT picks up all cues and wraps them in app info blocks in the profile XSD. When requesting a profile from the Component Registry, it can be instructed to apply a style (or maybe multiple), e.g. by getting ''/registry/profiles/clarin.eu:cr1:p_1361876010587/xsd?style=my_style'' where ''my_style'' is an identifier that gets the style from some '''style registry'''.

[[Image(extended display info.png)]]

Notes:
* The style should probably inject the namespace definition and schema location into the component spec so that we can have independent versioning of styles
* Applications can choose which cues to support and which not, and will also likely support a specific version of the style 'language'
* Maybe we want to have several 'sub-namespaces' for different kinds of cues (e.g. editor cues, viewer cues, ...)
* If we would do it like this, there will be a demand for a style editor because modellers are not going to want to write XSLT's (and we probably don't want them to)
* The 'style registry' could be integrated with the Component Registry though.

The required '''infrastructure''' extensions can be developed at a later stage, but for CMDI 1.2 it is important to '''prepare the model''' for inclusion of display style attributes. This would be achieved by allowing any attribute from the display cues namespace on component, element and attribute specifications.

=== Pros ===

* A pure extension, it's optional for any tool to support this
* Multiple styles can be created for each component or profile
* Generic styles are possible (but probably of limited use)
* Instances can point a styled schema for a default visualisation or to the unstyled schema just as easily

=== Cons ===

* XSLT's cannot be constrained to only add style info (i.e. arbitrary transformations are possible)
* Cues may not always be applicable in every context, so tools will have to be tolerant and unexpected (side) effects cannot be prevent completely (as with CSS)

=== Centre impact ===

* Affected tools
 * Infrastructure
  * Component Registry
 * Editors
  * Arbil
  * ProForma
 * Viewers
  * VLO
  * ...
* Impact on instances

=== Implementation examples ===

Cues will be represented on the model level only (component specification -> XSD), not on the instance level

==== Implementation in general component schema ====
xs:anyAttribute can be used to allow display cues on component, element and attribute specifications:

{{{#!xml
   <!-- list of all attributes that can be bound to a cl_el -->
    <xs:attributeGroup name="clarin_element_attributes">
        <xs:attribute name="name" type="xs:Name" use="required">
            <xs:annotation>
                <xs:documentation>The name of the element.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        ...
        <xs:anyAttribute namespace="http://www.clarin.eu/cmdi/cues/display/1.0" processContents="strict"/>
    </xs:attributeGroup>

    <!-- list of all attributes that can be bound to a cl_comp -->
    <xs:attributeGroup name="clarin_component_attributes">
        <xs:attribute name="name" type="xs:Name"/>
         ...
        <xs:anyAttribute namespace="http://www.clarin.eu/cmdi/cues/display/1.0" processContents="strict"/>
    </xs:attributeGroup>
}}}
and similar for Attribute specifications

==== Implementation on component model level ====

Allowing any attribute in the cues namespace on components, elements and attributes (or maybe different namespaces).

A simple case:

{{{#!xml
    <CMD_Element name="Title" />
}}}
can be transformed to
{{{#!xml
    <CMD_Element name="Title" display:backgroundcolor="#"/>
}}}

Visual merging of (linked) child components (only effective if child component does not have repeating children):

{{{#!xml
    <CMD_Component name="ActorLanguage">
       <!-- link to ISO-639-3 component -->
       <CMD_Component  ComponentId="clarin.eu:cr1:c_1271859438110" CardinalityMin="1" CardinalityMax="1" display:mergewithparent="true" />
       <CMD_Element name="PrimaryLanguage" />
    </CMD_Component>
}}}

An alternative to the display priority attribute of CMDI 1.1:

{{{#!xml
    <CMD_Component name="Actor" display:displayvaluefield="Name,Role">
       <CMD_Element name="Name" />
       <CMD_Element name="Role" />
       <CMD_Element name="Age" />
    </CMD_Component>
}}}

the attributes can be inherited in the derived (via comp2schema) XSD, like the datcat attributes are, in the same display cues namespace.

==== Implementation on profile schema level ====

The display cue attributes can be inherited on the element and attributes definitions in the schema file, in the same as 'datcat' attributes. For example (based on the last component specification example above):

{{{#!xml
<xs:element name="Actor" minOccurs="1" maxOccurs="1" display:displayvaluefield="Name,Role">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="Name"
                display:backgroundcolor="#f00"
                minOccurs="1" maxOccurs="1">
                <xs:complexType>
                    <xs:simpleContent>
                      <xs:extension base="xs:string"/>
                    </xs:simpleContent>
                </xs:complexType>
            </xs:element>
}}}

== Tickets ==
{{{#!comment
Below replace the word 'keyword' in both the the text and the ticket query
}}}
Tickets in the CMDI 1.2 milestone with the keyword ''displayinformation'':
[[TicketQuery(keywords=~displayinformation,milestone=CMDI 1.2,format=table,col=summary|owner|component|priority|status)]]

== Discussion ==

Oddrun: I for one think it's a great idea to provide more display information! To the open questions:
* Where to store the information? NOT in the component/profile specification! One strong reason for this is that changes in display information should not be allowed to affect (complicate) the versioning of the profile. One idea could be to extend the CMDI metamodel with the class DisplayComponent, each instance of which specifying one display configuration of one specific component, and stored in a separate registry. A "display configuration" could be along the lines mentioned above (grouping of elements/profiles, salient elements/components)
[[Image(ClassDiagram2.png,300)]]
* Yes, multiple display configurations should be allowed per component/profile.
* Metadata modellers and tool developers should generate such display configurations. Metadata modelers at component-design-time (sort of "default display"). Tool developers could pick and choose from existing display configurations, and generate his own. At profile level, there will probably be a need to generate some kind of stylesheet based on the selected display configurations?

----

'''Twan''': An illustration of the need for display cues (taken from the WG e-mail discussion):

The grouping issue is the most predominant one, so good thing you're mentioning that. The essence of the issues lies in the fact that there are two factors determining the component hierarchy in a profile: purposeful nesting - to reflect some natural hierarchy or, more typically, to allow repetition of a set of elements or components - and nesting as a result of component reuse. Take for example the cmdi-actor component:

''Actor''
* Role
* Name
* ...
* ''!BirthCountry (0:1)''
 * ''iso-country (1:1)''
  * Code
* ''cmdi-actorlanguages (0:1)''
 * description
 * ''cmdi-actorlanguage (1:*)''
  * ...
  * ''cmdi-language (1:1)''
   * !LanguageName
   * ''iso-language-639-3 (1:1)''

I think this component shows some reasonably good examples of component reuse. However the resulting hierarchy is a nightmare if you were to represent an instance of it it in a tree based view with tables per component (like in Arbil). What you would like to have is something like

''Actor''
* Role
* Name
* !BirthCountry.iso-country.Code
* ''cmdi-actorlanguages''
 * description
 * ''cmdi-actorlanguage.cmdi-language'' (repeated)
  * !LanguageName
  * iso-language-639-3.iso-639-3-code

Where the tree is condensed, basically leaving out the levels that are an artifact of component reuse. Arbil is currently trying to achieve that by flattening all 0:1 and 1:1 branches in the tree. But then we got complaints about Arbil not representing the hierarchy of the components as modelled! So I think (unfortunately) there is no generic solution to this problem apart from providing a way of augmenting individual components with instructions like 'join children from here' for the editor or viewer. As far as I can tell this can only work top-down, but that should be powerful enough. 

----

Discuss the topic in general below this point