Documentation

WP_Backstage_Component
in package

WPBackstage

WP Backstage Component

$args

Args


    protected
        array<string|int, mixed>
    $args
     = array()

The array of args on the instance.

$countries

Countries


    protected
        array<string|int, mixed>
    $countries
     = array()

An array of localized countries.

$date_format

Date Format


    protected
        string
    $date_format
     = ''

The php date format.

$default_address_args

Default Address Args


    protected
        array<string|int, mixed>
    $default_address_args
     = array('max_width' => '100%')

An array of default address arguments.

$default_address_values

Default Address Values


    protected
        array<string|int, mixed>
    $default_address_values
     = array('country' => 'US', 'address_1' => '', 'address_2' => '', 'city' => '', 'state' => 'AL', 'zip' => '')

An array of default address field arguments.

$default_code_args

Default Code Args


    protected
        array<string|int, mixed>
    $default_code_args
     = array('settings_key' => '', 'mime' => 'text/html', 'max_width' => '100%')

An array of default code editor arguments.

$default_color_args

Default Color Args


    protected
        array<string|int, mixed>
    $default_color_args
     = array(
    'mode' => '',
    // hsl, hsv.
    'palettes' => \true,
)

An array of default color field arguments.

$default_date_args

Default Date Args


    protected
        array<string|int, mixed>
    $default_date_args
     = array('format' => 'yy-mm-dd')

An array of default date field arguments.

$default_editor_args

Default Editor Args


    protected
        array<string|int, mixed>
    $default_editor_args
     = array('max_width' => '100%', 'format_select' => \false, 'media_buttons' => \false, 'kitchen_sink' => \false)

An array of default editor field arguments.

$default_field_args

Default Field Args


    protected
        array<string|int, mixed>
    $default_field_args
     = array('id' => '', 'type' => 'text', 'name' => '', 'label' => '', 'title' => '', 'value' => \null, 'disabled' => \false, 'description' => '', 'help' => '', 'show_label' => \true, 'show_in_rest' => \false, 'options' => array(), 'input_attrs' => array(), 'args' => array())

An array of default field args.

$default_filter_control_args

Default Filter Control Args


    protected
        array<string|int, mixed>
    $default_filter_control_args
     = array('id' => '', 'name' => '', 'value' => \null, 'label' => '', 'option_none_label' => '', 'options' => array())

The default filter control args for this instance.

$default_media_uploader_args

Default Media Uploader Args


    protected
        array<string|int, mixed>
    $default_media_uploader_args
     = array('type' => '', 'multiple' => \false, 'attach' => \false)

An array of default media field arguments.

$default_option_args

Default Option Args


    protected
        array<string|int, mixed>
    $default_option_args
     = array('value' => '', 'label' => '', 'disabled' => \false)

An array of default option arguments.

$default_select_posts_args

Default Select Posts Args


    protected
        array<string|int, mixed>
    $default_select_posts_args
     = array('option_none_label' => '', 'query' => array('posts_per_page' => -1, 'post_type' => 'page', 'post_status' => 'any'))

An array of default select posts arguments.

$default_select_users_args

Default Select Users Args


    protected
        array<string|int, mixed>
    $default_select_users_args
     = array('option_none_label' => '', 'query' => array('number' => -1, 'count' => \false))

An array of default select users arguments.

$errors

Errors


    protected
        array<string|int, mixed>
    $errors
     = array()

The array of all errors on the instance.

$filterable_fields

Filterable Fields


    protected
        array<string|int, mixed>
    $filterable_fields
     = array('select', 'radio', 'select_posts', 'select_users')

Field types that should have the for attribute removed labels.

$global_code_settings

Global Code Settings


    protected
        array<string|int, mixed>
    $global_code_settings
     = array('codemirror' => array('lineWrapping' => \false))

Global settings for CodeMirror.

$non_regular_text_fields

Non Regular Text Fields


    protected
        array<string|int, mixed>
    $non_regular_text_fields
     = array('number', 'textarea', 'editor', 'select', 'checkbox', 'checkbox_set', 'radio', 'media', 'code', 'date', 'time', 'address', 'select_posts', 'select_users')

Field types that do not include text-style inputs.

$nonce_key

Nonce Key


    protected
        string
    $nonce_key
     = '_wp_backstage_nonce'

The key for nonce fields.

$remove_label_for_fields

Remove Label For Fields


    protected
        array<string|int, mixed>
    $remove_label_for_fields
     = array('radio', 'checkbox_set', 'time', 'address')

Field types that should have the for attribute removed labels.

$screen_id

Screen ID


    protected
        string|array<string|int, mixed>
    $screen_id
     = ''

The screen ID or IDs that apply to this instance.

$slug

Slug


    protected
        string
    $slug
     = ''

This is the main text identifier of the instance. It is alpha-numeric and only contains lowercase letters, underscores and hyphens. The slug is used when building nonces, creating dynamic hooks, and registering post types, taxonomies, and options pages. Note that on instances of WP_Backstage_User, the slug is set to user. The slug is sanitized using WordPress's sanitize_key() function that is used when sanitizing slugs.

the text slug that identifies the instance.

$textarea_control_fields

Textarea Control Fields


    protected
        array<string|int, mixed>
    $textarea_control_fields
     = array('textarea', 'editor', 'code')

Field types that use a textarea input as a control.

$time_pieces

Time Pieces


    protected
        array<string|int, mixed>
    $time_pieces
     = array()

This configuration is used in order to create the 3 <select> fields needed to create a time string as 00:00:00. This will register the localized label and set the number of options that are necessary for each time piece (hour, minute, second) respectively.

The configuration for time fields.

$us_states

US States


    protected
        array<string|int, mixed>
    $us_states
     = array()

An array of localized US states.

add_field_columns()

Add Field Columns


    public
                    add_field_columns([string $columns = array() ]) : array<string|int, mixed>

This will embed the field columns into the columns array. Looping through the already-set column names, if the column name is comments, date, or posts, The new field columns will be placed before the first instance of one of them. This method is hooked by objects screens that have tables, like WP_Backstage_User, WP_Backstage_Post_Type, and WP_Backstage_Taxonomy. Columns will only be placed for the field if the field's has_column argument is set to true.

Parameters

$columns : string = array(): The columns that are currently set.

Return values

array<string|int, mixed> —

The filtered columns with the new columns added.

add_rest_api_field_link()

Add REST API Field Link


    public
                    add_rest_api_field_link([WP_REST_Response $response = null ][, array<string|int, mixed> $field = array() ][, mixed $value = null ]) : WP_REST_Response

Parameters

$response : WP_REST_Response = null: The response object to manipulate.
$field : array<string|int, mixed> = array(): An array of field arguments.
$value : mixed = null: The field's value.

Return values

WP_REST_Response —

The augmented response object.

has_errors()

Has Errors


    public
                    has_errors() : bool

A utility method to easily check if the instance has errors or not.

Return values

bool —

Whether the instance has errors or not.

init()

Init


    public
                    init() : void

Hook all methods to WordPress.

Return values

void —

inline_code_editor_script()

Inline Code Editor Script


    public
                    inline_code_editor_script() : void

Inlines the code editor settings objects. This provides necessary context to the code editor scripts when initializing code editor fields.

Return values

void —

manage_sortable_columns()

Manage Sortable Columns


    public
                    manage_sortable_columns([array<string|int, mixed> $columns = array() ]) : array<string|int, mixed>

This will set which columns are sortable. This method is hooked by object screens that have tables, like WP_Backstage_User, WP_Backstage_Post_Type, and WP_Backstage_Taxonomy. Columns will only be made sortable if the field's has_column and is_sortable arguments are set to true.

Parameters

$columns : array<string|int, mixed> = array(): The sortable columns that are currently set.

Return values

array<string|int, mixed> —

The sortable columns with the new sortable columns added.

print_errors()

Print Errors


    public
                    print_errors() : void

Return values

void —

render_add_nonce()

Render Add nonce


    public
                    render_add_nonce() : string

Renders a nonce with this instance's $nonce_key with the action set to add.

Return values

string —

The formatted add nonce.

render_edit_nonce()

Render Edit nonce


    public
                    render_edit_nonce() : string

Renders a nonce with this instance's $nonce_key and the action set to edit.

Return values

string —

The formatted edit nonce.

render_rest_api_preview()

Render REST API Preview


    public
                    render_rest_api_preview([string $path = '' ]) : void

This method renders a REST API preview for a given path. Code mirror is used to initialize a json editor area that is read only. Filters for context and _embed are provided for through api response checks.

Parameters

$path : string = '': An API path to fetch.

Return values

void —

render_table_filter_control()

Render Table Filter Control


    public
                    render_table_filter_control([array<string|int, mixed> $args = array() ]) : void

This method is responsible for rendering a single filter control according to the array of arguments passed in. This will always render an HTML <select> element and is constructed in the same way that the existing table filter controls are rendered in core WordPress table fitlers. Note that the options key can either be an array of option arguments, or a string of fully built HTML <options>, to be able to support the drop down walkers for select_users and select_posts.

Parameters

$args : array<string|int, mixed> = array(): The incoming args for this control.

Return values

void —

render_table_filter_controls()

Render Table Filter Controls


    public
                    render_table_filter_controls() : void

This method is responsible for rendering the filter controls for fields. The fields will get their value from the parsed URL query parameters and set up arguments for the filter select as defined in WP_Backstage_Component::render_table_filter_control().

Return values

void —

sanitize_address()

Sanitize Address


    public
                    sanitize_address([array<string|int, mixed> $value = array() ]) : array<string|int, mixed>

Parameters

$value : array<string|int, mixed> = array(): The value to sanitize. Expects an array of address key => value pairs.

Return values

array<string|int, mixed> —

An array of address key => value pairs.

sanitize_checkbox()

Sanitize Checkbox


    public
                    sanitize_checkbox([bool $value = false ]) : bool

Parameters

$value : bool = false: The value to sanitize. Expects a value that can be cast to a boolean.

Return values

bool —

A boolean.

sanitize_checkbox_set()

Sanitize Checkbox Set


    public
                    sanitize_checkbox_set([array<string|int, mixed> $values = array() ]) : array<string|int, mixed>

Parameters

$values : array<string|int, mixed> = array(): The values to sanitize. Expects an array of strings.

Return values

array<string|int, mixed> —

An array of values.

sanitize_code()

Sanitize Code


    public
                    sanitize_code([string $value = '' ]) : string

Parameters

$value : string = '': The value to sanitize. Expects a string.

Return values

string —

An unsanitized string.

sanitize_editor()

Sanitize Editor


    public
                    sanitize_editor([string $value = '' ]) : string

Parameters

$value : string = '': The value to sanitize. Expects a string.

Return values

string —

the string sanitized as post content.

sanitize_email()

Sanitize Email


    public
                    sanitize_email([string $value = '' ]) : string

Parameters

$value : string = '': The value to sanitize. Expects an email address.

Return values

string —

An email address.

sanitize_field()

Sanitize Field


    public
                    sanitize_field([array<string|int, mixed> $field = array() ][, mixed $value = null ]) : mixed

Parameters

$field : array<string|int, mixed> = array(): The field args.
$value : mixed = null: The field value.

Return values

mixed —

The sanitized value according to the field type.

sanitize_media()

Sanitize Media


    public
                    sanitize_media([mixed $value = null ]) : array<string|int, mixed>

Parameters

$value : mixed = null: The value to sanitize. Expects a CSV string or array of attachment IDs.

Return values

array<string|int, mixed> —

An array of integers.

sanitize_number()

Sanitize Number


    public
                    sanitize_number([int|float $value = null ]) : float

Parameters

$value : int|float = null: The value to sanitize. Expects a numeric value.

Return values

float —

a float, or null if empty.

sanitize_select_posts()

Sanitize Select Posts


    public
                    sanitize_select_posts(mixed $value) : array<string|int, mixed>

Parameters

$value : mixed: The value to sanitize. Expects a post ID.

Return values

array<string|int, mixed> —

A non-negative integer.

sanitize_select_users()

Sanitize Select Users


    public
                    sanitize_select_users(mixed $value) : array<string|int, mixed>

Parameters

$value : mixed: The value to sanitize. Expects a user ID.

Return values

array<string|int, mixed> —

A non-negative integer.

sanitize_text()

Sanitize Text


    public
                    sanitize_text([string $value = '' ]) : string

Parameters

$value : string = '': The value to sanitize. Expects a string.

Return values

string —

a text field sanitized string.

sanitize_textarea()

Sanitize Textarea


    public
                    sanitize_textarea([string $value = '' ]) : string

Parameters

$value : string = '': The value to sanitize. Expects a string.

Return values

string —

a textarea sanitized string.

sanitize_time()

Sanitize Time


    public
                    sanitize_time([mixed $value = array() ]) : string

Parameters

$value : mixed = array(): The value to sanitize. Expects an array of 3 2-digit time values keyed as "hour", "minute", "second"; or a time string as hh:mm:ss.

Return values

string —

a string as hh:mm:ss.

sanitize_url()

Sanitize URL


    public
                    sanitize_url([string $value = '' ]) : string

Parameters

$value : string = '': The value to sanitize. Expects a URL.

Return values

string —

A URL.

__construct()

Construct


    protected
                    __construct() : void

Return values

void —

format_attrs()

Format Attrs


    protected
                    format_attrs([array<string|int, mixed> $attrs = array() ]) : string

A utility method for formatting an array of $key => $value pairs into a string of sanitized HTML element attributes.

Parameters

$attrs : array<string|int, mixed> = array(): An array of attributes as $key => $value pairs.

Return values

string —

The imploded, escaped, formatted attributes.

format_field_value()

Format Field Value


    protected
                    format_field_value([mixed $value = null ][, array<string|int, mixed> $field = array() ]) : string

This will format a fields value based on a given array of field args. According to the field type, different formatting will be applied to the value.

Parameters

$value : mixed = null: The value to format.
$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

string —

The value of the field as a string

format_filterable_value()

Format Filterable Value


    protected
                    format_filterable_value([mixed $value = null ][, string $label = '' ][, string $query_arg = '' ]) : mixed

This method is responsible for formatting filterable values. It accepts a value, a label, and a query arg and will determine what the link should be based on what component is currently being called.

Parameters

$value : mixed = null: The query arg's value.
$label : string = '': The label that will be printed.
$query_arg : string = '': The key of the query arg that will be added to the URL.

Return values

mixed —

get_field_by()

Get Field By


    protected
                    get_field_by([string $key = '' ][, mixed $value = null ]) : array<string|int, mixed>

Get the first field that matches the passed $key and $value.

Parameters

$key : string = '': the key of the field arg to check.
$value : mixed = null: the value of the passed field arg key to check.

Return values

array<string|int, mixed> —

the first field arg array if found, or an empty array.

get_field_schema()

Get Field Schema


    protected
                    get_field_schema([array<string|int, mixed> $field = array() ]) : array<string|int, mixed>

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

array<string|int, mixed> —

An array of schema arguments.

get_fields()

Get Fields


    protected
                    get_fields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

an array of field arg arrays.

get_fields_by()

Get Fields By


    protected
                    get_fields_by([string $key = '' ][, mixed $value = null ], int $number) : array<string|int, mixed>

Get all fields that matches the passed $key and $value.

Parameters

$key : string = '': the key of the field arg to check.
$value : mixed = null: the value of the passed field arg key to check.
$number : int: the number of fields to return.

