Options Builder Fields

Theme options are created using the Options Builder with it’s drag-and-drop user interface. Each field can be configured as needed for the intended purpose in your theme options. This includes setting the field values, required fields and validating the submitted data.

Options Builder Edit Screen

The following fields are pre-defined for use with the Options Builder.

  • Checkbox (true/false)
  • Checkbox list
  • Colorpicker
  • Datepicker
  • File upload
  • Input text
  • Multiselect
  • Image radio buttons
  • Radio buttons
  • Select
  • Text editor
  • Textarea

All fields above are defined as a custom classes extending the Data_Type() class. The default Data Types are saved in the runway-framework/data-types folder. Custom Data Types can be created and saved to this same folder. By defining custom Data Types a developer can build theme options including specialized inputs, field validation or other custom theme features.

Field settings

Each field has standard settings to define how it will be displayed in a theme options page. The following settings will exist for all fields in the Options Builder.

Field Settings Modal Window

Title

The displayed title of the filed in the theme options page.

Title caption

A caption shown below the title.

Alias

Used to register the filed with Runway and retrieve the saved data. An alias should not have any spaces or special characters. A descriptive alias can be useful, such as ‘heading-font-color’ for a color picker used to set the color of H1-H6 tags.

Field type

Sets the field type to be used. Any data type registered with the Runway install will be automatically listed here.

Values

Your custom values for the input. When using a text field this will become the default value of the field before users have saved their settings. Some data types can accept multiple values and will be displayed as multiple lines with key=>value pairs. This area and the options will change based on the data type selected in the “Field type” setting.

Required

A checkbox for setting a field as required. The default is for fields to be options. A required field will produce an error message for the user if they do not enter a value for the field.

Required Error Message

An optional custom error message to show the user if they don’t provide a value for a required field.

Validation

Optional validation method to apply to the submitted value. Each filed will have custom validation methods specific to that field. Not all fields have validation methods.

Validation Error Message

An optional custom error message to show the user if the validation fails.

Standard fields

All of these fields (Data Types) are available when creating or editing a custom field in Runway > Options Builder, and also when creating or editing custom fields for Headers, Footers and Layout Options in Appearance > Layout Manager > Custom Fields.

Checkbox (true/false)

Returns true or false – depending on the setting of the “Checked” option.

Options builder settings:

Checkbox (true/false)

Appearance in theme options:

Checkbox in Theme Options

Checkbox list

Specify the options using a list of key=>values pairs in the format below with one pair on each line.

Example values:

1=>English
2=>French
3=>German
4=>Russian

Example values using custom keys:

en-us=>English
fr=>French
de=>German
ru=>Russian

Options builder settings:

Checkbox List

Appearance in theme options:

Checkbox List in Theme Options

Colorpicker

Accepts the value of the selected color in HEX format, #FF0077 or shorthand #F07.

Options builder settings:

Colorpicker

Appearance in theme options:

Colorpicker in Theme Options

Datepicker

Accepts the chosen date in the selected format.

Options builder settings:

Datepicker

Appearance in theme options:

Datepicker in Theme Options

File upload

Select and upload files and images. Accepts a full path to the file to be uploaded or an existing uploaded file.

Options builder settings:

File upload

Appearance in theme options:

File Upload in Theme Options

Input text

Accepts the text entered into the input box.

Validation methods
  • None – No validation. (default)
  • URL – Check for a valid URL string.
  • Email – Checks for a valid email address.
  • Alpha – Only alphabetic characters. (A-Z and a-z)
  • Alpha num – Alphabetic and numeric characters. (A-Z, a-z and 0-9)
  • Numeric – Only numeric characters. (0-9)
Validation error message

Optionally enter a custom error message to display if the validation method fails.

Options builder settings:

Input text

Appearance in theme options:

Input Text in Theme Options

Multiselect

Specify the options using a list of key=>values pairs in the format below with one pair on each line.

Example values:

1=>Salt
2=>Vinegar
3=>Mustard
4=>Pepper

Example values using custom keys:

salt-and-pepper=>Salt and Pepper
oil-and-vinegar=>Oil and Vinegar
ketchup-and-mustard=>Ketchup and Mustard
fish-n-chips=>Fish n Chips

Options builder settings:

Multiselect

Appearance in theme options:

Multiselect in Theme Options

Image radio buttons

Specify the options using a list of key=>image or key=>image=>description sets in the format below with one set on each line. The image should be a URL for the radio button image.

Example values:

1=>http://example.com/image-1.png
2=>http://example.com/image-2.png
3=>http://example.com/image-3.png

Example values with optional text descriptions:

1=>http://example.com/image-1.png=>Image One
2=>http://example.com/image-2.png=>Image Two
3=>http://example.com/image-3.png=>Image Three

Options builder settings:

Image radio buttons

Options page appearance:

Image Radio Buttons in Theme Options

Radio buttons

Specify the options using a list of key=>value pairs in the format below with one pair on each line.

Example values:

blink=>Chrome or Opera
gecko=>Mozilla Firefox
trident=>Internet Explorer
webkit=>Safari
khtml=>Konqueror

Options builder settings:

Radio buttons

Appearance in theme options:

Radio Buttons in Theme Options

Select

Specify the options using a list of key=>value pairs in the format below with one pair on each line.

Example values:

google=>Chrome
microsoft=>Internet Explorer
apple=>Safari
mozilla=>Firefox
opera-software=>Opera

Options builder settings:

Select

Appearance in theme options:

Select in Theme Options

Text editor

Text editing in Visual and Text modes, accepts the contents of the text editor window.

Options builder settings:

Text editor

Appearance in theme options:

Text Editor in Theme Options

Textarea

Creates a simple multi-line text area.

Options builder settings:

Textarea

Appearance in theme options:

Textarea in Theme Options

Custom fields

The fields in the Options Builder are a feature of the FormsBuilder() class. Using this class it is easy to add the Options Builder interface and functionality to a custom Extension. An example of this can be seen in the Layout Manager extension where the header and footer options make use of the Forms Builder class.

Each of the Options Builder “fields”, also called “Data Types”, extends the core Data_Type() class that is inherited from the WordPress WP_Customize_Control() class. This enables any Data Type to also be set via the Appearance > Customize feature of the WordPress Theme Customizer screen.

The fields are stored in the Runway sub-folder runway-framework/data-types and, much like a WordPress plugin, anything added to this folder with the proper comment header will be read by the framework and automatically included into the Options Builder for use in theme options pages.

You can easily duplicate an existing field in the runway-framework/data-types folder, give it a custom name, modify it for your custom purpose and drop it back in the folder to instantly have a specialized input.

A quick example of a specialized field might be a select input for choosing a font face. This could include options for Google web fonts, Adobe Edge fonts and a list of standard web-safe fonts. The settings in the Options Builder could allow developers to select between these three font sources for displaying as options to the end user in their theme options page.

There are many ways you might extend the Options Builder with custom data-types. Runway makes it easy to use the default fields included, or create custom fields for your specific needs.

Create a Note

Google+