Implementing Forms and Form Renderers in the Open Source Portfolio David McPherson, Chris Maurer Will Trillich, Janice Smith Materials by Sean Keesler

Objectives Understand the XML technology stack (XML, XSD, XSL) Understand the role of XSD and XSL in OSP forms Understand how to manipulate form schema in an XML IDE Be able to capture the stored XML from an OSP form Be able to change a form’s appearance through form schema and XSL renderers July th Sakai Conference - Boston, MA, U.S.A.

Form Design and Use

THE XML TECHNOLOGY STACK A little background… July th Sakai Conference - Boston, MA, U.S.A.4

XML A “Correct” XML document is a text file that is: Well formed Opening and closing tags that do not overlap Optionally validated against a set of rules DTD and XML Schema July th Sakai Conference - Boston, MA, U.S.A.5

Parts of a Form XML document File MetaData File ID and Display Name Created and modified dates Structured Data The form data for each field Schema information Instructions and validation rules CSS information for styling July th Sakai Conference - Boston, MA, U.S.A.6

Explore Form XML in Oxygen IDE You do it! Open “sampleFormXML.xml” Identify the parts of the XML document Identify what fields were filled out Identify the form instructions when this form was completed Use OxygenXML to identify the set of elements in the XML to get the “displayName” of this file July th Sakai Conference - Boston, MA, U.S.A.7

XPATH Expressions that are used by many technologies (including XSLT) to specify one or more parts of an XML document (a node set) that meet a set of conditions Can be an absolute path: /formView/formData/artifact/metaData/repo sitoryNode/created July th Sakai Conference - Boston, MA, U.S.A.8

XPATH July th Sakai Conference - Boston, MA, U.S.A.9 Can be an absolute path: /formView/formData/artifact/metaData/reposit oryNode/created … refers to: “ Thu Jul 02 17:03:00 UTC 2009 ”

XPATH Can be a relative PATH:../../displayName July th Sakai Conference - Boston, MA, U.S.A.10 …refers to “ Test Feedback ” if used from the “created” element

XPATH Can include conditions in “predicates” …refers to all “element” node sets that have their “name” attribute set to “value” July th Sakai Conference - Boston, MA, U.S.A.11

Finding an XPATH with OxygenXML July th Sakai Conference - Boston, MA, U.S.A.12 XPATH expressions can be generated and tested by using the XPATH functionality in Oxygen

XPATH You do it! Find the XPATH to the element of the formView XML Generate an XPATH expression that will refer to the “value” field in the form’s structured data Generate an XPATH expression that will refer to the last date the form data was modified July th Sakai Conference - Boston, MA, U.S.A.13

What is an XML Schema? An XML document Describes other XML data files Structure Data types Data validation rules Provides a means to “validate” another XML document 14

XSD Example Form requirements: 3 fields Evaluation – Numeric value from 0 – 3 “Short” Rich text field – 1200 characters max Rich text field – “no limit” July th Sakai Conference - Boston, MA, U.S.A.15

XSD Example One way to represent the “Value” field July th Sakai Conference - Boston, MA, U.S.A.16

XSD in OSP XSD describes “valid” data AND Provides information to form presentation tool about how to render the HTML form Uses “ospi” extensions Form field labels and descriptive text Use of rich text editor “Subform keys” July th Sakai Conference - Boston, MA, U.S.A.17

XSD in OSP Examples This XSD snippet: Evaluation July th Sakai Conference - Boston, MA, U.S.A.18 Produces this HTML form field:

Explore XSD in OSP You do it! Open “schemaEnumeratedTextValue.xsd” Identify the form elements and validation rules Change the “value” scale to include 5 values Reorder the fields so that the “value” field is last on the form Make the “value” a required field Add a new field that prompts user for an evaluation date of the type “xs:date” Create a new form with this new schema and see the results by “Previewing” the form. July th Sakai Conference - Boston, MA, U.S.A.19

Questions about: XML XSD XPATH July th Sakai Conference - Boston, MA, U.S.A.20

FORM RENDERING LOGIC

An XSL Primer An XML document can be “transformed” into a new XML document by a set of instructions written in XSLT (Extensible Stylesheet Language Transformation) Sakai includesXalanJ - an XSLT processor

A “passthrough” XSL file Instructs the XSL processor to send a copy of the input as its output. Useful because we have no way to see the raw XML “behind the scenes” that we want to transform. Included in handouts as “passthrough.xsl” 23

Passthrough XSL Note the use of the XPATH expression in the match attribute Specifies we are taking a “copy-of” everything below the “root element” July th Sakai Conference - Boston, MA, U.S.A.24

Form Rendering XSL When Sakai renders a form, it assembles an XML document behind the scenes. Form XML is rendered using the default renderers (formCreate.xslt/formFieldTemplate.xslt) or your custom renderers. Use a “passthrough” xsl as a custom renderer to capture the raw form XML Use that as your XML input in an XML IDE to create your own form renderers.

Capture “Raw” form XML You do it! Create a form using the the “practice” schema in your handouts. Upload the passthrough XSL file to resources and use it as a form view renderer for this form. Fill the form out in resources. Click on the form name in resources Capture the form XML (you need to “view source” since it isn’t HTML). Copy and paste it into a new XML document in Oxygen Use Oxygen “Format and Indent” ( ) feature to format the file. Save the file as “formPassthrough.xml” 26

“Import” Rather than “Include” The default formCreate.xslt renderer “includes” the formFieldTemplatestylesheet. If you want fields to be rendered differently than the defaults, import formFieldTemplate.xslt and override form field templates locally. Use “customFormCreate.xslt” from the handouts. 27

Oxygen and XSL Oxygen is shipped with XalanJ “Transformation Scenarios” can be established to transform one XML document with an XSL stylesheet Allows for quicker iterative development than repeatedly uploading your XSL stylesheets into Sakai 28

Configure Transformation Scenario Start with the document you wish to transform Establish a new project scenario Inputs XML URL: ${currentFileURL} (the default) XSL URL: browse to locate your new stylesheet Transformer: Xalan Extensions: add the xslt- façade.jar (in handouts) July th Sakai Conference - Boston, MA, U.S.A.29

Configure a Transformation Scenario Outputs: Save As: “out.html” “Open in Browser” and “Saved File”: if you want to view it in a browser “Open in Editor” to view the XML output July th Sakai Conference - Boston, MA, U.S.A.30

Create a Custom Form Renderer Watch me! Using the “practice” form from earlier Set up a scenario with the raw XML and the “formCustomCreate.xslt” in the handouts Add a prompt for the “shortText” field and view the results of a transformation. Switch the “import” of the formFieldTemplate to import from Sakai rather than your desktop. Upload the file and attach it as your custom renderer for this form. July th Sakai Conference - Boston, MA, U.S.A.31

Create a Custom Form Renderer You do it! Using the “practice” form from earlier Set up a scenario with the raw XML and the “formCustomCreate.xslt” in the handouts Add prompts for the “description” and “value” fields only and view the results of a transformation Change their order and transform it. Add descriptive text somewhere on the form about the meaning of each “value” and transform it. Upload the new renderer and attach it as your custom renderer for this form. July th Sakai Conference - Boston, MA, U.S.A.32

Other Ideas for Renderers Adding your own CSS files to change the look of a form Attachment of custom JavaScript files to change the form behavior Addition of “default” text to form fields Others? July th Sakai Conference - Boston, MA, U.S.A.33

Questions about: OxygenXML XSL Form rendering process Form renderers July th Sakai Conference - Boston, MA, U.S.A.34