Return values

array<string|int, mixed> —

an array of field arg arrays if found, or an empty array.

get_fields_by_query()

Get Fields By Query


    protected
                    get_fields_by_query([array<string|int, mixed> $query = array() ], int $number) : array<string|int, mixed>

Get all fields that matches the passed query array.

Parameters

$query : array<string|int, mixed> = array(): An array of key values to check against.
$number : int: the number of fields to return.

Return values

array<string|int, mixed> —

an array of field arg arrays if found, or an empty array.

get_option_labels()

Get Option Labels


    protected
                    get_option_labels([array<string|int, mixed> $field = array() ]) : array<string|int, mixed>

A utility method to get the localized labels for a given field. This will return a $value => $label array that can be used to pluck an option label for a given option value for a field. This is useful when displaying the value of a radio, checkbox, or checkbox_set where the value is not "pretty".

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

array<string|int, mixed> —

An array of $value => $label pairs.

get_sanitize_callback()

Get Sanitize Callback


    protected
                    get_sanitize_callback([array<string|int, mixed> $field = array() ]) : string

Since the WP_Backstage_Options class is using the WP Settings API, it is necessary to provide a sanitize_callback to the register_setting() function. This method provides a mask of all of this class's sanitize_field methods as strings per field type.

Parameters

$field : array<string|int, mixed> = array(): The field args.

Return values

string —

The sanitize callback function name as a string.

is_screen()

Is Screen


    protected
                    is_screen([string $key = '' ][, string|array<string|int, mixed> $value = '' ]) : bool

A utility method to easily check values returned by get_current_screen().

Parameters

$key : string = '': The key of the WP_Screen object to check.
$value : string|array<string|int, mixed> = '': The value or array of values to check.

Return values

bool —

If the match was successful or not.

render_address()

Render Address


    protected
                    render_address([array<string|int, mixed> $field = array() ]) : void

Render a group of fields that will provide all necessary inputs to create a full address. The value of this field is an array of address pieces as country, address, address_2, city, state, zip. If the US is selected as the country, then a <select> of localized US states will replace the "State/Province/Region" input.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_checkbox()

Render Checkbox


    protected
                    render_checkbox([array<string|int, mixed> $field = array() ]) : void

Render a checkbox field. This was separated out from this class's render_input() method because the markup is significantly different.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_checkbox_set()

Render Checkbox Set


    protected
                    render_checkbox_set([array<string|int, mixed> $field = array() ]) : void

Render a set of checkboxes that allow for multiple values to be set for a field. The options are set as an array of the field's options key. These can be dynamically created by looping post types, taxonomies, users, options, etc.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_code()

Render Code


    protected
                    render_code([array<string|int, mixed> $field = array() ]) : void

Render a code editor using the native CodeMirror integration in WordPress Core. This field supports multiple mime types like text/javascript, text/css, text/html, and application/pdf, etc. WordPress's provided configuration will lint, show errors in code, and provide autocompletes. All WordPress caveats, like bugs when moving code editors around in the DOM in meta boxes, and bugs when displaying a meta box that was hidden on page load, have been handled.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_color()

Render Color


    protected
                    render_color([array<string|int, mixed> $field = array() ]) : void

Render a color picker field. This uses the the native Iris JavaScript library as included in WordPress Core to render the same robust color pickers found in WordPress. The field is configurable with arguments for hsl and hsv color modes, as well as custom color palettes.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_date()

Render Date


    protected
                    render_date([array<string|int, mixed> $field = array() ]) : void

Render a date field using jQuery UI Datepicker. This was separated out from this class's render_input() method because of the JavaScript integration. This UI method ensures a full-proof way of ensuring date strings are always ISO compliant.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_editor()

Render Editor


    protected
                    render_editor([array<string|int, mixed> $field = array() ]) : void

