Table of Contents
The MU_Form class provides end-to-end services for creating a form, validating a form's contents, and harvesting a form's data. The MU_Inline_Form class provides a subset of the MU_Form class' functionality and is intended to be used to create extremely small and simple forms.
MU_Form forms use the following structure:
Form
Section
Input items
Blocks (optional)
Input items
...
Section
Input items
Blocks (optional)
Input items
...
...
MU_Inline_Form forms use the following simpler structure:
Form
Input items
The general methodology of using a form is:
Instantiate an MU_Form or MU_Inline_Form object by name
Add sections, blocks, and input items
Add the form to the MU_Presentation object
Marmot handles form validation
Instantiate an MU_Form or MU_Inline_Form object with the same name as the original
Access form data with the value() method
Due to the way Marmot internally handles and passes form data to and from the validation engine, direct access to form data through $_GET, $_POST, and $_REQUEST is not supported. The value() method should be used to extract any user input from the form. When gathering data from a form, you do not need to add the sections, blocks, or input items. The MU_Form class retains all of the information necessary to return data back to the developer.
After creating and populating an MU_Form object, it must be added to the presentation layer with the MU_XML_Element::add_object() method.
The form must be fully built before adding it to the presentation object. The MU_XML_Element::add_object() method will immediately add the necessary elements to the parent object.
This section includes basic information about how forms are created and added to a document. These examples can also be seen in the "Forms- Creating Forms" example included with Marmot.
The following code creates a form with instructions, a textbox, a popup list, and a submit button:
We first create a new instance of the MU_Form class, $simple_form.
We can then set class properties, like the form's action (to what URL it will be submitted), title, and instructions:
Forms must be divided into named sections. Our simple form only contains one section, named "widgets:"
The add_input_item() method is, as the name implies, used to add input items to an enclosing object (either a section or block). In this example, a textbox and a popup menu are added to the section we created above:
Refer to Input item types for descriptions of the available form input item types.
The add_input_item() method follows this format:
All input items must have a unique name. It is by this name that you will access the submitted form's values. Note that the third argument passed to add_input_item() is a default value. As you will see later in the Validating a form section, Marmot will keep track of a user's input if the form is displayed again.
A user action named "submit" is added to the form with the add_user_action() method. The Presentation Layer displays this as a button. In addition, we tell Marmot to validate the user's input to this form- in this case, checking to make sure that the value of "part_number" is a number.
Finally, the form is added to the document using the MU_XML_Element::add_object() method:
Note that the form will not be diplayed if it is not added to the document.
In the following example, we build on our simple form. It now includes a hidden input element, multiple sections, section titles, section-level instructions, blocks within sections, block-level instructions, and input groups:
The MU_Inline_Form class is used to create tiny, extremely simple forms. It is used almost exactly like MU_Form, but doesn't include support for such features as sections, blocks, or validation.
It is sometimes necessary to insert elements into a form that are submitted along with a user's input, but are not displayed. In HTML, these are "input" items of the type "hidden". Marmot allow you to insert such elements by invoking the MU_Form class's add_hidden method:
By default, all types of forms submit to the page that created them. This allows the developer to keep the data process in the same file as the form definition. If you want to change the page the form data is submitted to, simply alter the action attribute of the form to a valid URL (relative to the current page). For example: