Dev:FormUI

From Habari Project

(Redirected from Classes/FormUI)
Jump to: navigation, search

FormUI is a class for easily creating forms that mesh well with the Habari admin design and easily handling their validation and processing.

FormUI is not meant to be a panacea for form construction, especially in terms of styling, but it allows Habari the flexibility of modifying many internal forms on the fly from plugins without manipulating the HTML and form results directly.

The operations provided by FormUI and its related classes should be simple. Most common controls on forms should be created with the least effort. Required values for controls should suffice in most cases, but some extra commands should allow more (but not necessarily absolute) flexibility.

Contents

Using FormUI

Create a Form

The basis of creating forms with FormUI starts with creating the form object.

A form requires a unique identifier to distinguish it from other forms that might be submitted on the page.

To create and output a basic form object:

$myform = new FormUI('my_identifier');
$myform->out();

This creates a form with no controls and the id "my_identifier". This form could be addressed in javascript using jQuery as $('#my_identifier').

The ->out() method on the form causes the form both to be displayed and to be processed if it is submitted.

Using the class name for an identifier

Many plugins in core pass the class name as the identifier for a new form:

$myform = new FormUI( strtolower( get_class( $this ) ) );

This is just an elaborate way of ensuring a unique form identifier between each plugin.

A reason to use this as an identifier is in case the plugin is copied to a new directory and given a new class name, the two plugin forms (the original and the copy) will use different identifiers. A reason not to use this as an identifier is if javascript addresses the id of the form (which is the identifier), which would be more difficult to do if the identifier was allowed to vary.

Suffice to say that a unique string is all that's necessary, and how it is obtained is usually immaterial.

Add a Control

For a form to be useful, it should contain at least one control, and a method for the form to submit.

In this case, a text field has been added to the form, along with a save button:

$myform = new FormUI('my_identifier');
$myform->append('text','firstname', 'user:username', 'Firstname:');
$myform->append('submit', 'save', 'Save');
$myform->out();

The append() method of the FormUI class (or any FormContainer class descendant) accepts parameters in two styles. First is the style above, which allows easy creation of a text field with minimal configuration.

The second style allows you to manually create the control and append it to the form:

$myform = new FormUI('my_identifier');
$myform->append(new FormControlText('firstname', 'user:username', 'Firstname:') );
$myform->append(new FormControlSubmit('save', 'Save') );
$myform->out();

This may be useful if you want to create the control object beforehand, such as if you needed to display one of two control types depending on some other criteria.

Note that these two constructs produce the same result. If the first parameter is a string, then a control is created using the class "FormControl" plus that text. The subsequent parameters are passed in the control's constructor, just like in the second example. If there's no need to alter control parameters ahead of time, the first style of control creation provides a simpler construction.

Arrange a Control

function get_myform() {
  $myform = new FormUI('my_identifier');
  $myform->append('text', 'firstname', 'user:username', 'First name:');
  $myform->append('submit', 'save', 'Save' );
  return $myform;
}
$myform = get_myform();
$myform->insert('save', 'text', 'lastname', 'user:username', 'Last name:');
$myform->append('cancel', 'cancel', 'Cancel');

Move a Control

Both of the following move $myform->lastname before $myform->firstname.

$myform = get_myform();
$myform->move_before($myform->firstname, $myform->lastname);
$myform->move_after($myform->lastname, $myform->firstname);

Remove a Control

$myform = get_myform();
$myform->firstname->remove();

Insert a Control

You may find the need to place a control within another control, specifically adding a control to a fieldset.

$myform->control->move_into($myform->control);

Modify a Control

Controls can be easily modified after using either of the styles for adding new controls:

$myform = new FormUI('my_identifier');
$myform->append('text', 'firstname', 'user:username', 'Firstname:');
$myform->firstname->label = 'First Name:';
$myform->append(new FormControlSubmit('save', 'Save') );
$myform->out();

The line $myform->firstname->label = 'First Name:'; changes the label of the control to 'First Name:'. Notice that the name of the control is now a property of the container, and that the control's property of label provides direct access to that value of the control.

Controls should not use names that correspond to FormUI members or they will be inaccessible. For example, if you create a form, $form, and FormUI defines $form->style as the style string to assign to the form tag, then you shouldn't name a control 'style'. As yet, FormUI has no members.

The ->append() method also returns the instance of the control so that it can be modified. Assign the return value to a variable. This variable will contain the same value as the name of the control used as a property on the FormUI object:

$myform = new FormUI('my_identifier');
$firstname_control = $myform->append(new FormTextControl('firstname', 'user:username', 'Firstname:') );
 
// This:
$myform->firstname->label = 'First Name:';
 
// Is the same as this:
$firstname_control->label = 'First Name:';

Useful Hooks

Habari provides specific hooks for certain forms. For example the publish form can be modified using action_form_publish() and the comment form can be modified using action_form_comment().

Many plugins that add a content type need to alter the post publish form to add fields specific to that content type. An example might be a blogroll plugin that adds a field for a URL.

public function action_form_publish( $form, $post)
{
  if ( $form->content_type->value == Post::type( 'blogroll' ) ) {
    $form->append('text', 'url', 'null:null', _t('URL'), 'admincontrol_text');
    $form->url->tabindex = 2;
    $form->url->value = $post->info->url;
    $form->url->move_after($form->title);
  }
}

Adding a class to the comment form inputs might be useful for themes.

public function action_form_comment( $form )
{
  $form->email->class[] = 'comment_email';
}

Additionally, Habari provides hooks that allow for the modification of named forms, using action_modify_form_{name}(), where {name} is the name of the form, without the braces.

To modify a form named register, you would use the following code.

public function action_modify_form_register( $form )
{
  $events = array(
    'pony ride',
    'coffee drinking',
    'HabariBar'
  );
  $form->append('select', 'event', 'null:null', 'Event:');
  $form->select->options = $events;
}

Finally, and even more generally, any form can be modified using action_modify_form().

Special FormControl Properties

There are special properties of the FormControl that are used in the form processing. These values can be output in the template, but they are also used by FormUI internally.

value
This property of a FormControl contains the value that will be or is already stored in the database for this control, whether the value was read from the database or submitted by a user.
label
This property of a FormControl contains the rendered name of the control as used in prompts concerning the control. For example, in validation methods the label of a FormControl is displayed as the field name if there is a validation failure.

Adding and Changing Control Templates

While Habari ships with both generic and admin-specific templates for the various controls, it is possible to add or override these template to change the way these controls are presented by calling Pluggable's add_template() method. Since both Theme and Plugin classes extends Pluggable, the method can be called from within both.

Say that you want to add a new template to the text fields displayed in your plugin's configuration form:

//Within our plugin
public function action_form_publish( $form, $post)
{
    $this->add_template('my_text_template', dirname(__FILE__).'/custom_formcontrol_text.php');
    $myform = new FormUI('my_identifier');
    $myform->append('text', 'firstname', 'user:username', 'Firstname:', 'my_text_template');
    $myform->append(new FormControlSubmit('save', 'Save') );
    $myform->out();
}

Overriding an existing template is similar. In the following example, we override the default template, formcontrol_text, with a custom template file included within our theme directory:

//Within theme.php
public function action_form_comment($form)
{
    $this->add_template('formcontrol_text', Site::get_dir( 'theme' ).'/custom_formcontrol_text.php', true);
}

Any control in the form that was using the formcontrol_text template would now use our custom template.

You must exercise caution when calling add_template(). In the above example, the only text controls affected are the comment form's text controls. Calling it from a plugin's action_init() method, for example, would cause it to override templates in other forms as well, such as in the admin theme.

Habari's default FormUI templates are in habari/system/admin/formcontrols/. Do not modify these as the modifications will be lost when you upgrade Habari. Instead, place a copy of the control template you wish to modify in your theme or plugin directory and make the necessary modifications.

See the Customizing forms section in Creating a Custom Theme for more details.

Handle Form Submissions

