Component Registry, Browser and Editor Reference Manual
This document contains usage instructions for the CMDI Component Registry. For more information about metadata in CLARIN, see the page on CMDI.
Introduction
The Component Registry has the following features:
1) Register and store Components/Profiles
2) Enable a user to browse the registered Components/Profiles
3) Enable a user to edit and create Components/Profiles.
For more information on CMDI, visit http://www.clarin.eu/cmdi.
Component Registry
The start screen of the Component Registry application shows the Component Browser. From here you can also access the editing functionality of the application (Component Editor). The sections in this document describe both functionalities, starting with the Component Browser.
Component Browser
In the Component Browser (see Figure 1) there is a dropdown that allows you to choose between the two item types: 'Profiles' and 'Components', showing the name and icon of the currently selected type. Selecting one of them allows you to view either all the registered Profiles or Components in the table. Next to this dropdown, there is a the space dropdown, also showing the currently selected option with its name and icon. The available options in this menu that you can switch between are the Public space, the user's Private space and optionally one or more shared team spaces. The public space shows all published profiles/components by all users. The user space shows all profiles/components that are located in your own private workspace. If you are a member of one or more teams, the team spaces show the profiles/components that are visible to and editable by all members of these teams. The user and team space items are unpublished. Finally, there is a status filter dropdown that allows you to switch between types of status for which items are shown: development, production or deprecated. There is also an option to show items with any status in the selected space. If no explicit selection is made, the default status for the selected space is selected: production for the public space, and development for the private and team spaces. Regardless of the status filter selection, non-production items will be recognisable by means of their distinct styling in the table.
On the far right, there is a search input field. Here you can type a term to quickly filter out all non-matching items within the selected space.
If you select an item in the browser list, the panel below the list fills up with info about the selected Profile/Component. It allows for a default 'view' and an xml view. The default view is an interactive view where you can click open reference components to explore the full structure of a profile/component. The xml view shows the actual xml of a Profile/Component. The comments tab provides a place for discussion by allowing authenticated users to post a comment on a specific Profile/Component or to see what others have written.
When you click the item menu dropdown (▼) in the list or on the info pane you are given some options. You can download the Profile/Component as an xml representation or get the corresponding xsd of that xml representation. Other tools can use the downloaded xml or xsd, CLARIN supported tools will integrate with the registry automatically so you won’t have to download anything yourself. Arbil (see http://www.clarin.eu/cmdi) can for instance be used to edit metadata based on the xsd’s generated by the profiles.
On the top left, there are three buttons: 'Create new', 'Edit (as new)' and 'Delete'. The first button brings you to the editor (see the section 'Component Editor') so that you can start creating a new profile/component in your private workspace. The second button will only be enabled if an item in the list is selected; then clicking the button will open the selected item in the editor, depending on the active space either as a copy (public space) or the item itself (in a private or team workspace). Both actions require you to authenticate if you’re not yet logged in. The final button allows you to delete the selected item, which is possible for unpublished items and published items in case you are the owner and the item has recently been published (less than one month ago). Notice that additional buttons appear in the private and team spaces. These are discussed later on in this document.
Figure 1: Browse Screen
Component Editor
The 'Component Editor' view (see Figure 2) allows you to create a new Profile/Component or edit an already existing Profile/Component. The view offers four buttons:
- 'Save': Submits the Profile/Component and overwrites an existing Profile/Component in the workspace it is in, or will create a new one if a previous version of it did not exist already
- 'Save as new': Always creates a new Profile/Component in a private or team workspace
- 'Publish': Submits your Profile/Component to the public space with production status, or alternatively with the development status if you choose the 'Publish as draft' sub-option
- 'Cancel': Returns to the Component Browser discarding any changes (you will need to confirm this if there are unsaved changes).
'Save' and 'Publish (as draft)' always trigger a validation for the edited Profile/Component. When successful, the 'Browse' view will show with the newly added item highlighted. If shown in the browse overview it means that the Profile/Component is registered. If the action was unsuccessful, an error message will be displayed and the Profile/Component is not registered. The created Profile/Component is validated against the xsd schema: https://infra.clarin.eu/CMDI/1.x/xsd/cmd-component.xsd.
A Profile or Component can be made public if:
- It is valid (e.g. all fields are filled in correctly)
- It contains already public components.
There are two sub-options when publishing a component or profile: the default 'Publish' option and 'Publish as draft'. The former assigns the production status to the the published item, which makes it immutable and visible to all users in the list of published production items. In contrast, if an item is published 'as draft', it keeps the development status. It then is visible to the public, but only in the list of development items and can still be edited by you. The item will be shown in the Component Browser with an indication of the fact that it is subject to change. After you have published an item as draft, you can set its status to production at any moment by using the 'Set status' button in the Component Browser.
Below the buttons the view is split in two parts: an editing pane with below it a component 'palette' (see Figure 3). The palette, which normally is minimised when editing but can be expanded at any time, can be used to add existing components to the item in the editing pane. Click '+Component' in the (sub)component where you would like to insert an existing component by reference and select 'Link existing component'. You can then select an already existing component from the list by clicking the '+' button. While the palette is showing, a placeholder will display the location where the item will be inserted. When inserting an existing component, a reference to that component is created and the component will be viewed in the browser and editor. The editing pane also has '+component', '+element', '+attribute' buttons that can be clicked to add new constituents to the pane: (inline) components, elements or attributes. Newly created constituents can then be edited within the pane. You can reorder the elements and components with the little up and down arrows to the right of the attribute, element or component's header.
Figure 2: Edit Screen
Figure 3: Existing components palette
The form sections for individual elements and components can be collapsed and expanded so as to hide or show specific sections using the ▶/▼ button next to each section. These actions will not affect the actual specification, but is only intended to ease navigation within the editor. Collapsed components and elements can still be moved or deleted, but their input fields will be hidden; instead all values will be displayed on a single line. Before the first element in the editor there are action links ('Expand all' / 'Collapse all') to show or hide details for all elements and components in the editor.
When new items are added it should be fairly straightforward to fill in the fields. The fields that need to be filled in depend on the type of item (see Figure 4). Some of the fields that occur in one or more of the types are covered in detail in the following subsections.
Figure 4: Element and attribute editing
ConceptLink
A conceptlink can be added by clicking on the button next to the field this pops-up a search box (see Figure 5) to search for concepts in the Isocat concept registry. Select one and press ‘Ok’ to use the selected concept for the field.
Figure 5: Isocat Search popup
Documentation
For every component, element and attribute at one or more 'Documentation' fields are shown. It is possible to provide multilingual documentation. To do this, you can specifiy the content language (the language in which the documentation entry is written) of one or more fields by selecting the button on the left hand side of the input field. A speech balloon is shown if no language is specified, otherwise the selected language code is shown. It is recommended to select the content language from the list in the dialogue that appears upon pressing this button, but it is also possible to enter a language code manually.
It is possible to add additional documentation fields by pressing the 'Add documentation' link, but this is only valid as long as the documentation fields within one constituent have distinct content languages. Only one of these fields can have no content language specified (speech balloon shown instead of language code). All but the first documentation entry can be removed by clicking the 'trash can' icon next to the field.
Display Priority
The 'display priority' is a number that is used in determining the display value for the containing component in clients and viewers. They will use the value of the field with the highest display priority that has an actual value (e.g. for an Actor component this could be the Name field).
By default, the display priority will be set to 0 for fields, which indicates that the concerning field is not taken into account when determining the display value. However, at least one field should have a positive number larger than 0. Among the fields that have a value above 0, lower numbers indicate higher priority.
Type
The 'type' field can be edited by clicking the 'Edit' button next to it. This pops-up a window (see Figure 6a) forcing you to choose between three different types by selecting a tab: Type (primitive type), Controlled Vocabulary or Pattern. Type refers to primitive types and is used when the type of the field must be for example type 'string' or "boolean". You can also create a vocabulary of allowed values for this particular field. The creation and editing of vocabularies is described in detail below. Finally, you can also choose Pattern to specify a regular expression to allow only values that match the pattern[1].
Figure 6a. "Edit and choose type" popup
Controlled vocabularies
There are two types of vocabularies that you can use as a type for elements or attributes: open and closed vocabularies. Open vocabularies do not restrict the set of values that can be provided in a profile instance (metadata record), but they do offer the possibility of linking a field to an external vocabulary so that tools can offer values from this vocabulary as preferred or suggested value candidates. In addition the instance can reference a value from the vocabulary by means of its identifier, which leads to a strong semantic link while supporting value variations, for example across languages or spelling variations. Closed vocabularies can optionally reference external vocabularies as well, but always provide a closed set of allowed values. Providing an instance value that does not appear in this set will lead to invalidity of the record.
Figure 6b: Vocabulary editor
A closed vocabulary can be specified by selecting 'Closed' as vocabulary type (see Figure 6c) and adding one or more values in the table that appears below the vocabulary type dropdown. To start entering values or adding an additional value, press the 'Add an item' link. A concept link can optionally be provided for each item in the vocabulary. As soon as one or more values are present, the batch editing mode can be used to edit the table as a list of comma-separated values (CSV), optionally using an external editor via copy/paste if preferred. More information about using CSV to edit a closed vocabulary can be found in the embedded help function of the batch editor.
Figure 6c: closed vocabulary editor
An external vocabulary can be linked to a closed vocabulary by using the form below the values table. Use the 'Search' button of the external vocabulary section of the vocabulary dialogue and select a vocabulary from the table that is retrieved dynamically from CLAVAS. Setting this implies that the values in this vocabulary are legal values for the current vocabulary but this is not enforced. To synchronise the closed vocabulary with the external vocabulary, use the action 'Import/update from the selected external vocabulary' that appears as a link below the values table as soon as an external vocabulary has been set. In the dialogue that appears (see Figure 6d) you can optionally override the settings that determine the values that will be materialised into the vocabulary. Press '(Re)load vocabulary' and verify the correct retrieval using the 'Show preview' option. If the values, and descriptions are as desired, press 'Import loaded items' to complete the import. After a successful import, all vocabulary items can be edited freely in the values table and/or batch editor.
Figure 6d: importing an external vocabulary
Open vocabularies can be specified by selecting 'Open' as vocabulary type (see Figure 6e) and selecting an external vocabulary. In contrast to closed vocabularies, linking an external vocabulary is mandatory for open vocabularies.
Figure 6e: open vocabulary editor
Multilingual (Checkbox)
Elements (but not attributes) can be specified as being multilingual by checking the checbox with this label within the element definition. Enabling this option forces the maximum cardinality of the element to 'unbounded'.
Automatic Value Expressions
Expanding the 'Additional element options' of an element or attribute definition reveals the option to define 'automatic value expressions' for that constituent. Any number of such expressions can be added. There is no predefined syntax for automatic value expressions but individual tools can provide support for sets of expressions that allow for the automatic derivation, calculation or retrieval of values. Consult the documentation of the tools you are using to generate metadata to find out what expressions it supports.
Collaborating on Components and Pofiles
The administrators of the Component Registry can create teams in which users can work together on components and profiles before publishing them while using their own individual accounts. If you would like to have a team created or want to become a member of an existing team, please send a request to the administrators of the Component Registry through the following e-mail address: cmdi [at] clarin.eu (cmdi[at]clarin[dot]eu). Please include your user id, which can be found by logging into the Component Registry, then clicking the ‘settings’ link in the top right. The title of the settings page will show your user id (‘User settings for ….’).
Figure 7a: Switching to a team space
To start using the teams, switch to the team space that you would like to work in by selecting it from the work space drop down list in the browser (see Figure 7a). You will then see the components and profiles (in separate tabs, as is the case in the public and private spaces) that are available in that team. You can select any of these and view their contents or start editing by pressing the ‘Edit’ button. Any changes you make will become available to other team members immediately. Any team member can also publish or delete components and profiles that belong to the team.
Figure 7b: Moving a component to a team space
To add new components or profiles to a team space, first create them in your private workspace. Then, from the browser, you can move them to any team that you are a member of by selecting one or more components and choosing the target team from the ‘Move to team…’ drop down box. Then, click ‘Move to team’ and select the target team (see Figure 7b). Notice that components cannot be moved back to your private workspace once they have been moved into a team space!
User teams are still (as of version 2.2) an experimental feature and there are several known issues! See towards the end of the document for details.
Other Features
Deprecating Items and Setting a Successor
Figure 8: changing the status of an item
Any item with development or production status can be assigned the deprecated status by its owner. To do this, select the component or profile you wish to deprecate in the Component Browser and select 'Deprecated' from the 'Status' dropdown (see Figure 8). The Component Registry will then check whether you have the rights to change the status of the selected items, and if so will ask you to confirm the action. After the status has been updated you will be offered the option to set a successor for the deprecated item immediately. You can choose to do this at a later point as well. To do so for a deprecated item that has no successor specified yet, select the item in the Component Browser and press the 'Set successor' button. Whether doing this immediately after deprecation or at a later stage, a new dialogue will show up (an example is shown in Figure 9) that allows you to select any item of the same type (component or profile) that has the production status as a successor; items that are already deprecated or still have the development status cannot be used as successors. You can review the properties of a candidate after selecting it before pressing Ok to verify that the selected item is indeed the intended successor. Any public production item can be marked as the successor of any number of deprecated items of the same type.
Figure 9: setting a successor
Deprecated components or profiles are not shown in the default listing of published or unpublished items. Deprecated items that have been published (before deprecation) can be viewed by setting the status filter of the Component Browser to deprecated. Deprecated items are clearly marked as such in the browser and the viewer. If a deprecated component is used in another item, the Component Editor provides an easy option to replace it with its successor provided that a successor has been assigned.
Creating a Reference Link
It is possible to create a reference link (bookmark) to a public component or profile that starts up the Component Registry with the browse view and the given component or profile selected. This is done with the URL:
https://catalog.clarin.eu/ds/ComponentRegistry/?item=<id>
For example to open the Registry on component with id clarin.eu:cr1:c_1271859438180, the url becomes: https://catalog.clarin.eu/ds/ComponentRegistry/?item=clarin.eu:cr1:c_12…
The id of a component can be seen in the xml of the browse view. The link can also be obtained by selecting a component or profile in the component browser, opening its item drop down menu, and selecting the option ‘Show info’. A pop-up will appear (see Figure 10) that has a button to copy the reference link to the clipboard.
Using an Unpublished Profile Outside the Component Registry for Testing
A schema (XSD) representation of both published and unpublished profiles can be obtained following the same procedure. Open the item drop down menu of a profile, choose ‘Show info’ and copy the ‘Link to xsd’ to the clipboard using the button. This link is particularly useful for testing unpublished profiles in a metadata editor. In the metadata editor Arbil, the ‘profiles and templates’ dialogue has an option to add profiles by means of their schema location. There you can paste the XSD link to use the profile without publishing it first. Notice that you have the option to select a link for either the CMDI 1.1 or CMDI 1.2 version of the profile. Consult the documentation of your software to find out which version of CMDI is supported. If both are supported, CMDI 1.2 is preferable as certain features are not available in CMDI 1.1. More information about this can be found at www.clarin.eu/cmdi1.2.
Figure 10. The 'Show info' pop-up dialogue
Getting an RSS Feed for Components, Profiles or Comments
To automatically receive updates on the list of components or profiles or on comments on a specific profile or component, you can use the RSS feeds that are available for these collections. Click the RSS icon (see Figure 11) on the Component Browser or in the ‘Comments’ tab for a component or profile to be redirected to the URL of the RSS feed.
Figure 11. Getting the RSS feed for components, profiles or comments
Known Issues
- There currently is no way of logging out of the Component Registry other than ending the browser session
-
User teams: there is no locking so be careful not to edit components or profiles simultaneously
[1] The regular expression should conform to the standard used for XSD, which differs slightly from e.g. Perl and UNIX variants. For details, see http://www.w3.org/TR/xmlschema-2/#regexs