Custom Field Types

When the default field types don't fit your needs, BigTree also makes it easy to create new types. Any valid HTML input type can be used as the basis for a BigTree form field.

To create a new field type, navigate to Developer > Field Types > Add Field Type. This screen requires only three pieces of information to create a field type: an ID that must be unique among all field types, a Name, and a selection of Use Cases, enabling your field to be used in templates, modules, settings, and callouts.

When you click "Create," BigTree will create three files for your field type.

custom/admin/form-field-types/draw/field_id.php contains the code to draw your field in the BigTree admin.

custom/admin/form-field-types/process/field_id.php is used to process field input before it is saved in the database. The default process file is one line: <? $field["output"] = $field["input"]; ?>.

custom/admin/ajax/developer/field-options/field_id.php is where you can set options for your form field — use when drawing it in BigTree forms.

Environment

In each of the files you are presented with a different environment in which to work:

Drawing

In your drawing file (custom/admin/form-field-types/draw/field_id.php) you are expected to draw the form field elements aside from the <fieldset> and <label> which are drawn for you. You are provided with the $field array which provide the following key/value pairs:

  • "title" — The title given by the developer to draw as the label (drawn automatically)
  • "subtitle" — The subtitle given by the developer to draw as the smaller part of the label (drawn automatically)
  • "key" — The value you should use for the "name" attribute of your form field
  • "value" — The existing value for this form field
  • "id" — A unique ID you can assign to your form field for use in JavaScript
  • "tabindex" — The current tab index you can use for the "tabindex" attribute of your form field
  • "options" — An array of options provided by the developer
  • "required" — A boolean value of whether this form field is required or not

You are also provided with the $bigtree environment variable — The BigTree environment variable contains "datepickers", "timepickers", "datetimepickers", "html_fields", and "simple_html_fields" — adding your $field["id"] to one of these arrays will initiate the JavaScript for the related array on your field.

Processing

In your processing file (custom/admin/form-field-types/process/field_id.php) you are expected to process the POST data you receive and update $field["output"] with the value to store in the database.

$field — The field environment variable with the following key/value pairs:

  • "key" — The key of the field (this could be the database column for a module or the ID of the template or callout resource)
  • "options" — An array of options provided by the developer
  • "input" — The end user's $_POST data input for this field
  • "file_input" — The end user's uploaded files for this field in a normalized entry from the $_FILES array in the same formatting you'd expect from "input"
  • "ignore" — Whether to ignore this field (if set to true, the field is not stored in the database)
  • "output" — The value to store in the database.

$bigtree — The BigTree environment variable contains several important keys:

  • "post_data" — The array of $_POST information that you can retrieve the user's submitted values for other fields from. You should not use $_POST directly because your value may actually be in $_POST["callouts"][0][$key] or something similar.
  • "crops" — An array of crops for the current entry. You should add cropping arrays to this array. See /core/admin/form-field-types/_photo-process.php for usage of the crop information arrays.
  • "many_to_many" — An array containing many to many entries. You should add many to many information to this array. See /core/admin/form-field-types/many_to_many.php for information on many to many arrays.
  • "fails" — An array containing a list of failures. You can see an example of adding failures to this array in /core/admin/form-field-types/_photo-process.php.
  • "entry" — The entry array that is being created for storage in the database. You can modify this to change other columns. See /core/admin/form-field-types/geocoding.php for an example of this occurring.

Options

Your options file (custom/admin/ajax/developer/field-options/field_id.php) is where you'll setup your form elements for populating your $options array in the draw/process files. You simply draw form elements and use the "name" attribute to correspond to the key of the element you wish to set in $options. You have the following environment variables:

  • $data — The array of currently set options for the field type.

For more on custom field types, check out our tutorial.