When the ->out() method is called on the form object, it is rendered to the page. If the form was submitted back to the page (the default submission destination for FormUI forms), then the ->out() method processes the form as well.

$myform = new FormUI('my_identifier');
$myform->append('text', 'firstname', 'user:username', 'Firstname:');
$myform->append('submit', 'save', 'Save');
$myform->out();

In the case of this form, two controls were created. One was of type FormControlText, and the other of FormControlSubmit. FormControlSubmit does not save its value, and so its constructor does not include a property for a storage method. FormControlText, as with most other FormControl descendants, has as its first parameter the storage mechanism that the control will employ. This mechanism is always either an object instance implementing FormStorage or a string in the format "type:location", where the type dictates the use of the location:

user
This type indicates that the value of the control will be stored in the userinfo table using the name "{$location}"
option
This type indicates that the value of the control will be stored in the options table using the name "{$location}"
action
This type indicates that the value of the control will be passed to the indicated plugin action named "{$location}".
session
This type indicates that the value of the control will be stored in the $_SESSION superglobal with the key named ["{$location}"]["{$controlname}"]. The whole set of values can be obtained via Session::get_set("{$location}").
null
This type indicates that the value of the control should not be automatically stored. The location in this case is ignored.

Prior versions of FormUI may have used the form name as part of the option name. This is undesirable because it prevents, for example, a plugin from inserting additional fields into another form and storing them under its own prefix.

It is a good practice to use a prefix to the location so that all of a form's settings are stored under a grouping. For example, "option:myplugin__username" would do well to group all of the options related to "myplugin".

If the type is omitted from the storage mechanism, then "option:" is implied.

If the storage parameter is an object instance implementing FormStorage, then the field_save() method of the object is used to store the control value. Likewise, when obtaining existing values, the field_load() method of the FormStorage object is used. When storing values in a FormStorage object, the key of the value stored is the name of the control.

The value stored by the control is completely dictated by the control. A FormControlText stores a plain text value, but a FormControlCheckbox stores a boolean value. Other stored values may be more complex or even compound in the case that the control is actually a set of controls combined together (such as a grid control, or a control to let you select and upload a file temporarily before submitting the whole form).

Initial Control Values

The storage method specified is also used to obtain the default value of the control specified. If a control should have a different initial value than the one in the storage location (or if the location is "null"), then the value of the control must be set, like in this example:

$myform = new FormUI('my_identifier');
$myform->append('text', 'firstname', 'null:unused', 'Firstname:');
$myform->firstname->value = 'Bob';
$myform->append('submit', 'save', 'Save');
$myform->out();

Reading the value of the control immediately after it is assigned may yield somewhat unexpected results. If the form was submitted, then the value assigned in code will not be the value returned from that control's value property.

Consider this example, which assigns the value of "Alice" to the firstname control, and then assumes that a user may submit "Bob" as the field's value. If so, the code adds a "Lastname" field to the form:

$myform = new FormUI('my_identifier');
$myform->append('text', 'firstname', 'user:username', 'Firstname:');
 
$myform->firstname->value = 'Alice';
 
if($myform->firstname->value == 'Bob') {
  $myform->append('text', 'lastname', 'user:lastname', 'Lastname:');
}
 
$myform->append('submit', 'save', 'Save');
$myform->out();

Form Post-Processing

The storage mechanisms described above may be fine if the values of the form simply need to be stored in the database, but if some processing needs to happen as the result of a submission, the ->on_success() method should be used:

$myform = new FormUI('my_identifier');
$myform->append('text', 'firstname', 'user:username', 'Firstname:');
$myform->append('submit', 'save', 'Save');
$myform->on_success(array($this, 'my_callback'), 'Bob');
$myform->out();

The first parameter of the ->on_success() method is either a valid PHP callback or the name of a plugin filter.

For example, the on_success parameter is "my_callback" as in the above code. Upon successful submission FormUI looks for a function named "my_callback". If found, then my_callback() is called with the form object as the first parameter. Any additional parameters to ->on_success() are passed as additional parameters to the callback.

