Tribe Settings API

This is documentation for the new TribeSettings API available in The Events Calendar 2.0.5 and up

There are four classes that make up the new Tribe Settings API. All four are located in the /src/Tribe/ folder of the plugin. All four are also bootstrapped and loaded whenever the plugin runs.

Take note that each class represents a level of abstraction. If you are creating a new settings tab, you will be mostly concerned and interested in the fourth class Tribe__Events__Settings_Tab which neatly wraps the other 3 classes into a helpful & easy to use API.

Class TribeSettings

File: /src/Tribe/Settings.php
Description: static helper class that allows registration of settings, instantiation takes place in Tribe__Events__Main.

Class variables:

$instance: (stdClass) singleton method instance var
$tabs: (array) the tabs that will appear in the settings page (filtered on class construct)
$fields: (array) multidimentional array of the fields that will be generated for the entire settings panel, tabs are represented in the array keys
$defaultTab: (string) the default tab for the settings panel, this should be a tab ID
$currentTab: (string) the current tab being displayed
$noSaveTabs: (array) tabs that shouldn’t show the save button
$adminSlug: (string) the slug used in the admin to generate the settings page
$menuName: (string) the menu name used for the settings page
$requiredCap: (string) the required capability for the settings page
$errors: (mixed) errors that occur after a save operation
$saved: (bool) true when just saved
$admin_page: (string) the $current_screen name corresponding to the admin page
$major_error: (bool) true if a major error that prevents saving occurred
$validated: (array) holds validated fields

Action Hooks:

tribe_settings_do_tabs: this is the hook to use to add new tabs (used with the Tribe__Events__Settings_Tab class)
tribe_settings_after_do_tabs: occurs after all tabs are added
tribe_settings_top: occurs before opening <div class=”tribe_settings wrap”> of the settings page
tribe_settings_above_tabs: occurs right above the tabs (below the title)
tribe_settings_below_tabs: occurs right below the tabs
tribe_settings_below_tabs_tab_{$currentTab}: occurs right below the tabs for the specified tab
tribe_settings_above_form_element: occurs above the from element
tribe_settings_above_form_element_tab_{$currentTab}: occurs above the form element for the specified tab
tribe_settings_before_content: occurs after the form element
tribe_settings_before_content_tab_{$currentTab}: occurs after the form element for the specified tab
tribe_settings_content_tab_{$currentTab}: generates the content for the specified tab
tribe_settings_after_content_tab_{$currentTab}: occurs after the content for the specified tab
tribe_settings_after_content: occurs after the content
tribe_settings_after_form_element: occurs after the form element
tribe_settings_after_form_element_tab_{$currentTab}: occurs after the form element for the specified tab
tribe_settings_after_form_div: occurs after the closing form div
tribe_settings_bottom: occurs at the bottom of the settings screen
tribe_settings_after_tabs: occurs after tabs
tribe_settings_validate_before_checks: occurs during validation, before any kind of checks are made
tribe_settings_validate: occurs in validation once the permission, nonce and tab checks are made
tribe_settings_validate_tab_{$currentTab}: same as tribe_settings_validate but for a specific tab
tribe_settings_validate_field: occurs on field validation
tribe_settings_validate_field_{$field_id}: occurs on specific field validation
tribe_settings_save: occurs on save
tribe_settings_save_tab_{$currentTab}: occurs on save for specific tab
tribe_settings_save_field: occurs on field save
tribe_settings_save_field_{$field_id}: occurs on specific field save

Filter Hooks:

tribe_settings_menu_name: filter the settings panel’s menu name
tribe_settings_req_cap: filter the required capability, defaults to manage_options
tribe_settings_admin_slug: filter the admin slug for the settings page
tribe_settings_tabs: filter the tabs for the settings panel
tribe_settings_fields: filter the fields for the settings panel
tribe_settings_default_tab: filter the default tab, defaults to general
tribe_settings_current_tab: filter the current tab, defaults to $_GET[‘tab’]
tribe_settings_no_save_tabs: filter which tabs don’t have the save tab
tribe_settings_form_element: filter the opening form element for the settings panel, defaults to <form method=”post”>
tribe_settings_closing_form_element: filter the closing form element for the settings panel, defaults to </form>
tribe_settings_validate_field_value: filter a field’s value before we validate it
tribe_settings_save_field_value: filter a field’s value before we save it
tribe_settings_save_field_parent_option: filter a field’s parent array option id before saving it
tribe_settings_save_option_array: filter an option array before saving it
tribe_settings_display_errors: filter the $errors array before displaying it
tribe_settings_count_errors: filter how many errors there are before displaying them
tribe_settings_display_errors_or_not: determine whether to display errors or not, defaults to wether the error count is above zero or not
tribe_settings_error_message: filter the full error message
tribe_settings_success_message: filter the success message

