smartEditor Developer Documentation

Steps to add new form fields to an existing form tab

1. Tiles and forms
   1. Create a new JSP file based on an existing "similar" form field, i.e. same multiplicity (one, or many) and similar number of fields (to re-use the same styling/form layout.
      For a simple text form field "smlAcousticSensorLength" create a new smlAcousticSensorLength.jsp in webapp/Web-INF/jsp/elements:

<table class="verticalTop">
 <tr>
 <td><label for="smlAcousticSensorLength" id="smlAcousticSensorLength"
 class="firstLabel width190 tooltip"> <fmt:message
 key="element.smlAcousticSensorLength.label" />
 </label></td>
 <td><form:input htmlEscape="true"
 path="storage['smlAcousticSensorLength'].length" size="100"
 id="smlAcousticSensorLength" /> <form:errors
 path="storage['smlAcousticSensorLength'].length"
 cssClass="ui-state-error-text" /></td>
 </tr>
</table>

• • • Add required language labels in message(_de).properties in main/resources

element.smlAcousticSensorLength.label=Länge
element.smlAcousticSensorWeight.label=Gewicht
element.smlAcousticSensorHeight.label=Höhe

and

element.smlAcousticSensorLength.label=Length
element.smlAcousticSensorWeight.label=Weight
element.smlAcousticSensorHeight.label=Height

• • • If you have multiple possible elements, then make sure that the configuration of AjaxEventDecoration in the JSP file is correctly updated, see LinkHere.
  1. Add the element into the layout in tiles-editor.xml in webapp/Web-INF/defs/.
     • Make the new definition available by adding it ( put-attribute) to the definition of editor.body. For a simple text form field "smlAcousticSensorLength" for example:

<definition name="editor.body" template="/WEB-INF/jsp/body.jsp"
 preparer="de.conterra.smarteditor.tiles.BodyViewPreparer">
 <put-attribute name="smlAcousticSensorLength"
        value="/WEB-INF/jsp/elements/smlAcousticSensorLength.jsp" cascade="true" />	
</definition>

• • • The name is used in the body.jsp and body_.jsp pages in webapp/Web-INF/jsp/ to insert the new field.

<div id="tabs-1">
 <tiles:insertAttribute name="smlAcousticSensorLength" />
</div>

1. 1. If the Element has a Multiple...jsp File: Add the element into the layout in tiles-elements.xml.
      • Create a definition.
      • Make the new definition available by adding it ( put-attribute) to the definition of editor.body.
      • The name is used in the tiles-editor.xml
2. Transformation and beans
   1. Create new transformation scripts in the directory src/main/resources/xslt:
      • .._toISO.xslt for the transformation of internal beans to ISO document.
      • .._toBean.xslt for the transformation of ISO to internal beans.
      • See LinkHere for more information on the transformation scripts.
   2. Create and configure beans
      • Create a Groovy bean in src/main/resources/groovy.
        • The names of the fields in the bean must match the names of the storage[..].name used in the JSP.
        • The Groovy beans are transformed automatically to XML, which is the input $beanDoc that is read in the .._toISO transformation scripts.
        • Groovy beans can hold other groovy beans and lists (see for example DescriptiveKeywordBean.groovy)
        • The @XStreamAlias links the Groovy bean to the XSLT scripts.
        • The XML element names and other encoding/decoding configuration can be done with XStream annotations, see for example SecurityConstraintsBean.groovy.
      • Add a new definition in beans-definitions.xml in webapp/WEB-INF/ and add the links to the XSLT files and Groovy bean created above in the same fashion as the existing definitions. For a simple text form field "smlAcousticSensorLength" for example:

<lang:groovy id="smlAcousticSensorLength" script-source="classpath:groovy/SmlAcousticSensorLengthBean.groovy">
 <lang:property name="transformToISO" value="/xslt/SmlAcousticSensorLength_sml.xslt" />
 <lang:property name="transformToBean" value="/xslt/SmlAcousticSensorLength_bean.xslt" />
 </lang:groovy>

• • • Add an entry for the new definition in the backendBean in beans-definitions.xml.
      • The key of the entry must match the storage in the JSP, the value-ref is the name of the newly added bean definition. For a simple text form field "smlAcousticSensorLength" for example:

<bean id="backendBean" class="de.conterra.smarteditor.beans.BackendBean"
 scope="session">
 <aop:scoped-proxy />
 <property name="validatorId" value="smlValidator" />
 <property name="stickyErrorMessages" value="false" />
 <!-- default validator id -->
 <property name="storage">
 <map>
                              <entry key="smlAcousticSensorLength" value-ref="smlAcousticSensorLength" />
                 </map>
 </property>
</bean>

1. Double check: Search all the new files (JSP, XSLT) for occurrences of the name/identifier of your "template" to avoid bugs.
2. Optional
   • If the new form field is a "first level" element then create a tooltip entry. The filename of the tooltip must match the id of the field description's span element or the id of the HTML label element if there is no span.
   • If the new form field is mandatory, then add highlighting in the respective validator JavaScript, e.g. isoValidator.js, and adjust the validation schematron file in /src/main/resources/validation.
     • IMPORTANT: Depending on how your Schematron rules are defined (i.e. their context), you might have to add an empty element to the template so that the rule is fired.
   • If the new form field is mandatory and multi-valued, then you might want to have an empty tab open when you start a new document. To achieve this you must add an empty field (e.g. eventually containing ) into the templates in /src/main/resources/templates/, for both or either of dataset.xml and service.xml.
     • *IMPORTANT:* Check all functionality afterwards! Some of the =.._iso.xslt=-scripts have case differentiation if an element that they want to change already exists. To find these elements, check all source code occurrences of the element name that you added to the template.

How does the transformation to and from metadata documents work?

@XStreamAlias("SmlAcousticSensorLength")
class SmlAcousticSensorLengthBean extends BaseBean {

  @XStreamAlias("length")
  String length
}	

.._toISO.xslt

1. Removing existing elements of the type that the script will add later
2. Copying all non-touched elements from the XML (see the official schemas so that you're not misssing any!). It is good practice to keep the copying statements in the same order as the elements are in the XML schemas.
3. Adding the new information based on the XML that is passed via the $beanDoc transformation attribute.
   • The beanDoc is an XML encoding of the Groovy bean, starting either with the tag if the form element can be available multiple times, or with the XML alias of the Groovy bean, which is configured by the @XStreamAlias annotation.

<xsl:template
 match="/sml:SensorML/sml:member/sml:System/sml:characteristics/swe:DataRecord[@definition='urn:ogc:def:property:OGC:physicalProperties']/swe:field/swe:DataRecord/swe:field/swe:Quantity[@definition='urn:ogc:def:property:OGC:length']" />
 <xsl:template
 match="/sml:SensorML/sml:member/sml:System/sml:characteristics/swe:DataRecord[@definition='urn:ogc:def:property:OGC:physicalProperties']/swe:field/swe:DataRecord/swe:field[@name='length']" />
 <!-- parameter handed over by transformer -->
 <xsl:param name="beanDoc" />
 <xsl:template match="//sml:member/sml:System/sml:characteristics/swe:DataRecord[@definition='urn:ogc:def:property:OGC:physicalProperties']/swe:field/swe:DataRecord">
 <xsl:copy>
 <xsl:apply-templates select="swe:field" />
 <swe:field name="length">
 <swe:Quantity definition="urn:ogc:def:property:OGC:length"> 
                  <swe:uom code="mm"/> 
                  <swe:value><xsl:value-of select="$beanDoc/*/length" /></swe:value>
                </swe:Quantity> 
 </swe:field>
 </xsl:copy>
 </xsl:template>

.._toBean.xslt

<xsl:template match="/">
        <SmlAcousticSensorLength>
            <length>
                <xsl:value-of select="//sml:member/sml:System/sml:characteristics/swe:DataRecord[@definition='urn:ogc:def:property:OGC:physicalProperties']/swe:field/swe:DataRecord/swe:field/swe:Quantity[@definition='urn:ogc:def:property:OGC:length']/swe:value"/>
            </length>
        </SmlAcousticSensorLength>
    </xsl:template>

How can I use existing codelists?

How is the AjaxEventDecoration configured?

• elementId is the id of the =input=-element of the "+"-Button.
• elementName and elementIndex are the names of two hidden input fields defined in body.jsp that are used to hold the information which specific tab of the multi-element form is to be removed.
  • ? Or is this also used in the storage[..] statements and/or the id of the =div=-element holding the form section.
• fragments is the name of the tiles in editor.body.
• propertyPath is the name of the list of items use in storage, should be left to items.
• type is the name of the Groovy bean defining the internal structure.
• formId, "event", "method" should not be changed.

How is the hierachyLevel and serviceType set for the document?

How can I solve the error “Invalid property 'storage[]' of bean class [...]: Could not determine property type for auto-growing a default value

Browser message “This webpage has a redirect loop”, in conjunction with endless loop of “de.conterra.suite.edit.controller.EditController - Binding to new form” and “de.conterra.suite.edit.controller.EditController - Displaying new form”

• Re-check the beans-definitions.xml if there is an entry in the backendBean for the form that you are currently working and if all the identifiers are correct (no typos). Also check if the groovy bean name is correct! Check if the storage identifier used is correct and if the child elements of the storage match the names in the Groovy bean.
• Make a clean build, clear browser cache (cookies).
• Debug into Springs’s AbstractFormController.java to see if there are swallowed errors, start in the method showForm(..), then wait for an Exception to be thrown but never logged.

org.apache.tiles.template.NoSuchAttributeException: Attribute '…' not found.

• Clean build, clear browser cache, …
• Check if somewhere in the stacktrace is AjaxTilesBackendDecoratorView > Debug into it, or re-check the ajax JS in the (multi)element you’re working on…
• Debug in DispatcherServlet to find out more…

Metadata elements do not show up in a new form element after opening an existing document

• Re-check if the output of the _bean.xslt transformation script matches the names or aliases in the Groovy bean.
• Also, in the _bean.xslt scripts, check that xsl:value-of statements do not end in /text() (which might happen if you develop your patterns in an XSLT editor.
• Also, in the Groovy bean, check that the classname matches the filename, since there is no validation for that and the bean definition uses the filename.

Metadata elements do not show up in the output document

• Re-check if the XStreamAlias of the Groovy bean is correctly used in the _iso.xslt transformation. Check the XPaths used to read the beanDoc variable are correct.
• Also, in the Groovy bean, check that the classname matches the filename, since there is no validation for that and the bean definition uses the filename. Check the xstreamaliases of attributes as well if they match the attribute name in the storage in the jsp files.
• Save the metadata document to a local file. Then open the debug log. There you will see a repeated occurrence of logs starting with the "de.conterra.smarteditor.service.TemplatesCache - Trying to load XSL resource from URL" which tells you what the currently executed transformation is. Then the BeanTransformerService logs the input and output documents it tries to merge by running the XSLT script, namely the beanDoc in the log after "... XMLBeans documents was", and the created output document after the log "... Result document is".
  • If the problematic output is included, but it is missing from subsequent logs, then a copy statement might be lacking in subsequent XSLT scripts.
  • If the problematic output is not included but the input beanDoc is OK, recheck the matching of the base element in the _iso.xslt script: Is the element that you match against included? It might not be there in the used template, so you have to match higher up in the document and subsequently create the intermediate required parent elements, copy untouched elements, and then do your own transformation. An example of this can be seen in DistributorFormat_iso.xslt.

How to add a new metadata encoding

How can I add my own Schematron-based validation?

• Create a Schematron file
• Configure a bean in validator-definitions.xml, giving the validator a unique identifier and setting the resource path to the file with the Schematron rules
• Add the validator to the bean backendSetupService in service-definitions-xml. Here is also the best place to disable other validators.
• Add messages for the UI (shown in the "validation options"-dialog) in the messages_de.properites/ messages.properties file.
  • element.validation..label=
  • element.validation..message=
• Configure (if desired) your validator to be the default validator in the backendBean in beans-definitions.xml as <property name="validatorId" value=""/>
• Add new xxxValidator.js in folder Webapp/js/validation