If a callback of any kind exists, then it is responsible for saving the data of the form. This can be done using FormUI's save() method, which simply saves the form values as though the on_success() callback did not exist. Alternatively, the callback could save the options by querying the values from the form and saving them to wherever is appropriate.

The callback should return false if the form is to display itself again (with the default confirmation message) after it returns. Alternatively, the callback can return HTML that will be output instead of the form to display a more detailed message. The form itself can be included in this HTML by calling $form->get() and adding any additional markup.

Here is an example of the callback method described above:

function my_callback($form, $special_name) {
  if($form->firstname->value == $special_name) {
    // Do something if the first name is the one
    // specified in the call to $form->on_success()
  }
  // Perform normal save routines
  $form->save();
  // Display the form normally with the default confirmation message
  return false;
}

A valid callback can be either an executable PHP callback or the name of a Habari filter. For a PHP callback, if the array is defined as array($this, 'my_callback') then the callback executes a method of the plugin's class named my_callback(). Refer to the PHP documentation on callbacks for more clarity on this idea.

If the callback does not exist as a callable function, then the plugin filter with the same name (in our example, "my_callback") is executed, which in turn executes every plugin's method named "filter_my_callback". Remember that this is a plugin filter, and needs to be named as such (with "filter_" prepended), not just share the identical name supplied as the callback string.

The first parameter of the filter is the same as the return value of the function callback above. If the default form and confirmation should be displayed, return false. If something else should be displayed instead, return the appropriate HTML. If a prior filter has handled the callback and returned HTML, new values should be added to that HTML, rather than simply returning false.

The second parameter of the filter is an instance of the form object itself. Additional parameters to the ->on_success() method are passed as additional parameters of the filter function.

Here is an example:

class myplugin extends Plugin {
...
  function filter_my_callback($save_form, $form, $special_name) {
    if($form->firstname->value == $special_name) {
      // Do something if the first name is the one
      // specified in the call to $form->on_success()
    }
    // Perform normal save routines, but account for
    // other plugins that might want to override this
    return $save_form || false;
  }
}

Changing the Form Action

By default, the form will be submitted to the same page that it was rendered on. This can be overridden using the set_option method.

$myform = new FormUI('my_identifier');
$myform->append('text', 'firstname', 'user:username', 'Firstname:');
$myform->append('submit', 'save', 'Save');
// Set the submission URL
$myform->set_option('form_action', URL::get('admin', 'page=users' ) );
$myform->out();

The second parameter is the URL to which you want to submit the form. In this case, we use URL::get() to let Habari construct the appropriate URL for us.

Using Form Values

It might not always be apparent where a form value is stored. It would be useful to code the storage technique and location used for a control once, and then rely on the control values for use in the application of the code. Here is a way to do that:

class MyPlugin extends Plugin {
...
  // A function to create and not display the form:
  private function get_form() {
    // Create a new form:
    $form = new FormUI('myplugin');
    // Add a new field for "about" that is stored in Options::get('about'):
    $form->append('textarea', 'about', 'option:about', 'About this blog:');
    // Return the form:
    return $form;
  }
...
  // A function to display the form in the plugin config:
  function function action_plugin_ui($plugin_id, $action) {
    if ($plugin_id == $this->plugin_id()){
      switch ($action){
        case 'Configure' :
          $this->get_form()->out();
          break;
      }
    }
  }
...
  // A theme function to output the "about" information:
  function theme_about() {
    // Instead of this:
    //   return Options::get('about');
    // This allows access directly from the form:
    return $this->get_form()->about->value;
  }
...
}

This example might seem absurd at first, since it produces what seems like additional work, but if the form is more complex and draws its default values from multiple storage locations or custom settings, it might be easier to centralize the form creation without outputting it, then use the form to gather the required field data as requested.

Create a Custom Control

All form components must derive from the FormControl class. Controls should be named "FormControl{$something}" so that they can be used with the easy creation method.

When a FormControl is output to the page by FormUI, FormControl uses the FormUI's Theme object to render a template specified by the descendant control.

