Defining Fields in an Admin Box Tab

Fields are used to display things on an Admin Box, and to allow an administrator to enter information.

Fields must be defined as belonging to a specific tab, and will only be displayed when that tab is selected.

Even if you don't want to use tabs in your admin box, you will still need to define one tab to place your fields on. (If you don't wish this to be visible then you can always hide the tab bar.)

Different types of field

There are four main categories of field (which are mutually exclusive, e.g. a field cannot be both a HTML Snippet and a text field):

HTML Snippets

If you set the snippet property, you can add some static html to your Admin Box instead of an editable field. This can be used for descriptions, help text, or adding bespoke widgets that can't be done natively by the toolkit.

Note that snippets are not editable fields and are not considered to have a "value"; you will not see an entry for snippets in the $values array in your PHP methods.

Standard HTML fields

If you set the type property, you will be able to add one of several standard HTML fields, e.g. a text field.


If you set the type property to "editor", you will be able to create a WYSIWYG Editor. This works like a normal text field in terms of loading and saving data, but be aware the data will be in HTML format.

File Uploads and Organizer Pickers

If you set the upload property you can create a file-upload field, that allows administrators to upload one or multiple files. If the site has an API key from administrators can also choose files from their Dropbox accounts.

If you set the pick_items property then you can create an Organizer picker that allows administrators to select items from an Organizer panel.

If the items that you are selecting are files, you can also set both of these properties on the same field.

Different Properties for different categories of Field

Note that several properties will only work for certain categories or types of fields, e.g.:

  • Checkboxes, radiogroups and select lists require the values property
  • The read_onlycurrent_value and redraw_onchange properties do not work for HTML Snippets
  • The insert_link_button property only applies to WYSIWYG Editors

Some other special cases

If you have a date or a datetime field, you should provide the time in the standard "MySQL" format. However this will be formatted to a more user-friendly format (as defined in the site settings).

Date fields are implemented using jQuery date-pickers.

Datetime fields are always shown in readonly mode and cannot be changed. If you need to input a datetime we suggest you use a date field and then two select lists for hours and minutes.

A "type: hidden" field works differently to "type: text" fields that are set to  "hidden: true". A "type: hidden" field is still drawn on the page as HTML and its value can still be changed using JavaScript. If you use a "type: hidden" field we recommend that you set the same_row property as well to avoid empty rows in your Admin Boxes.

Reference for fields: