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.
WYSIWYG Editors
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 https://www.dropbox.com/developers/apps 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
valuesproperty - The read_only, current_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.
