API Documentation
\

\O3PO_Form

Trait for forms such as the settings form.

Summary

Methods
Properties
Constants
specify_page()
specify_section()
specify_field()
render_single_line_field()
render_multi_line_field()
render_password_field()
render_checkbox_field()
render_select_field()
render_array_as_comma_separated_list_field()
get_field_default()
get_field_defaults()
get_field_title()
specify_fake_field()
validate_doi_prefix()
validate_doi_suffix()
validate_four_digit_year()
validate_eprint()
validate_issn_or_empty()
validate_issn()
validate_email()
validate_url()
validate_array_as_comma_separated_list()
validate_two_letter_country_code()
validate_positive_integer()
validate_non_negative_euros()
checked_or_unchecked()
checked()
trim()
trim_strip_tags()
leave_unchanged()
get_field_value()
No public properties found
No constants found
add_error()
$plugin_name
$slug
$pages
$sections
$fields
N/A
No private methods found
No private properties found
N/A

Properties

$plugin_name

$plugin_name : string

The unique identifier of this plugin.

Type

string — The string used to uniquely identify this plugin.

$slug

$slug : string

Slug of this form.

Used for css classes when rendering the sections and fields. Used then storing/retreiving data from the database.

Type

string — Slug of the form.

$pages

$pages : array

Array of all pages of the form.

Type

array — Dictionary of all pages and their properties.

$sections

$sections : array

Array of all sections of the form.

Type

array — Dictionary of all sections and their properties.

$fields

$fields : array

Array of all field of the form.

Type

array — Dictionary of all fields and their properties.

Methods

specify_page()

specify_page(string  $id, string  $title, callable  $callback = null)

Specify a section of the form.

Keeps a record of all sections in $this->sections.

Parameters

string $id

Slug-name to identify the page.
string $title

Formatted title of the section. Shown as the heading for the section.
callable $callback

Function that echos out the any content at the top of the page (before the first section).

specify_section()

specify_section(string  $id, string  $title, callable  $callback, string  $page, callable  $summary_callback = null)

Specify a section of the form.

Keeps a record of all sections in $this->sections.

Parameters

string $id

Slug-name to identify the section. Used in the 'id' attribute of tags.
string $title

Formatted title of the section. Shown as the heading for the section.
callable $callback

Function that echos out any content at the top of the section (between heading and fields).
string $page

The slug-name of the page on which to show the section.
callable $summary_callback

Callback to call when composing the summary of this form.

specify_field()

specify_field(string  $id, string  $title, callable  $callback, string  $page, string  $section, array  $args, callable  $validation_callable, string  $default, integer  $max_length = false)

Specify a field of the form.

Keeps a record of all fields in $this->fields.

Parameters

string $id

Slug-name to identify the field. Used in the 'id' attribute of tags.
string $title

Formatted title of the field. Shown as the heading for the field.
callable $callback

Function that echos out any content at the top of the field (between heading and fields).
string $page

The slug-name of the page on which to show the field.
string $section

The slug-name of the section in which to show the field.
array $args

{ Extra arguments used when outputting the field. May be an empty array().

@type string $label_for When supplied, the label will be wrapped
                        in a `<label>` element, its `for` attribute populated
                        with this value.
@type string $class     CSS Class to be added to the `<tr>` element when the
                        field is output.

}
callable $validation_callable

Callable to use during validation of inputs. Must take a field ID and input as parameters and return a valid value for the field. Should call $this->add_error() to indicate problems.
string $default

Default value for the field.
integer $max_length

Maximum length of the value of the field.

render_single_line_field()

render_single_line_field(string  $id, string|null  $placeholder = null, string  $autocomplete = 'on', string  $style = false, string  $label = false, boolean  $esc_label = true, string  $label_style = false)

Render a standard text box type field.

Parameters

string $id

Id of the field.
string|null $placeholder

Placeholder text (default is null).
string $autocomplete

Whether to auto complete 'or' (default) or 'off.
string $style

CSS style.
string $label

HTML label.
boolean $esc_label

Whether to escape the content of label.
string $label_style

CSS style for the label.

render_multi_line_field()

render_multi_line_field(string  $id, integer  $rows = false, string  $style = false, boolean  $preview = false, string  $placeholder = false)

Render a multi line text box type field.

Parameters

string $id

Id of the field.
integer $rows

Number of rows
string $style

CSS style
boolean $preview

Whether to show a LaTeX preview below the field.
string $placeholder

Placeholder

render_password_field()

render_password_field(string  $id)

Render a password field.

Parameters

string $id

Id of the field.

render_checkbox_field()

render_checkbox_field(string  $id, string  $label = '', boolean  $esc_label = true)

