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 /lib
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 TribeSettingsTab
which neatly wraps the other 3 classes into a helpful & easy to use API.
- File:
/lib/tribe-settings.class.php
- Description: static helper class that allows registration of settings, instantiation takes place in
TribeEvents
.
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 theTribeSettingsTab
class)tribe_settings_after_do_tabs
: occurs after all tabs are addedtribe_settings_top
: occurs before opening<div class="tribe_settings wrap">
of the settings pagetribe_settings_above_tabs
: occurs right above the tabs (below the title)tribe_settings_below_tabs
: occurs right below the tabstribe_settings_below_tabs_tab_{$currentTab}
: occurs right below the tabs for the specified tabtribe_settings_above_form_element
: occurs above the from elementtribe_settings_above_form_element_tab_{$currentTab}
: occurs above the form element for the specified tabtribe_settings_before_content
: occurs after the form elementtribe_settings_before_content_tab_{$currentTab}
: occurs after the form element for the specified tabtribe_settings_content_tab_{$currentTab}
: generates the content for the specified tabtribe_settings_after_content_tab_{$currentTab}
: occurs after the content for the specified tabtribe_settings_after_content
: occurs after the contenttribe_settings_after_form_element
: occurs after the form elementtribe_settings_after_form_element_tab_{$currentTab}
: occurs after the form element for the specified tabtribe_settings_after_form_div
: occurs after the closing form divtribe_settings_bottom
: occurs at the bottom of the settings screentribe_settings_after_tabs
: occurs after tabstribe_settings_validate_before_checks
: occurs during validation, before any kind of checks are madetribe_settings_validate
: occurs in validation once the permission, nonce and tab checks are madetribe_settings_validate_tab_{$currentTab}
: same astribe_settings_validate
but for a specific tabtribe_settings_validate_field
: occurs on field validationtribe_settings_validate_field_{$field_id}
: occurs on specific field validationtribe_settings_save
: occurs on savetribe_settings_save_tab_{$currentTab}
: occurs on save for specific tabtribe_settings_save_field
: occurs on field savetribe_settings_save_field_{$field_id}
: occurs on specific field save
Filter Hooks:
tribe_settings_menu_name
: filter the settings panel's menu nametribe_settings_req_cap
: filter the required capability, defaults tomanage_options
tribe_settings_admin_slug
: filter the admin slug for the settings pagetribe_settings_tabs
: filter the tabs for the settings paneltribe_settings_fields
: filter the fields for the settings paneltribe_settings_default_tab
: filter the default tab, defaults togeneral
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 tabtribe_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 ittribe_settings_save_field_value
: filter a field's value before we save ittribe_settings_save_field_parent_option
: filter a field's parent array option id before saving ittribe_settings_save_option_array
: filter an option array before saving ittribe_settings_display_errors
: filter the$errors
array before displaying ittribe_settings_count_errors
: filter how many errors there are before displaying themtribe_settings_display_errors_or_not
: determine whether to display errors or not, defaults to wether the error count is above zero or nottribe_settings_error_message
: filter the full error messagetribe_settings_success_message
: filter the success message
- File:
/lib/tribe-field.class.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 TribeField($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, dropdown_chosen and license_key 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
TribeValidate
- '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 - 'can_be_empty' => 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 typestribe_field_id
: filter the field's idtribe_field_{$key}
: filter the field's specified properlytribe_field_output_{$type}
: filter the specified field type's outputtribe_field_output_{$type}_{$field_id}
: filter the specified field's outputtribe_field_start
: filter the field start outputtribe_field_end
: filter the field end outputtribe_field_label
: filter the field's label outputtribe_field_div_start
: filter the field's encompassing div's outputtribe_field_div_end
: filter the field's closing div's outputtribe_field_tooltip
: filter the field'stitle
attribute output, which is used for the tooltiptribe_field_screen_reader_label
: filter the field's screen reader labeltribe_field_value
: filter the field's value attributetribe_field_name
: filter the field's name attribute
- File:
/lib/tribe-validate.class.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
- File:
/lib/tribe-settings-tab.class.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 IDtribe_settings_tab_name
: filter the tab nametribe_settings_tab_{$field_id}
: filters the specified tab propertytribe_settings_do_content_parent_option
: filters the parent option for a fieldtribe_settings_field_default
: filters the default for a fieldtribe_settings_get_option_value_pre_display
: filters the value before giving it to theTribeField
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 TribeSettingsTab
class processes 2 extra parameters for fields above and beyond those of TribeField
. 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 TribeEvents::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 TribeEvents::OPTIONNAME
serialized array,.
Take note of the tribe_settings_do_tabs
hook which is used to add the tab.
<?php
add_action('tribe_settings_do_tabs', 'tribe_add_general_tab');
function tribe_general_setting_tabs() {
$generalTab = array(
'priority' => 10,
'fields' => array(
'upsell-heading' => array(
'type' => 'heading',
'label' => __('Additional Functionality', 'tribe-events-calendar'),
'conditional' => ( !defined('TRIBE_HIDE_UPSELL') || !TRIBE_HIDE_UPSELL ),
),
'upsell-info' => array(
'type' => 'html',
'html' => '<p>'.__('Looking for additional functionality including recurring events, custom meta, community events, ticket sales and more?', 'tribe-events-calendar' ).'</p>'.'<p>'.sprintf(__('Check out the %s.', 'tribe-events-calendar' ), '<a href="'.self::$tribeUrl.'?ref=tec-options'.'">'.__('available Add-Ons', 'tribe-events-calendar').'</a>').'</p>',
'conditional' => ( !defined('TRIBE_HIDE_UPSELL') || !TRIBE_HIDE_UPSELL ),
),
'ical-heading' => array(
'type' => 'heading',
'label' => __('iCal', 'tribe-events-calendar'),
'conditional' => function_exists('tribe_get_ical_link'),
),
'ical-info' => array(
'type' => 'html',
'html' => (function_exists('tribe_get_ical_link')) ? '<p>'.__('Here is the iCal feed URL for your events:', 'tribe-events-calendar').' '.'<code>'.tribe_get_ical_link().'</code></p>' : '',
'conditional' => function_exists('tribe_get_ical_link'),
),
'donate-link' => array(
'type' => 'checkbox_bool',
'label' => __('Donate a link', 'tribe-events-calendar'),
'default' => false,
'validation_type' => 'boolean',
'clear_after' => false,
),
'donate-link-tooltip' => array(
'type' => 'html',
'html' => '<div id="donate-link-tooltip" class="wp-pointer-left tribe-tooltip"><div class="wp-pointer-content"><p class="tribe-tooltip-inner"><p>'.__('Are you thinking "Wow, this plugin is amazing! I should say thanks to tribe for all their hard work." The greatest thanks we could ask for is recognition. Check this box to add a small text only link at the bottom of your calendar pointing to the events calendar project.', 'tribe-events-calendar').'<br><br><img src="'.$this->pluginUrl.'/resources/images/donate-link-screenshot.png"></p></div><div class="wp-pointer-arrow"><div class="wp-pointer-arrow-inner"></div></div></div>',
),
'settings-heading' => array(
'type' => 'heading',
'label' => __('Settings', 'tribe-events-calendar'),
),
'viewOption' => array(
'type' => 'radio',
'label' => __('Default view for the Events', 'tribe-events-calendar'),
'tooltip' => __('Determines whether the default events view is a calendar or a list', 'tribe-events-calendar'),
'default' => 'month',
'options' => array('month' => 'Calendar', 'upcoming' => 'Event List'),
'validation_type' => 'options'
),
'eventsSlug' => array(
'type' => 'text',
'label' => __('Events URL slug', 'tribe-events-calendar'),
'tooltip' => __('The slug used for building the Events URL', 'tribe-events-calendar'),
'default' => 'events',
'validation_type' => 'slug',
'conditional' => ( '' != get_option('permalink_structure') ),
),
'slug-info' => array(
'type' => 'html',
'html' => '<p class="tribe-field-indent">'.sprintf( __('Your current Events URL is %s', 'tribe-events-calendar' ), '<strong><a href="'.tribe_get_events_link().'">'.tribe_get_events_link().'</a></strong>' ).'</p>',
'conditional' => ( '' != get_option('permalink_structure') ),
),
'singleEventSlug' => array(
'type' => 'text',
'label' => __('Single Event URL slug', 'tribe-events-calendar'),
'tooltip' => __('The slug used for building a single Event URL.', 'tribe-events-calendar', 'tribe-events-calendar'),
'default' => 'event',
'validation_type' => 'slug',
'conditional' => ( '' != get_option('permalink_structure') ),
),
'single-slug-info' => array(
'type' => 'html',
'html' => '<p class="tribe-field-indent">'.sprintf( __('<strong>NOTE:</strong> You <em>cannot</em> use the same slug as above. The above should ideally be plural, and this singular.<br />Your single Event URL is like: <strong>%s</strong>', 'tribe-events-calendar' ), trailingslashit( home_url() ) . tribe_get_option('singleEventSlug', 'event') . '/single-post-name/' ).'</p>',
'conditional' => ( '' != get_option('permalink_structure') ),
),
'postsPerPage' => array(
'type' => 'text',
'label' => __('Number of events to show per page in the loop', 'tribe-events-calendar'),
'tooltip' => __('This is the number of events displayed per page when returning a list of events', 'tribe-events-calendar'),
'size' => 'small',
'default' => get_option('posts_per_page'),
'validation_type' => 'positive_int',
),
'showComments' => array(
'type' => 'checkbox_bool',
'label' => __('Show Comments', 'tribe-events-calendar'),
'default' => false,
'validation_type' => 'boolean'
),
'multiDayCutoff' => array(
'type' => 'dropdown',
'label' => __('Multiday Event Cutoff', 'tribe-events-calendar'),
'tooltip' => __('This is the number of events displayed per page when returning a list of events', 'tribe-events-calendar'),
'validation_type' => 'options',
'size' => 'small',
'default' => '12:00',
'options' => array('12:00' => '12:00 am', '12:30' => '12:30 am', '01:00' => '01:00 am', '01:30' => '01:30 am', '02:00' => '02:00 am', '02:30' => '02:30 am', '03:00' => '03:00 am', '03:30' => '03:30 am', '04:00' => '04:00 am', '04:30' => '04:30 am', '05:00' => '05:00 am', '05:30' => '05:30 am', '06:00' => '06:00 am', '06:30' => '06:30 am', '07:00' => '07:00 am', '07:30' => '07:30 am', '08:00' => '08:00 am', '08:30' => '08:30 am', '09:00' => '09:00 am', '09:30' => '09:30 am', '10:00' => '10:00 am', '10:30' => '10:30 am', '11:00' => '11:00 am', '11:30' => '11:30 am'),
),
'googleEmbedSize' => array(
'type' => 'checkbox_bool',
'label' => __('Enable Google Maps', 'tribe-events-calendar'),
'tooltip' => __('If you don\'t have this turned on, your event listings won\'t have the backend map preview or frontend embedded map.', 'tribe-events-calendar'),
'default' => false,
'class' => 'google-embed-size',
'validation_type' => 'boolean'
),
'embedGoogleMapsHeight' => array(
'type' => 'text',
'label' => __('Google Maps Embed Height', 'tribe-events-calendar'),
'size' => 'small',
'default' => 350,
'class' => 'google-embed-field',
'validation_type' => 'number_or_percent',
),
'embedGoogleMapsWidth' => array(
'type' => 'text',
'label' => __('Google Maps Embed Width', 'tribe-events-calendar'),
'size' => 'small',
'tooltip' => __('number or %', 'tribe-events-calendar'),
'default' => '100%',
'class' => 'google-embed-field',
'validation_type' => 'number_or_percent',
),
'embedGoogleMapsZoom' => array(
'type' => 'text',
'label' => __('Google Maps Default Zoom Level', 'tribe-events-calendar'),
'tooltip' => __('0 = zoomed-out; 21 = zoomed-in', 'tribe_events_calendar'),
'size' => 'small',
'default' => 10,
'class' => 'google-embed-field',
'validation_type' => 'number_or_percent',
),
'debugEvents' => array(
'type' => 'checkbox_bool',
'label' => __('Debug Mode', 'tribe-events-calendar'),
'tooltip' => sprintf( __('Enable this option to log debug information. By default this will log to your server PHP error log. If you\'d like to see the log messages in your browser, then we recommend that you install the %s and look for the "Tribe" tab in the debug output.', 'tribe-events-calendar'), '<a href="http://wordpress.org/extend/plugins/debug-bar/" target="_blank">'.__('Debug Bar Plugin', 'tribe-events-calendar').'</a>' ),
'default' => false,
'validation_type' => 'boolean'
),
),
);
new TribeSettingsTab( 'general', __('General', 'tribe-events-calendar'), $generalTab);
}