Skip to content

Adding new elements

Jump to bottom
Jo Cook edited this page Jun 17, 2021 · 1 revision

How to add new elements to osmp

Note that file paths in the following documentation are relative to iso19139.osmp/src/main/plugin/iso19139.osmp.

This folder, rather than the root of the repository, is the one that should be copied to the schema_plugins directory in GeoNetwork. See https://github.com/AstunTechnology/iso19139.osmp/blob/3.10.x/README.md for more detailed installation instructions.

Define in osmp.xsd

New elements need to be defined and documented in ./schema/extensions/osmp/osmp.xsd.

Define code-lists

Code-lists must be defined in ./loc/eng/codelists.xml as well as being enumerated in osmp.xsd above. see https://github.com/AstunTechnology/iso19139.osmp/blob/3.10.x/src/main/plugin/iso19139.osmp/loc/eng/codelists.xml#L2358 for an example.

Note that the enumeration in osmp.xsd is used for validation purposes, and the enumeration in codelists.xml is for display (so can differentiate between the stored value and a more friendly display label if required).

Provide translations

Strings for new elements must be translated in ./loc/eng/labels.xml. See https://github.com/AstunTechnology/iso19139.osmp/blob/3.10.x/src/main/plugin/iso19139.osmp/loc/eng/labels.xml#L3572.

Note the use of the context attribute where there may be multiple elements in the xml record with the same name. The context defines the parent element where this particular label should be used.

Define conditionality

Define mandatory or optional elements in osmp.xsd using the minOccurs and maxOccurs attributes. You can define an element block to be optional, but require the elements within it to be mandatory if present, with judicious use of these attributes.

To ensure your mandatory element is displayed with an asterisk in the editor, add <condition>mandatory</condition> to the element in labels.xml.

Display in the editor interface

The editor interface for a metadata profile is in ./layout/config-editor.xml, eg https://github.com/AstunTechnology/iso19139.osmp/blob/3.10.x/src/main/plugin/iso19139.osmp/layout/config-editor.xml

The main GeoNetwork guidance has a section on customising the editor interface at https://geonetwork-opensource.org/manuals/trunk/en/customizing-application/editor-ui/creating-custom-editor.html which includes sections on adding new elements or fields.

There are several approaches for adding new elements, depending on various factors, including but not limited to:

  • Whether the element should be shown in the default or simple editing view or just the advanced editing view
  • Whether it is a single element or a group (described in the documentation as a "field with fieldset")
  • Whether a simple entry box is needed or something more complicated such as a dropdown list or a picker (eg for contacts or keywords).
  • Whether missing elements in the metadata record should be shown as empty elements, or not included (defined in the documentation as "flat mode")

Define the entry type

Towards the top of config-editor.xml is the section <fields>. This is a list of the fields used in the editor and their default entry type. Additional elements should be defined in this list. As well as simple types for date, text and number there are some more complex types defined as angular directives, such as contact or keyword pickers. These are defined and documented in https://github.com/geonetwork/core-geonetwork/blob/3.10.x/schemas/config-editor.xsd.

Define a fieldset and/or table fields

If your additions comprise more than one element, define them in the <fieldsWithFieldset> section. If you wish to use a tabular display method (as is commonly used for Responsible Party), then additionally define a <table for="namespace:newelement"> in the <tableFields> section. This should take the form of a set of <header> and <row> columns (see the xml for examples).

Add to a view

Elements that only need to be shown in the advanced editing view do not strictly need to be defined in the <view/> configuration- they will appear automatically with a structure provided by the xsd.

Similarly, it's not always necessary to explicitly add new elements to the default view- you can shortcut adding single mandatory elements by defining them in your template.

See the documentation linked to above outlines the options for adding new elements to the default or simple editing view. This section of the editor configuration starts with the line <view name="default">.

See <section name="gmd:contentInfo"> for one example of how to add an additional group of elements (<osmp:featureTypes>), with a button for adding more than one.

Note that you can add guidance to elements by defining a <text ref=""> below it, where the ref is defined in ./loc/eng/strings.xml (see below). This can be conditional, so you can have different guidance for (eg) datasets and services. See https://github.com/AstunTechnology/iso19139.osmp/blob/3.10.x/src/main/plugin/iso19139.osmp/layout/config-editor.xml#L3355 for an example.

Codelists, Labels and Strings

These xml files are all found in ./loc/eng.

  • Codelists allow you to extend the standard codelists for ISO19139, to either change what's in controlled lists or to add new ones.
  • Labels allow you to specify the display text for an element, and also to define dropdown lists (helpers).
  • Strings are used for other "page furniture", such as the help text shown below elements in the editor.

Additional validation

You can add additional schematron files into the schematron folder. By default these will be treated as "required for validation". If they are optional, eg they report an error but are not required for validation then you can set this in Admin Console -> Metadata and Templates -> Validation.

Actually deploying and visualising changes

You will need to be able to see the log files, preferably in real-time, when deploying schema changes as errors may not always be visible in the user interface.

The recommended approach is either to run it locally using jetty (see https://geonetwork-opensource.org/manuals/trunk/eng/users/install-guide/installing-from-source-code.html#building-running) or locally in docker and then watching the log files.

  • If using jetty, then changes to the schemas can generally be propagated by running mvn process-resources from the web folder (where you are running jetty from).
  • If using docker, then you'll need to redeploy the container.

If you can't see your change, then the following might help:

  • In jetty, check that your changes have propagated to the web/src/main/webapp/WEB-INF/data/config/schema_plugins/iso19139.osmp folder. If they haven't then restart jetty.
  • In docker, use docker exec to open a bash prompt inside the running container and check 'usr/local/webapps/geonetwork/WEB-INF/data/config/schema_plugins/iso19139.osmp`
  • Engage debug mode in the browser by adding ?debug directly before the # in the URL (and reloading your page).
  • Force GeoNetwork to clear it's caches by going to Admin Console -> Tools and clicking all three blue buttons.
  • Check the log files and/or have a look in your browser's dev console to see if there are any errors.
Clone this wiki locally