= Sub-templates =

|| '''Date''' || 2011/05/25 ||
|| '''Contact(s)''' || Francois, Simon ||
|| '''Last edited''' || ||
|| '''Status''' || draft ||
|| '''Assigned to release''' || 2.7.0 ||
|| '''Resources''' || Available ||
|| '''Ticket''' || #538 ||

== Overview ==

This proposal aims to provide the capability to handle sub-templates. Sub-templates are XML fragments of metadata records. A set of fragments compose a directory (ie. contact directory, extent directory).

Sub-templates are designed to be inserted into existing metadata records using two modes:
 * copy/paste mode which insert once the fragment.
 * permanent link mode which insert an XLink to the fragment.

The copy/pase mode allows user to add a fragment which could be modified after insertion. This mode provides default values or editing instructions which could be helpful to fill in the appropriate values (eg. a default quality report). It extends the suggestion mechanism which only expand element and does not provide sample values. It allows also to add a fragment with real value and change them.

The XLink mode create a dynamic link between the metadata record and the fragment. Editor can't edit such a fragment from the editor. The sub-template manager should be used and the cache of XLinks cleared from the administration panel.


[[Image(sub-template-using-xlinks-disabled.png)]]



=== Example ===


For example, a sub-template for a contact in ISO19139 standard is: 
{{{
	<gmd:CI_ResponsibleParty xmlns:gmd="http://www.isotc211.org/2005/gmd" xmlns:gco="http://www.isotc211.org/2005/gco" >
		<gmd:individualName>
			<gco:CharacterString>Individual name</gco:CharacterString>
		</gmd:individualName>
		<gmd:organisationName>
			<gco:CharacterString>Name of the responsible organization</gco:CharacterString>
		</gmd:organisationName>
		<gmd:positionName>
			<gco:CharacterString>Function performed by the responsible party</gco:CharacterString>
		</gmd:positionName>
		<gmd:role>
			<gmd:CI_RoleCode codeList="./resources/codeList.xml#CI_RoleCode" codeListValue="pointOfContact"/>
		</gmd:role>
	</gmd:CI_ResponsibleParty>
}}}




=== Proposal Type ===
 * '''Type''': Metadata
 * '''App''': !GeoNetwork
 * '''Module''': Admin, Editor 

=== Links ===
 * '''Documents''':
 * '''Email discussions''':
 * '''Other wiki discussions''':

=== Voting History ===
 * Vote proposed by Francois on 23 June 2011 , result was +1 Patrizia, Jeroen, Simon, Emanuele, Francois

----

== Proposal == 

=== Sub-template definition ===
Sub-templates are:
 * XML document
 * Based on an element which is a complexType of a schema (eg. gmd:CI_ResponsibleParty)
 * stored in the Metadata table with 
  * value 's' for the template column (reminder: 'y' is for template, 'n' is for metadata)
  * root element is stored in the root column. It allows us to know the type of sub-templates. This information is used to define where this element could be inserted.
  * schema is defined like metadata or template documents (only iso19139 supported for now)
 * indexed using Lucene 
  * field _isTemplate='s'
  * field _root= root column
  * full text indexing for search
 * imported through the metadata record import administration or the directory manager page (TODO)
 * similar to metadata document for privileges management


=== User interface ===

In the user interface, sub-templates are accessible through:
 * a directory manager in the administration
 * a popup selection mechanism in the metadata editor (like CRS, Thesaurus)


==== Manage sub-templates in the directory manager ====

The directory manager is accessible to all editors. It is composed of 2 parts:
 * a search form to find sub-templates
 * an editor to edit sub-templates


The search form is composed of:
 * a list of type of directory (eg. contact, extent, keywords)
 * a full text criteria for search

Sub-templates found are displayed in a grid where editors could select one.
Once selected, the current sub-template is open in the editor. Editors could click:
 * the duplicate button to create a copy
 * the delete button to delete it
 * the privileges button to set privileges.
 * the add button allows to add an entry from an XML fragment