If no ->get() method is supplied by the new FormControl class, then the {$something} part of the control's classname is used to derive the template to use to display that control. The template name is "formcontrol_{$something}".

To supply a template other than the derived one, the control must supply a ->get() method.

class FormControlCustom extends FormControl {
  function get($forvalidation) {
    // Get the theme object to use to render this control
    $theme= $this->get_theme($forvalidation);
 
    // Tell the theme what template to render for this control
    return $theme->fetch( 'my_special_control_template' );
  }
}

Any property assigned to the control that is not used by the control for another reason is assigned into the template when it is rendered by the ->get_theme() method. This makes it possible to easily create new controls by building new control templates that follow a certain format for displaying and collecting their values.

Field Validation

It may be necessary to limit the values submitted via certain controls to a range of certain values. When the submission falls outside that range, an error messages should be displayed, and the form should fail to submit (although the previously submitted values should appear to the user for alteration).

FormControls all have an add_validator() method which accepts a string containing the name of an existing FormValidator method, or an array pointing to a custom validator.

For example, to validate a text control which should contain an email address:

$email_control= $form->add( 'text', 'email', 'option:email', _t('Enter your email address') );
$email_control->add_validator( 'validate_email' );

validate_email is a method in the core FormValidator class. The value of the form submission is passed to this method for validation. If the validator returns an error, this error is displayed in the form and the form submission fails.

Validators may accept additional parameters. For example, the 'validate_regex' validator accepts a regular expression as an additional parameter, which should match the value submitted or cause the form to fail.

Applying multiple validators to a field causes all validators to be processed for that field. If any validator fails, then the form fails. Note that in the above example, the 'validate_email' validator does not require a value. In other words, if the field is submitted with a blank value, the validator passes. In order to require a value, the 'validate_required' validator should be applied to a field. (Should we add the validate_require by default, and then make the code remove that validator for optional fields?)

To validate based on an OR situation, such as when a field should be either a number or a name, a custom validator should be created.

A list of validators supplied by the core FormValidator class and the parameters they accept appear in a separate section, below.

Validators are stored on the control in an array that is indexed by the function used to do the validation. Therefore, there can only be one with any particular name. So if you add the same function a second time, it will overwrite the first. For instance, if you wanted to change the validation message on the comment box in the default comment form you could use:

$form->cf_content->add_validator( 'validate_required',_t ('Your custom message.'));
 
//Use the corresponding label in your message
$form->cf_content->add_validator( 
    'validate_required',
    _t ('Your custom message about %s here', array($form->cf_content->label))
);

Creating Your Own Validators

FormUI supports the use of custom validation functions.

If the validator returns an empty array, that implies that no validation errors were encountered. FormUI will pass the FormControl value, the FormControl itself, and the entire FormUI form to the validator.

Multiple validators can be applied to a single control. Multiple errors on a single control are merged for output.

As an example of a custom validator, the SimpleFileSilo plugin defines a custom mkdir_validator() method that ensures that a directory name specified for creation via the silo is valid:

class SimpleFileSilo extends Plugin implements MediaSilo {
...
$dir_text_control= $form->append( 'text', 'directory', 'null:unused', _t('Enter the directory name to create') );
$dir_text_control->add_validator( array( $this, 'mkdir_validator' ) );
...
  public function mkdir_validator( $dir, $control, $form ) {
    $dir= preg_replace( '%\.{2,}%', '.', $dir );
    $path= preg_replace( '%\.{2,}%', '.', $form->path->value );
    $dir= $this->root . ( $path == '' ? '' : '/' ) . $path . '/'. $dir;
 
    if ( ! is_writable( $this->root . '/' . $path ) ) {
      return array(_t("Webserver does not have permission to create directory: {$dir}."));
    }
    if ( is_dir( $dir ) ) {
      return array(_t("Directory: {$dir} already exists."));
    }
 
    return array();
  }
...
}

Using all of the values passed into the validator, it is possible to create validators that depend on the values of more than one control. For example, one might create a dropdown control that changes the validation requirements of a subsequent text control:

