API Guide

Table of Contents

1. Introduction

Introduction

The XForms API allows you to:

• Create a form programmatically or from a static XML file
• Present the form to the user
• Validate user input automatically
• Optionally provide extra validation using "Pictchas"
• Retrieve and process submission values

Including the necessary modules

To run XForms, you will need to add the PR2 and XForms modules to your project if they are not already added (typically done in config/standardIncludes):

SAutoLoad::addModule('pr2');
SAutoLoad::addModule('xforms');

Creating an XForm

You can create a new XForm by creating a new instance of XFormRenderModule.

$xrm = new XFormsRenderModule();

This will create a blank XForm, so you will need to add content to the form, either from a file or programmatically.

From an XML File

To load an XForm from a file, just load an XForms XML file from your file system into a string (in an application, this XML file should be stored in project/content), then load that string into the XFormsRenderModule.

$formXML = file_get_contents("../../content/sampleForm.xml");
$xrm->loadXml($formXML);

The wiki has documentation on how to write XForms-compatible XML files at the following link: https://wiki.shodor.org/index.php/Shodorx_Forms

Programmatically

Creating a Form Object

To being creating an XForm programmatically, create an instance of the Form class.

$form = new Form();

Adding Text

To add titles demarcating sections of your form, use addText();

$form->addText("Title of the Form Section", "Description of the Form Section");

Adding Form Inputs

To add a form input, use addInput(). Pass in the following, in this order:

• $type - The type of form input to generate
• $label - The label attached to the form input
• $ref - The ref that links this item to the data model, which you will use to access the user values for this input
• $validationType - The validation type that should be used to check user values for this input. Available validation types are discussed on this page: https://wiki.shodor.org/index.php/StandardValidator_class
• $required - Whether or not this input requires a value from the user
• $value - A default value for the input
• $items - The allowed values (if this is a select or select1 input)
• $appearance - how large the input element should be: full, compact, or minimal
• $description - A description that can appear under the label

To crete a set of checkboxes, you could use the following code to create a "select" input:

$options = array('One', 'Two', 'Three', 'Four', 'Five');
$form->addInput('select', 'My Checkboxes', 'myCheckBox', 'paragraph', true,
                array('One'), $options, 'full',
                'Try clicking on some of the following options...');

To crete a set of radio buttons, you could instead create a "select1" input:

$options = array('One', 'Two', 'Three', 'Four', 'Five');
$form->addInput('select1', 'My Checkboxes', 'myCheckBox', 'paragraph', true,
                array('One'), $options, 'full',
                'Try clicking on some of the following options...');

To crete a dropdown menu, you would use the same code, but with an appearance of 'minimal':

$options = array('One', 'Two', 'Three', 'Four', 'Five');
$form->addInput('select1', 'My Checkboxes', 'myCheckBox', 'paragraph', true,
                array('One'), $options, 'minimal',
                'Try clicking on some of the following options...');

To create a textarea, you would do the following:

$form->addInput('textarea', 'Description', 'description', 'paragraph', false,
                'Replace this text to write a description...', '', '',
                'Please write a description of yourself');

Generating Form XML Finally, we generate XML using buildForm() and pass that output to the XFormsRenderModule.

$outputXML = $form->buildForm('Submit Test Data');
$xrm->loadXml($outputXML);

Presenting Forms to Users

Validate User Input

Retrieve and Process Submission Values