Render a checkbox type field.

Parameters

string $id

Id of the field.
string $label

Label of the field.
boolean $esc_label

Whether to escape the content of $label, disable in case you want $label to contains htmls

render_select_field()

render_select_field(string  $id, array  $options, string  $onchange = false)

Render a select type field.

Parameters

string $id

Id of the field.
array $options

The options between which to select
string $onchange

The HTML onchange parameter

render_array_as_comma_separated_list_field()

render_array_as_comma_separated_list_field(string  $id, string  $placeholder = null)

Render an array as comma separated list type field.

Does not escape or otherwise handle individual fields that contain commas.

Parameters

string $id

Id of the field.
string $placeholder

Placeholder text.

get_field_default()

get_field_default(integer  $id) : string

Get the default value of a field by id.

Parameters

integer $id

Id of the field.

Returns

string —

Default value of the field

get_field_defaults()

get_field_defaults(boolean  $include_fake_fields = false)

Get the default value of all fields.

Parameters

boolean $include_fake_fields

Whether to also include fake fields in the list.

get_field_title()

get_field_title(integer  $id)

Get the title of a field by id.

Parameters

integer $id

Id of the field.

specify_fake_field()

specify_fake_field(string  $id, string  $default)

Add a fake field

Fake fields cannot be modified, but have default values that can be used to avoid hard coding values.

Parameters

string $id

Slug-name to identify the section. Used in the 'id' attribute of tags.
string $default

Default value for the field.

validate_doi_prefix()

validate_doi_prefix(string  $id, string  $input)

Clean user input to doi_prefix fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_doi_suffix()

validate_doi_suffix(string  $id, string  $input)

Clean user input to doi_suffix fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_four_digit_year()

validate_four_digit_year(string  $id, string  $input)

Clean user input to fields expecting a year.

Parameters

string $id

The field this was input to.
string $input

User input.

validate_eprint()

validate_eprint(string  $id, string  $input) : string

Clean user input to eprint fields

Parameters

string $id

The field this was input to.
string $input

User input.

Returns

string —

Valid issn or empty string.

validate_issn_or_empty()

validate_issn_or_empty(string  $id, string  $input) : string

Clean user input to issn fields

Parameters

string $id

The field this was input to.
string $input

User input.

Returns

string —

Valid issn or empty string.

validate_issn()

validate_issn(string  $id, string  $input)

Clean user input to issn fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_email()

validate_email(string  $id, string  $input)

Clean user input to email fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_url()

validate_url(string  $id, string  $input)

Clean user input to url fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_array_as_comma_separated_list()

validate_array_as_comma_separated_list(string  $id, string  $input)

Validate input to comma separated list fields.

Break a comma separated list into an array of fields.

Parameters

string $id

The field this was input to.
string $input

User input.

validate_two_letter_country_code()

validate_two_letter_country_code(string  $id, string  $input)

Validate two letter country code fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_positive_integer()

validate_positive_integer(string  $id, string  $input)

Validate positive integer fields

Parameters

string $id

The field this was input to.
string $input

User input.

validate_non_negative_euros()

validate_non_negative_euros(string  $id, string  $input)

Validate non-negative euro fields

Parameters

string $id

The field this was input to.
string $input

User input.

checked_or_unchecked()

checked_or_unchecked(string  $id, string  $input)

Restrict input to checked or unchecked fields

Parameters

string $id

The field this was input to.
string $input

User input.

checked()

checked(string  $id, string  $input)

Ensure that a check box field is checked

Parameters

string $id

The field this was input to.
string $input

User input.

trim()

trim(string  $id, string  $input)

Trim user input to field

Parameters

string $id

The field this was input to.
string $input

User input.

trim_strip_tags()

trim_strip_tags(string  $id, string  $input)

Trim user input to field

Parameters

string $id

The field this was input to.
string $input

User input.

leave_unchanged()

leave_unchanged(string  $id, string  $input)

Leave user input to field unchanged.

Parameters

string $id

The field this was input to.
string $input

User input.

get_field_value()

get_field_value(integer  $id)

Get the value of a field by id.

Parameters

integer $id

Id of the field.

add_error()

add_error(string  $setting, string  $code, string  $message,   $type = 'error')

Record errors during input verification.

The O3PO_Settings class for example implements this as just a wrappter around add_settings_error().

Implementations must adhere to the following parameter specification:

Parameters

string $setting

Slug title of the setting to which this error applies.
string $code

Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
string $message

The formatted message text to display to the user (will be shown inside styled

and

tags).
$type

Message type, controls HTML class. Possible values include 'error', 'success', 'warning', 'info'. Default value: 'error'