class myplugin extends Plugin {
...
  function output_form() {
    $myform = new FormUI('my_form');
    // Create a dropdown to select login method type:
    $myform->append('select', 'logintype', 'user:logintype', 'Login type to use:');
    $myform->logintype->options = array('user id #', 'user name');
 
    // Create a login field:
    $myform->append('text', 'login', 'user:login', 'Login:');
    $myform->login->add_validator( array( $this, 'validate_login' ) );
 
    // Create a save button:
    $myform->append('save', new FormControlSubmit('Save') );
    $myform->out();
  }
...
  function validate_login( $login, $control, $form ) {
    if($form->logintype->value == 'user id #') {
      if( !is_numeric( $login ) ) {
        return array(_t('The login id must be numeric.'));
      }
    }
    else {
      if( is_numeric( $login ) ) {
        return array(_t('The login must be your user name.'));
      }
    }
    return array();
  }
}

Remove a validator

There may be cases where a FormUI object is passed by reference to a plugin filter. This will allow a plugin to alter the fields of a form. In this case, it may be useful to remove a validator that had previously been added to a control.

To do this, use the ->remove_validator() method on the control:

// Some code that adds a required email field to a form:
$form->add( 'text', 'email', 'option:email', _t('Enter your email address') );
$form->email->add_validator( 'validate_required' );
 
// This code executes elsewhere and removes that validator:
$form->email->remove_validator( 'validate_required' );

Core Controls

The controls below are supplied with Habari's core. These controls can be extended, or whole new controls can be created.

Optional fields describes the fields that a control supports for altering output or the disposition of the control.

Additional templates describes templates that can be applied to the control so that it integrates into forms better stylistically. These templates are most commonly applied applied using this syntax:

$form->append('checkbox', 'mycheck', 'option:mycheck', 'Check Me');
$form->mycheck->template = 'tabcontrol_check';

Check Box

$form->append('checkbox', 'standalone', 'register__standalone', _t('Show standalone registration form'));

This adds a checkbox named standalone and labelled Show standalone registration form to your form, and saves it as a site option called register__standalone when the form is submitted. You can also add an array of checkboxes, as this example from the Route301 plugin shows.

$form->append('checkbox', $rule['name'], 'route301__'.$rule['name'], sprintf(_t('Route %s URLs'), $rule['build_str']));
Class Name
FormCheckBox
Default Template
formcontrol_checkbox

The check box control includes a special hidden field so that the form knows that the checkbox was submitted, even if it was unchecked.

Optional Fields

class
An array of classes that will be added to the wrapping div
id
The id of the wrapping div

Alternate Templates

tabcontrol_checkbox
This is used to integrate a checkbox control in areas similar to the tabbed area of the publish page

Fieldset

The following code adds a fieldset called imprint_controls to a form, with the legend "Enter details of IMPRINT edition". As no template has been specified, the default fieldset template will be used.

$form->append( 'fieldset', 'imprint_controls', 'Enter details of IMPRINT edition' );

Controls can then be added directly to the fieldset.

$form->imprint_controls->append( 'text', 'year', 'null:null', 'Year' );

Button

$form->append( 'button', 'button', _t( 'Click me' ) );

This adds a button named button and labelled Click me to your form.

Class Name
FormControlButton
Default Template
formcontrol_button

You can also set an onclick property on a button control, which lets the button respond to Javascript. The following code will show an alert when the button is clicked.

$form->button->onclick = 'alert("Clicked!");';

Optional Fields

class
An array of classes that will be added to the wrapping div
id
The id of the wrapping div

Hidden Field

$category_id = $form->append( 'hidden', 'category_id' )->value = $category_term->id;

Label

Password Field

Radio Buttons