This will render a WordPress editor complete with TinyMCE and quicktags. These provide a WYSIWYG environment where content creation can happen in a familiar WordPress flow. All WordPress caveats, like bugs when moving WP Editors around in the DOM in meta boxes, and bugs when displaying a meta box that was hidden on page load, have been handled.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_field_by_type()

Render Field By Type


    protected
                    render_field_by_type([array<string|int, mixed> $field = array() ]) : void

This will render a field by type, given an array of field arguments. Depending on the field type, different render field methods will be called in order to render the appropriate field HTML.

Parameters

$field : array<string|int, mixed> = array(): An array of field args.

Return values

void —

render_input()

Render Input


    protected
                    render_input([array<string|int, mixed> $field = array() ]) : void

Render an input field. This method will handle all HTML <input> types except for radio, checkbox, and those with their own methods like date.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_media_uploader()

Render Media Uploader


    protected
                    render_media_uploader([array<string|int, mixed> $field = array() ]) : void

The media uploader field is capable of selecting media files of all mime types, and supports single and multiple image selection. This field is deeply integrated into the WordPress Media Uploader, and there are arguments for mime type selection. Fields that allow multiple attachments to be selected also support selective removal, addition, and drag-and-drop sorting.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_radio()

Render Radio


    protected
                    render_radio([array<string|int, mixed> $field = array() ]) : void

Render a set of radios that allow for a single value to be set for a field. The options are set as an array of the field's options key. These can be dynamically created by looping post types, taxonomies, users, options, etc.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_select()

Render Select


    protected
                    render_select([array<string|int, mixed> $field = array() ]) : void

Render a select that allow for a single value to be set for a field. The options are set as an array of the field's options key. These can be dynamically created by looping post types, taxonomies, users, options, etc.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_select_posts()

Render Select Posts


    protected
                    render_select_posts([array<string|int, mixed> $field = array() ]) : void

Render a select field prepopulared by WordPress posts.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_select_users()

Render Select Users


    protected
                    render_select_users([array<string|int, mixed> $field = array() ]) : void

Render a select field prepopulared by WordPress users.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_textarea()

Render Textarea


    protected
                    render_textarea([array<string|int, mixed> $field = array() ]) : void

Render a textarea field.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_time()

Render Time


    protected
                    render_time([array<string|int, mixed> $field = array() ]) : void

Render a time field. This will create the 3 <select> fields needed to create a time string as 00:00:00. This UI method ensures a full-proof way of ensuring time strings are always ISO compliant.

Parameters

$field : array<string|int, mixed> = array(): An array of field arguments.

Return values

void —

render_time_options()

Render Time Options


    protected
                    render_time_options(int $number[, string $selected = '' ]) : void

This is used in order to create all <option> elements needed to create a time piece <select> as used in this class's render_time() method.

Parameters

$number : int: The number of options to render.
$selected : string = '': The selected option's value.

Return values

void —

WP_Backstage_Component in package WPBackstage

Tags

Table of Contents

Properties

$args

Tags

$countries

Tags

$date_format

Tags

$default_address_args

Tags

$default_address_values

Tags

$default_code_args

Tags

$default_color_args

Tags

$default_date_args

Tags

$default_editor_args

Tags

$default_field_args

Tags

$default_filter_control_args

Tags

$default_media_uploader_args

Tags

$default_option_args

Tags

$default_select_posts_args

Tags

$default_select_users_args

Tags

$errors

Tags

$filterable_fields

Tags

$global_code_settings

Tags

$non_regular_text_fields

Tags

$nonce_key

Tags

$remove_label_for_fields

Tags

$screen_id

Tags

$slug

Tags

$textarea_control_fields

Tags

$time_pieces

Tags

$us_states

Tags

Methods

add_field_columns()

Parameters

Tags

Return values

add_rest_api_field_link()

Parameters

Tags

Return values

has_errors()

Tags

Return values

init()

Tags

Return values

inline_code_editor_script()

Tags

Return values

manage_sortable_columns()

Parameters

Tags

Return values

print_errors()

Tags

WP_Backstage_Component
in package

WPBackstage