Privileges allows to share sub-template across a group of users. Therefore, the sub-template
needs to be publicly available for all while used through XLink mode.

Sub-template could be edited in simple,advanced and XML mode.

[[Image(sub-template-manager.png)]]


==== Using sub-templates in the editor ====

From the editor, a new button is added to access the sub-template selector. The selector panel provides a similar interface like CRS or Thesaurus selector. Editors could:
 * search, 
 * drag-and-drop the elements to add to the record
 * select the mode (copy/paste or linked)
 * add

For some kind of sub-template, another option is available. In case of contact directory, editor could also select the role of the contact. This will override the role defined in the directory manager (a same contact could be a point of contact in a record and a distributor in another record).


[[Image(sub-template-selector.png)]]


=== Sub-template configuration ===

In config-gui.xml, a mapping define for each type of sub-template the list of element where this type could be use. This is used then in the XSL to display or not an extra button to open the sub-template selector.
{{{
  <editor-subtemplate>
    <mapping>
      <subtemplate type="gmd:CI_ResponsibleParty">
        <parent id="gmd:pointOfContact"/>
        <parent id="gmd:userContactInfo"/>
        <parent id="gmd:distributorContact"/>
        <parent id="gmd:citedResponsibleParty"/>
        <parent id="gmd:contact"/>
        <parent id="gmd:source"/>
        <parent id="gmd:processor"/>
        <parent id="gmd:responsibleParty"/>
      </subtemplate>
      <subtemplate type="gmd:EX_Extent">
        <parent id="gmd:extent"/>
      </subtemplate>
      <subtemplate type="gmd:MD_Keywords">
        <parent id="gmd:descriptiveKeywords"/>
      </subtemplate>
      <subtemplate type="gmd:DQ_FormatConsistency">
        <parent id="gmd:report"/>
      </subtemplate>
    </mapping>
  </editor-subtemplate>
}}}

In order to have some information when searching for sub-template, a brief mode has been added for sub-templates. 
This brief mode defines at least a title.
This is defined in schema present XSL. Example for contact :
{{{
<xsl:template mode="iso19139-subtemplate" match="gmd:CI_ResponsibleParty">
    <xsl:variable name="langId">
      <xsl:call-template name="getLangId">
        <xsl:with-param name="langGui" select="/root/gui/language"/>
        <xsl:with-param name="md" select="."/>
      </xsl:call-template>
    </xsl:variable>
    <title>
      <xsl:apply-templates mode="localised" select="gmd:organisationName">
        <xsl:with-param name="langId" select="$langId"></xsl:with-param>
      </xsl:apply-templates> - 
      <xsl:apply-templates mode="localised" select="gmd:individualName">
        <xsl:with-param name="langId" select="$langId"></xsl:with-param>
      </xsl:apply-templates>
    </title>
  </xsl:template>
}}}


=== Sub-template services ===

A new package is added : org.fao.geonet.services.subtemplate.

2 services are added:
 * "subtemplate.type" to return the list of available sub-templates available.
 * "subtemplate" to return a subtemplate
  * Sub template are all public - no privileges check. Parameter "uuid" is mandatory.
  * One or more "process" parameters could be added in order to alter the template extracted. This parameter is composed of one XPath expression pointing to a single {@link Element} or {@link Attribute} and a text value separated by "{@value #SEPARATOR}". For example, to return a contact template with a custom role use "&process=gmd:role/gmd:CI_RoleCode/@codeListValue~updatedRole".



  
=== Future improvements ===

Here is a list of tasks not adressed in that proposal which could be plan for later:

 * subtemplate does not support XLink (nested XLinks)
 * Capability to extract subtemplate from existing record (cf. ReusableObjectStrategy in geocat.ch)?
 * Multilingual subtemplate (How to activate multilingual metadata editing for a fragment ?)
 * When deleting a subtemplate, metadata may use it via XLink (need to check links)

=== Note ===
Sub-template is only available when using the JS widget interface.

=== Backwards Compatibility Issues ===
None.

=== New libraries added ===
None.


== Participants ==
 * Francois Prunayre
 * Simon Pigot