Standard forms in FlightPath are handled through a system called the Form API. This is very similar to Drupal's Form API, for those that are curious. Forms are really just an array with all of the elements of the form contained within indexes of the array.

By making use of the Form API, input is automatically validated and screened for possible security threats.

Standard form elements

Defining a form element usually takes the following form:

$form["element_name"] = array(
   "type" => "textfield",
   "label" => "What is your favorite color?",
   "description" => "Enter your favorite color in the box.",
);

Let's look at some of the options you have for each type of form element:

Standard form element keys and options

• type - the type of form element this is going to be
  • textfield, markup, markup_no_wrappers, textarea, password, hidden, file, radios, select, checkboxes, checkbox, submit, button
    • The 'markup_no_wrappers' type will not place any <div> tags around your markup (value element), and is the default is you do not set a type.
• label - the text above an element, asking the user for information.
• description - A smaller bit of text below the element, describing in greater detail what this element is for.
• value - The default, initial value of the field.
  • For markup, this contains the HTML for the field of markup to display.
  • For checkbox, set to boolean TRUE if it should be checked.
• options - For select, radios, and checkboxes, this is an array of options for those fields.
• prefix - HTML to appear before the element
• suffix - HTML to appear after the element
• spinner - Boolean TRUE will cause a "spinner" to appear next to the element after it is clicked, and for the element itself to be disabled.
  • Works well for Submit buttons.
• required - boolean, whether or not the field is required in order to be submitted
• popup_description - Like description above, but this will provide a link for the user to click to view the description, using javascript.
• attributes - This is a string of attributes to add to the element itself.
  • Ex:   "attributes" => "readonly=readonly style='color: green;' class='inp1'  ";
     

Special form element options and notes

• submit element
  • confirm - Text to display to the user when the form's submit button is pressed.  It will cause a javascript confirm alert to appear.
    • Ex:  "confirm" => "Are you sure you want to delete this item?",
• select element
  • no_please_select or hide_please_select (alias) - boolean, whether or not to display the select list with an initial "Please select" option as the first option in the select list, which is the default behavior.
    • Ex:  "no_please_select" => TRUE,  // hide the Please select message
• checkbox element
  • Unlike the "checkboxes" element, which allows you to have multiple checkboxes, this is a single on/off checkbox.  What actually gets submitted is a number one (1) if checked, which is converted to a boolean TRUE when saved.
• cfieldset element
  • This creates a "collapsible fieldset", and it is very handy to use to group form fields together.
  • First, place your fields (you want in the fieldset) into their own array.  Ex: $fs. Then, build them up normally.  Ex:
          $fs["name"] = array( "type" => "textfield", "label" => "Enter your name");
          $fs["age"] = array("type" => "textfield", "label" => "Enter your age");
  • Then, create the collapsible fieldset like so:
    • $form["my_fieldset"] = array(
          "type" => "cfieldset",   // notice the 'c' !
          "label" => "My Collapsible Fieldset",
          "start_closed" => FALSE,   // set to TRUE to start in a closed state
         "elements" => array($fs),  // make sure this syntax is exact!  it goes in an array!   
      );
• file element
  • The following is only available when handling file uploads through the content module:
    • limit - this allows us to automatically allow the user to upload more than one file.  Using javascript, an "add more" link will appear.
      • Ex:   "limit" => 2,   // may upload up to 2 files.
      • If not set, the limit is 1 file.
    • allowed - this is a csv string of allowed file extensions. If not set, a default list of "safe" files is provided automatically.

Special options for the form itself (at the $form level, no element):

• #form_include
  • Extra files which need to be included when the form submits.  Good for if the form is defined in a .inc file.
• #attributes
  • An assoc array of attributes to add to the form.  Ex: class
• #submit_method
  • Either GET or POST.  POST is default.
• #submit_handlers
  • An array of additional submit handler functions (beside the default)
• #validate_handlers
  • Same as #submit_handers
• #redirect
  • Assoc array for where to redirect once submission is completed.  Expected structure: ["#redirect"]["path"] = "whatever/path";  and  ["query"] if there is an optional query.
  • Otherwise, the default redirect will be used, which is just to reload the form page.