Exposing New Fields in the Interface

Exposing New Fields

In the current version of CED2AR, the fields that are available for viewing and editing are hardcoded into the service layer and the frontend. In order to expose new fields, simple edits must be made to a few files.

---

Editing the Service Layer

In both of the service layer files to be edited, you must add the field you want to expose to a list of "Valid Fields", which requires the name of the field, xpath, type (single attribute, plural element, etc.), and display name.

First edit the controller for the editing interface located at Source/src/main/java/edu/ncrn/cornell/ced2ar/ei/controllers/EditCodebooks.java. Depending on whether the desired field is to be exposed under a variable, a title page, or a variable group, find the corresponding method (getXFields()) at the top of the file. The two most common will be getVarFields() and getTitleFields(). Inside this method, you must add your field to the list of valid fields by appending a new key-value pair to the validFields object.

private Map<String,String[]> getVarFields(String var, String index, String index2){
    validFields.put("labl", new String[] {"1","/codeBook/var[@name='"+var+"']/labl","Label","1"});

The above is code showing the label of a variable be added to the valid fields map. Let's look at the input.

• The key for this tuple is "labl". The key is generally just the name of the element or attribute, but for non-unique elements or attributes like "access", we often just concatenate the parent element with the non-unique child (for example "lablAcs" for the access of a label).
• The value of the tuple is a string array with a few elements. The first is the number denoting the type of field. This value is to decide how to display the field, as well as how to update the actual XML document. There are 5 options:
  • [1] single element
  • [2] single attribute
  • [3] plural element
  • [4] plural attribute
  • [5] access level
• Next is the xpath string, but with wildcards replaced with the input variables to the method; var, index, index2.
• Third is the display name of the element.
• Last is another flag, either 1 or 0, to denote whether or not HTML is allowed inside of the element, 0 being HTML, 1 being plaintext. HTML is only allowed in single elements at this point.

Next edit the file located at Source/src/main/java/edu/ncrn/cornell/ced2ar/eapi/rest/queries/EditCodebookData.java in a very similar manner. Find the correct method for the field you want to expose (editVar(...), editCover(...), etc.), then add a call to append the valid fields list similar to how it was done above:

validFields.put("labl", new String[] {"1","/var[@name='"+var+"']/labl","Label"});

The only difference is that there are only 3 elements in the string array rather than four; we don't use the HTML flag here.

---

###Editing the Frontend

Now two XSL files must be changed in order to expose these fields in the interface, both for regular display and for editing. This document assumes basic knowledge of XSL or ability to follow patterns present in the XSL code.

The first file will be located under the regular XSL directory at Source/src/main/webapp/xsl/. Most likely it will be either variable.xsl or codebook.xsl. Find the location in the document where you want your element displayed and insert code. Here is the example block for exposing the "Universe" field under a variable:

<xsl:if test="codeBook/var/universe != ''">
	<p>
	    <span class="staticHeader">Universe</span>
	</p>
	<div class="value2">
		<span itemprop="description">
			<xsl:copy-of select="codeBook/var/universe/node()" />
		</span>
	</div>
</xsl:if>

Generally, this XSL checks if the item is present in the XML it is parsing, then creates some HTML with a static header that you specify (should match the display name you put in the valid fields list) and then under that copies the value of the node specified by the xpath of your field. The exact code will vary field to field, but there should be ample examples in the file to get the display that you want.

Next, the XSL for the editing interface must be changed. This file will be located under the editing XSL directory at Source/src/main/webapp/xslEdit/. Most likely it will be either variableEdit.xsl or codebookEdit.xsl. Find the location in the document where you want your element displayed insert code. Below is the example block again for the "Universe" field:

<p class="lb2">
    <span class="staticHeader">Universe</span>
    <a title="Edit field" class="editIcon2">
	<xsl:choose>
		<xsl:when test="/codeBook/var/universe != ''">
			<xsl:attribute name="href"><xsl:value-of select="$varname" />/edit?f=universe</xsl:attribute>
			<i class="fa fa-pencil"></i>
		</xsl:when>
		<xsl:otherwise>
			<xsl:attribute name="href"><xsl:value-of select="$varname" />/edit?f=universe&amp;a=true</xsl:attribute>
			<i class="fa fa-plus"></i>
		</xsl:otherwise>
     </xsl:choose>
     </a>
     <xsl:copy-of select="cdr:schemaDoc('universe')" />	
</p>

This code is a bit more complex than that for displaying the field. In general, it checks whether your field already exists. If it does, then it displays the value with a pencil icon and a link to edit that field (make sure to put the f= parameter in both URLs equal to the field name you specified in the valid fields list). If the field doesn't exist, then it displays just a plus icon and sets the a= parameter to true (add = true).

This structure works for single elements and attributes but if you have plural elements or attributes, you always want to have the link to append another element. Below is an example of a plural element (using functions defined at the top of the XSL file for editing and adding) where each element is shown, each is editable, and you can always add more:

<p id="DocumentProducer" class="value4">
	Codebook prepared by:
	<xsl:for-each select="codeBook/docDscr/citation/prodStmt/producer">
		<xsl:copy-of select="cdr:field(current(),'multi','docProducer',position(),false())" />
	</xsl:for-each>
	<xsl:copy-of select="cdr:fieldAdd('docProducer','','Add producer',count(codeBook/docDscr/citation/prodStmt/producer)+1)" />
	<xsl:copy-of select="cdr:schemaDoc('producer')" />
</p>

NOTE: The 'multi' flag in the call to the cdr:field function is NOT an argument to indicate that this is a plural element. It is an argument to indicate that multiple attributes are edited within this single element. For regular plural elements leave that argument empty with ' '.

Here is a link to a commit which shows the necessary edits made to expose the 'Universe' field under a variable.