Fieldtypes

Create new ways for admins to enter data.

A fieldtype lets you create a way for users to input data into the Control Panel. For example, location is an add-on with a fieldtype. This aspect is the most complex of the four, as it has the most requirements and things to understand.

Creating a Fieldtype

The first step to creating a fieldtype is creating the file containing the object that will define the fieldtype itself. This file will be named after your add-on, for example, if your add-on is in a folder called backpack, your fieldtype file will be ft.backpack.php. The ft is for fieldtype. This file goes into the root-level of your add-on’s folder.

Next, within that file we need to create an object that extends Statamic’s Fieldtype object. The name of the object must be Fieldtype_ followed by the name of your add-on, like so:

class Fieldtype_backpack extends Fieldtype
{

}

How Fields are Rendered

A fieldtype is rendered by combining four different parts:

1. The field’s label
2. The field’s “above” instructions
3. The field itself
4. The field’s “below” instructions

The only thing that you must define is how the field itself will render. The rest of these options come with default values that you can optionally overwrite.

Rendering Labels

To render your own field label, you’ll define the render_label method. By default, this method returns an HTML label tag using $this->field_id as the for attribute. The text within will be what was set for this field’s display configuration (as set in the fieldset).

Rendering Instructions

You’re probably best leaving the instructions-rendering alone. There are two methods that handle rendering instructions: render_instructions_above and render_instructions_below. The tricky part comes in where Statamic allows users to enter either instructions as a named-list (with “above” and “below”), or just define instructions as a string, in which case this value will be used as “above” instructions.

Rendering Your Field

This is the only required method to define for a fieldtype. Defining your field is done by returning the HTML for your fields from the render method.

class Fieldtype_backpack extends Fieldtype
{
   public function render()
   {

   }
}

Fieldtype comes with a couple of properties that you may find to be quite useful.

• $this->field_id is a random string that can be used as the HTML id of your field, the render_label method will use this value by default
• $this->field_data is the current value of your field — it will be null on a new form, and will contain the saved value during a form edit

Render Order

The render_field method is essentially a wrapper that determines the order of the items rendered for a given fieldtype. The default order is listed above, but can be altered per fieldtype. To do this, overwrite render_field in your fieldtype returning the items in the order you choose, for example:

public function render_field()
{
   return $this->render_instructions_above() .
          $this->render_label() .
          $this->render() .
          $this->render_instructions_below();
}

The above code would print the label after your “above” instructions, but just for your fieldtype. Best practice is to leave the default order unless you have a very good reason to do so.