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 Tribe__Events__Field

• 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 Tribe__Events__Validate

• 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 Tribe__Events__Settings_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.