Class "Form" - mudmin/UserSpice5-Dev GitHub Wiki

The Forms class is used with this syntax:

$myForm = new Form([
    'keyvalue' => 'html code',
    'keyval2' => new FormType ([]),
    'keyval3' => new FormFieldType ([]),
    ...
], [
    'key1' => 'option1', 
    ...
]);

There are 2 arrays passed as arguments to the constructor, both optional.

ARGUMENT 1. The first is an array of any of the following:

  • HTML code
  • nested Form elements (FormTab, FormCol, FormRow, FormPanel, FormWell, etc.)
  • these form classes can then contain any of these 3 types along with the options below
  • FormField elements

These 3 types of elements can be intermixed in any order and nested Form elements can contain any of the 3 types of elements in a recursive fashion.

ARGUMENT 2. The second argument is an array of options

Valid options for a form include the following:

  • 'titletoken' or 'title_lang' - a token to be passed to lang() to set the title of the form
  • 'title' - sets the title of the form
  • 'active_tab' - sets/identifies the default active tab on a tabbed form
  • 'tab_id' - identifies the id of the current tab (normally used on FormTab_Pane forms)
  • 'keep_AdminDashboard' - allows the UserSpice administrative dashboard menu to be displayed in addition to the normal navigation
  • 'elements' - used to set the list of HTML elements to be included
  • 'table' or 'dbtable' - used to identify which database table the data in the current form is based off of
  • 'debug' - set an integer value of 0=none to 5=maximum debug verbosity
  • 'keep_if' or 'keepif' - a boolean value which indicates this form will be kept if true and deleted completely if false (inverse of deleteif)
  • 'delete_if' or 'deleteif' - a boolean value which indicates this form will be deleted if true and kept if false (inverse of keepif)
  • 'delete_if_empty' - a boolean indicating whether the form element should be deleted if there are no values to display
  • 'exclude_elements' - a list of elements which normally would be included in this form but will now not be included
  • 'repemptyalternate' or 'nodata' - an HTML string which will be displayed instead of the element if the repeating element has no values

All of the above options are case-insensitive.

In addition, options may be used to alter class definitions as follows:

  • any method which begins with "set" can be executed by passing an option which corresponds to the remainder of that method name. So passing 'foo_abc' => 'xyz' as an option would execute setFoo_Abc('xyz') if setFoo_Abc() exists.
  • any property which begins with "HTML_" can be altered by passing an option which corresponds to the remainder of that property name. So passing 'foo_abc' => 'xyz' as an option would set $this->HTML_Foo_Abc to 'xyz' if that property exists. These $HTML_* properties correspond to the elements included in any form.
  • any property which begins with "MACRO_" can be altered by passing an option which corresponds to the remainder of that property name. So passing 'foo_abc' => 'xyz' as an option would set $this->MACRO_Foo_Abc to 'xyz' if that property exists. These $MACRO_* properties are used as search/replace values within the string of the form elements.

To help understand $HTML_* and $MACRO_*, consider this example:

$HTML_Input = '<input type="{INPUT_TYPE}" name="{NAME}" />';
$MACRO_Input_Type = 'text';
$MACRO_Name = 'MaryJane';

When run, this would result in the 'Input' element being displayed as this:

`<input type="text" name="MaryJane" />`

The Form class is a parent of the following classes, each of which can be included in a form as a nested form element.

  • Form_Col - used to create a new bootstrap column within a form
  • Form_Row - used to create a new bootstrap row within a form
  • FormTab_Contents - used to create a table of contents for a tabbed form
  • FormTab_Pane - used to create a new pane for a tabbed form
  • Form_Form - used to create a new HTML form within a UserSpice form (apologies for the ambiguous names)
  • Form_Panel - can't remember what this is for - I think a special bootstrap thing with a header and footer
  • Form_Well - used to create a bootstrap well