Seamless Donations forms engine
The purpose of the Seamless Donations forms engine is to abstract form elements from the HTML page design such that it will be easier to add, move, delete, and change form elements.
A given form object consists of sections and element lists. Sections can contain sections and section can contain element lists. This is how the form can be easily segmented for user display. The functioning of the form is driven by a hierarchical PHP array that contains all the attributes that drive the form. This is the core of the engine design: change the array, change the form. Rather than recoding each instance of every form element, simple changes to attributes in the array can change behavior of the entire form or individual elements.
Forms can support the following form components:
- Radio button and radio button sets
- Checkbox
- Selection list in the form of either a drop-down or on-page list
- Form section – basic div
- Text field
- Static Text
- Action button
- Hider/revealer
- Hidden field
- Note: textarea fields have not yet been implemented
JavaScript requirement
The form requires JavaScript to function. It generates a <noscript></noscript> block that can be modified with the filter seamless_donations_forms_engine_noscript_filter.
Array definitions
Please note that this is a discussion of the internals of the plugin. Plugin users do not need to understand this design, although developers who wish to modify Seamless Donations to their needs or extend it for their sites may find this information valuable.
Seamless Donations Forms Array
The following elements are used to build up the main form array for any given form.| Array Key | Description |
|---|---|
| id | The id of the form |
| name | Name of the form for the name= attribute |
| before | Raw, unformatted HTML inserted just outside the <form> tag. |
| after | Raw, unformatted HTML inserted just after the </form> tag. |
| elements | An array of form elements, described below. |
| method | The form submit method, either POST or GET. Defaults to POST. |
| onsubmit | The name of a parameter-less JavaScript used by the form to process the form. By default, passed "return SeamlessDonationsValidator();". The validator either returns false on failure or goes on to call SeamlessDonationsCheckout, another JavaScript that parses the submitted form data and makes the Ajax request to the payment gateway. |
| action | A PHP script used to process the form result. Defaults to empty and is not used by Seamless Donations, but is included because we might want to trigger PHP at some point, or for some other use of the forms engine. |
| [section-name] | An array of section elements. Note that the key for this element is the name of the section, like "section-one". |
Seamless Donations Forms Section Array
The following elements are used to build up each section array. More than one section array can be created, and sections can be inside of sections. Each section array is named for its top-level key.| Array Key | Description |
|---|---|
| id | A string passed to the id= attribute |
| style | A string passed to the style= attribute |
| class | A string passed to the class= attribute |
| cloak | This is a class name used by reveal/conceal and indicates the section is to be cloaked (hidden) on initial state. |
| wrapper | Either 'div' or 'span'. Each element is wrapped in a wrapper for additional manipulation. If unspecified, defaults to div, but span can be used to prevent block-level presentation. |
| before | Raw, unformatted HTML inserted just inside the section wrapper opening div or span. |
| after | Raw, unformatted HTML inserted just inside the section wrapper closing div or span. |
| elements | An array of form elements, described below. |
| [section-name] | An array of section elements. Note that the key for this element is the name of the subordinate section, like "section-inside". |
Seamless Donations Forms Element List Array
The following elements are used to build up each element list array. This is where the real power of the forms engine can be found. All keys must be lower-case.| Array Key | Description |
|---|---|
| type | Defines the type of element being presented. Can be one of text|checkbox|radio|select|static|hidden|submit. As of 5.2.4, textarea is also available. |
| value | The value of the element (the default shown on the form, for text items), passed to the value= attribute. In the case of select lists, the value is the key of the item shown as selected (like the item in a drop-down list). |
| size | Size effects the text and select elements. If used with text, determines the width of the field. If used with select, determines dropdown (if set to 1) or list (if set to >1) |
| cols, rows | Works with textarea |
| options | An array containing select options for drop-down and display lists. The key is the value="" element, and the value is the text name. |
| id | A string passed to the id= attribute |
| style | A string passed to the style= attribute |
| class | A string passed to the class= attribute. When used with a label/input field, is used to define the div that surrounds the label and input. |
| class-label | A string passed to the class= attribute of the label. 5.0.6+ |
| class-input | A string passed to the class= attribute of the input field. 5.0.6+ |
| before | Unfiltered HTML code placed before the rest of the element's HTML code |
| after | Unfiltered HTML code placed after the element's HTML code |
| prompt | Simple text string displayed after a radio button or a checkbox |
| wrapper | Either 'div' or 'span'. Each element is wrapped in a wrapper for additional manipulation. If unspecified, defaults to div, but span can be used to prevent block-level presentation. |
| cloak | Elements with cloak keys are initially cloaked (hidden) when the form is presented. When a reveal element with a matching value to the cloak element is triggered, the element becomes visible. |
| reveal | Specifies that this element can be used to reveal another element. Works with radio buttons, checkboxes, and selection lists. The value is the reveal id, which determines what will be revealed when triggered (see hide). When used with select, this is an array containing option values as keys and space-separated lists of reveal ids as values. When the option is selected, the reveal id elements or sections are displayed. If reveal is used with a selection list, the value is an array containing the key/value pairs corresponding to selection list options and the targets to be modified when that option is selected. |
| conceal | This element contains a space-separated list of reveal ids, which represent the elements or sections that are to be hidden when the element (a radio button, check box, or selection list) is changed. |
| placeholder | If defined, gives the form an extra type that inserts a “placeholder=” into the form element. This might not be fully compatible with HTML standards, but it’s certainly something that, say, jQuery could use to do some magic with. |
| select | If defined (regardless of value) for an element of type radio or checkbox, will check or enable that element. It should be noted that using select on a checkbox or radio button won't trigger that control's reveal attribute. Hide trumps select and to show a hidden object, the user must actually tap a reveal control. |
| check | Used in a radio button or checkbox element to check or select a target element. The value of check is the element name of the target object to be checked. The target object is checked using this feature only when the element is checked (not unchecked) or selected (not unselected). |
| uncheck | Used in a radio button or checkbox element to check or select a target element. The value of uncheck is the element name of the target object to be unchecked. The target object is unchecked using this feature only when the element is checked (not unchecked) or selected (not unselected). |
| group | Used to define which radio buttons work together. All buttons with a group key of the same value will function like radio buttons. |
| validation | List of validations to be applied to the input. More than one validation can be applied by separating the validations with a comma. Choose from required, email, and currency. |
| [element-key] | Each element array has a key, and that key becomes the name= attribute for the element |
| submit | Generates a submit button |