Class TribeEventsField

File: /src/Tribe/Field.php
Description: helper class that creates fields for use in Settings, MetaBoxes, Users, anywhere. Instantiate it whenever you need a field

Class variables:

$id: (string) the field’s id
$name: (string) the field’s name (also known as it’s label)
$args: (array) the field’s arguments
$defaults: (array) field defaults (static)
$valid_field_types: (array) the valid field types (static)

Constructor variables:

These variables are passed to the class when it is instantiated, like so:

new Tribe__Events__Field($id, $field, $value = null)

$id: (string) the field’s id
$field: (array) the field object/arguments
$value: (mixed)[optional] the field’s current value

Field Arguments:

These are set with the $args variable. Below are the different arguments with their default value:

‘type’ => ‘html’, the field type
‘name’ => $id, the field’s name attribute (used in $_POST)
‘class’ => null, class to be applied to the field’s <fieldset> element
‘label’ => null, the field’s label
‘tooltip’ => null, the field’s description/label, used in the tooltip as well as in the screen reader label
‘size’ => ‘medium’, (possible values are small, medium or large) this applies to text, text area, dropdown, dropdownchosen and licensekey fields only
‘html’ => null, the html of a field (applies only to an html field)
‘error’ => false, boolean to indicate if the field is currently erroneous or not – this is set via Tribe__Events__Validate
‘value’ => $value, the current value for the field
‘options’ => null, options for the field (this applies to radio, dropdown and dropdown_chosen fields only)
‘conditional’ => true, allows you to set a condition on a field to determine whether it should appear or not, you can pass a function, a variable, whatever you want here, but it expects a boolean value
‘display_callback’ => null, a function name to generate the field with, this would overwrite the class’ behaviour and generate the field with the specified function instead
‘if_empty’ => null, optional message to display for a radio or dropdown button when $options are empty, handy for dynamic fields
‘canbeempty’ => false, allows a field to be saved with an empty value
‘clear_after’ => true, to add a <div class=”clear”></div> after the field or not, defaults to add it

Valid Field Types:

heading: an <h3> wrapped heading
html: arbitrary html code
text: regular text field
textarea: regular text area field
radio: radio buttons
checkbox_bool: single checkbox (true or false)
checkbox_list: checkbox list with options
dropdown: regular <select> dropdown
dropdown_chosen: chosen-enhanced dropdown
license_key: regular text field capable of ajaxing to the right place for license key (note: implementation currently pending)NOTE: more field types will surely be added in future versions of this API

Action Hooks:

None for this class

Filter Hooks:

tribe_valid_field_types: filter valid field types
tribe_field_id: filter the field’s id
tribe_field_{$key}: filter the field’s specified properly
tribe_field_output_{$type}: filter the specified field type’s output
tribe_field_output_{$type}_{$field_id}: filter the specified field’s output
tribe_field_start: filter the field start output
tribe_field_end: filter the field end output
tribe_field_label: filter the field’s label output
tribe_field_div_start: filter the field’s encompassing div’s output
tribe_field_div_end: filter the field’s closing div’s output
tribe_field_tooltip: filter the field’s title attribute output, which is used for the tooltip
tribe_field_screen_reader_label: filter the field’s screen reader label
tribe_field_value: filter the field’s value attribute
tribe_field_name: filter the field’s name attribute

Class TribeEventsValidate

File: /src/Tribe/Validate.php
Description: helper class that validates fields for use in Settings, MetaBoxes, Users, anywhere. Instantiate whenever you want to validate a field

Class variables:

$field: (array), the field object to validate
$value: (mixed), the field’s value
$additional_args: (array) additional arguments for validation – used by some methods only
$label: (string), the field’s label, used in error messages
$type: (string), the type of validation to perform
$result: (stdClass), the result object of the validation

Valid Validation Types:

positive_int: validates & sanitizes fields as being positive integers
slug: validates & sanitizes fields as URL slugs
url: validates & sanitizes fields as URLs
options: validates fields that have options (radios, dropdowns, etc.) by making sure the value is part of the options array
cannot_be_the_same_as: validates & sanitizes fields as not being able to be the same as the specified value, use the $additional_args[‘compare’] to pass the value to compare against, use the $additional_args[‘compare_name’] to pass the name of what you are comparing against (for the error message)
number_or_percent: validates fields as being a number or a percentage
html: sanitizes an html field
license_key: validates & sanitizes a license key
textarea: sanitizes a textarea field
boolean: sanitizes fields as being a boolean
google_maps_zoom: validates a google map zoom level
address: validates fields as being part of an address, allows for letters, numbers, dashses and spaces only
city_or_province: validates fields as being a city or province, allows for letters, dashses and spaces only
zip: validates fields as being a zip code
phone: validates fields as being a phone number
country_list: validates & sanitizes a field as being a country list
none: automatically validate a field regardless of the value. Don’t use this unless you know what you are doingNOTE: more validation types will surely be added in future versions of this API

Action Hooks:

None for this class

Filter Hooks:

None for this class

Class TribeEventsSettings_Tab

File: /src/Tribe/Settings_Tab.php
Description: helper class that creates a settings tab; this is a public API, use it to create tabs simply by instantiating this class

Class variables:

$id: (string) Tab ID, used in query string and elsewhere
$name: (string) Tab’s name
$args: (array) Tab’s arguments
$defaults: (array) Defaults for tabs

Action Hooks:

None for this class

Filter Hooks:

tribe_settings_tab_id: filters the tab ID
tribe_settings_tab_name: filter the tab name
tribe_settings_tab_{$field_id}: filters the specified tab property
tribe_settings_do_content_parent_option: filters the parent option for a field
tribe_settings_field_default: filters the default for a field
tribe_settings_get_option_value_pre_display: filters the value before giving it to the Tribe__Events__Field class

Default Arguments:

Below are the default arguments with an explanation for each, these are passed via $args.

‘fields’ => array(), the fields for the tab
‘priority’ => 50, the priority of a tab – this will determine the placement of the tab, see below for a more in-depth explanation
‘show_save’ => true, whether to show the save button on this tab
‘display_callback’ => false, a function name to generate the tab’s content instead of the default behaviour

Priority:

The priority argument is passed to the tribe_settings_tabs filter which is run via the addTab() function, like so: add_filter(‘tribe_settings_tabs’, array($this, ‘addTab’), $priority );

The Event Calendar’s tabs have the following priorities:

General: 10
Template: 20
Defaults (pro only): 30
Licenses (pro and add-ons only): 40
Help: 60

This allows you to add new tabs anywhere in between, for example, a priority of 9 would insert your tab right before General, whereas a priority of 35 would insert it right after Defaults, etc.

Fields:

The Tribe__Events__Settings_Tab class processes 2 extra parameters for fields above and beyond those of Tribe__Events__Field. The extra parameters are parent_option and allows you to set under what option the specified field will save (aka as part of a serialized array), and default, used to set a default value if one isn’t present.

By default, the parent_option parameter will be set to Tribe__Events__Main::OPTIONNAME, aka the default option for The Events Calendar. If you leave parent_option blank when registering your field, it will save under this default.

You can specify a field to save as it’s own stand-alone option by setting parent_option to false.

You can set parent_option to any other string value, and the field will save as part of a serialized array under the specified option name.

Setting the default param is important for options that are required.

Usage Example:

The following example inserts a new tab called General. Every field saves to the Tribe__Events__Main::OPTIONNAME serialized array.

Take note of the tribe_settings_do_tabs hook which is used to add the tab.

Class TribeSettings

Class Tribe__Events__Field

Class Tribe__Events__Validate

Class Tribe__Events__Settings_Tab

Class TribeEventsField

Class TribeEventsValidate

Class TribeEventsSettings_Tab