$form->append('radio', 'display_avatar', 'option:woopra__display_avatar', _t('Display users\'s avatars', 'woopra', array('no' => 'never', 'yes' => 'always'));

This adds a radio button named display_avatar and labelled Display users's avatars to your form, and saves it as a site option called woopra__display_avatar when the form is submitted. The possible values and their labels are passed as an array.

Class Name
FormControlRadio
Default Template
formcontrol_radio

Optional Fields

options
An array of radio buttons to be used in a group.
$form->display_avatar->options = array( 'no'=>'Disabled', 'userimage'=>'Local user image', 'gravatar'=>'Gravatar' ));

The array key will be stored, while the array value will be displayed as the radio button's text. By default, the first radio button is selected. If the value of the group has been stored, that value will be selected.

Select

$myform->append('select','state', 'null:null', _t('State:'));
Class Name
FormSelect
Default Template
formcontrol_select

Optional Fields

options
An array of radio buttons that will be placed in a group.

This can be a one or two dimensional array, or both. e.g.

$options = array(
	'option_value'=>'Option Name',
	'Option Group Label'=>array('option_value_2'=>'Option Name')
);

To select an option, set its value as the formcontrol's value.

$selectioncontrol->value = 'Option Name';


template
The name of the template to use for displaying this control
$myform->append('select','state', 'null:null', _t('State:'), $options_array, 'tabcontrol_select' );

or

$selectioncontrol->template = 'tabcontrol_select';

Alternate Templates

tabcontrol_select
This is used to integrate a select control in areas similar to the tabbed area of the publish page.

File Upload

$form->append('file', 'photo', 'path:' . Site::get_dir('files') . '/photos', 'formcontrol_file');

This adds a file upload control named photo to your form. Unlike other controls that submit data, this control is used to upload a file, so some storage options are different. These take the same format as other storage options, "type:location", and are described below.

silo (not currently implemented)
Based on the uploaded file, a MediaAsset will be created and saved at the silo path specified by "{$location}".
path
The uploaded file will be moved to the specified filesystem path specified by "{$location}".
null
Nothing will be done automatically with the uploaded file when the form is submitted. The temporary file can be accessed through $form->photo->tmp_file. The location in this case is ignored.

(Note: Can any sensible use be made of option:, user:, like setting a banner or an avatar location? In that case, one still might want the uploaded file to be put in a silo. It probably makes sense just to let people who want to do that handle it in code. It might make sense to pass to a plugin hook with action:. session: definitely doesn't make sense.)

Adding this control changes the form's encoding type to multipart/form-data. (Note: Is it a problem that plugins can change the enctype to something else, causing file upload to fail?)

Class Name
FormControlFile
Default Template
formcontrol_file

Static Text

$form->append('static','disclaimer', _t( '<p><em><small>Email address is not published</small></em></p>') );

The static form control lets you add any text or markup to your form.

Text Area

The text area is a standard text input that accepts optional parameters for HTML5 data types.

$form->append( 'textarea', 'blacklist', 'option:simpleblacklist__blacklist', _t( 'Items to blacklist (words, IP addresses, URLs, etc):' ) );

Optional Properties

This control has a number of optional properties that are used when rendering:

class
A string of array of strings to use as the CSS class attribute of the control's div wrapper.
label_title
A string label attribute for the label of the control
for
A string value used as the 'for' attribute of the label
control_title
An explicit string value to use as the title of the control
tabindex
The numeric tab index of the control
size
The numeric size (width in characters) of the text control
maxlength
The numeric maximum length in characters of the value of the control
type
The string type value of the control, defaulting to "text", but can be "email", "url", "datetime", etc. as supported by HTML5.

Text Box

$form->append( 'text', 'list_title', 'option:blogroll__list_title', _t( 'List title: ', 'blogroll' ) );

Text Multi

Creating Custom Controls

Core Validators

validate_url

validate_email

validate_required

validate_username

validate_same

validate_regex

$qty = $form->append('text', 'quantity', 'null:null', 'Quantity: ');
$qty->add_validator('validate_regex', '/^[0-9]*$/', 'Only numbers may be entered for quantity.');

validate_range

This page describes a PHP class that is in the Habari software. For more comprehensive technical information visit the API Documentation.
Other Class Pages
Personal tools