Defining fields

Each field in PuppyFW is an array of its own attributes.

Common field attributes

Attribute	Description
id	Field ID. This should be unique for each option
title	Field title. It will be displayed in options page
type	Field type. See the list of supported field types
desc	Field description
default	Default value
options	List of choices. Use for fields `checkbox_list`, `radio`, `select`
js_options	Options some fields use third-party js library. Eg: `datepicker`, etc.
attrs	Custom HTML attributes for the `input` element of field (some fields don't support this)
tab	Tab id which this field is belonged to. See tab field
dependency	Field dependencies definition. See Field dependencies for more detail

List of supported field types

text
email
tel
url
number
checkbox
checkbox_list
radio
select
textarea
image
images
map
editor
html
colorpicker
datepicker
tab
group
repeatable

Text fields

text, email, tel, url, number are text fields, use common attributes for definition:

array(
	'id'      => 'example_text',
	'title'   => 'Example text',
	'desc'    => 'Example text description',
	'default' => 'Default value',
	'type'    => 'text',
)

Min, max, step of number field:

array(
	'id'      => 'example_number',
	'title'   => 'Example number',
	'type'    => 'number',
	'attrs'   => array(
		'min'  => 0,
		'max'  => 100,
		'step' => 10,
	),
)

checkbox

A single checkbox input.

Attributes:

attrs: will not affect this field.
default: accepts boolean value.

array(
	'id'      => 'checkbox',
	'title'   => 'Checkbox field',
	'type'    => 'checkbox',
	'default' => true,
)

checkbox_list

List of checkbox inputs, allow choosing multiple value.

Attributes:

attrs: will not affect this field.
default: accepts array of options value.
inline: accepts boolean value. Default is false, checkbox inputs will be display in each line. If true, checkbox inputs will be display in a line.
data_source: default is empty. If this attribute is specific, options will be list of posts, terms or taxonomies. Accepts post, term, taxonomy.
post_type: use if data_source is set to post.
taxonomy: use if data_source is set to term.
none_option: the displayed text for empty option if use data_source. Default is empty.

array(
	'id'      => 'checkbox_list',
	'title'   => 'Checkbox list field',
	'type'    => 'checkbox_list',
	'default' => array( 2, 3 ),
	'inline'  => true,
	'options' => array(
		1 => 'Option 1',
		2 => 'Option 2',
		3 => 'Option 3',
		4 => 'Option 4',
	),
),
array(
	'id'          => 'pages_checkbox_list',
	'title'       => 'Pages checkbox',
	'type'        => 'checkbox_list',
	'data_source' => 'post',
	'post_type'   => 'page',
	'none_option' => 'Choose pages',
)

radio

List of radio inputs, allow choosing only a single value. It supports attributes like checkbox_list, except default only accepts a single value.

array(
	'id'      => 'radio',
	'title'   => 'Radio field',
	'type'    => 'radio',
	'default' => 2,
	'options' => array(
		1 => 'Option 1',
		2 => 'Option 2',
		3 => 'Option 3',
	),
),

select

Attributes:

multiple: accepts boolean value. Default is false. If true, this field allows choosing multiple value.
default: accepts a single value if multiple is false, an array of value if multiple is true.
data_source, post_type, taxonomy, none_option are same as checkbox_list field.

array(
	'id'      => 'select',
	'title'   => 'Select field',
	'type'    => 'select',
	'default' => 3,
	'options' => array(
		1 => 'Option 1',
		2 => 'Option 2',
		3 => 'Option 3',
		4 => 'Option 4',
	),
),
array(
	'id'      => 'multiple_select',
	'title'   => 'Multiple select field',
	'type'    => 'select',
	'multiple' => true,
	'default' => array( 2, 4 ),
	'options' => array(
		1 => 'Option 1',
		2 => 'Option 2',
		3 => 'Option 3',
		4 => 'Option 4',
	),
),

textarea

Supports common attributes.

array(
	'id'      => 'textarea',
	'title'   => 'Textarea field',
	'default' => "Default value\nSupport multiline",
	'type'    => 'textarea',
)

image

Use WordPress media upload. Allow adding a single image.

Attributes:

attrs: will not affect this field.
default: accepts URL of image.

array(
	'id'    => 'image',
	'title' => 'Image field',
	'type'  => 'image',
	'default' => array(
		'url' => 'https://assets.merriam-webster.com/mw/images/article/art-wap-article-main/[email protected]',
	),
)

This field stores both image ID and image URL with below structure:

array(
	'id'  => IMAGE_ID,
	'url' => IMAGE URL,
)

images

Use WordPress media upload. Allow adding multiple images with sortable feature.

Attributes:

attrs: will not affect this field.
default: isn't supported in this field.

array(
	'id'    => 'images',
	'title' => 'Images field',
	'type'  => 'images',
)

Data structure:

array(
	array(
		'id'  => IMAGE_ID,
		'url' => IMAGE URL,
	),
	array(
		'id'  => IMAGE_ID,
		'url' => IMAGE URL,
	),
	array(
		'id'  => IMAGE_ID,
		'url' => IMAGE URL,
	),
)

map

A google map with an address search input.

Attributes:

attrs: will not affect this field.
default: accepts an array contains lat, lng and formatted_address (like data structure).

array(
	'id'    => 'map',
	'title' => 'Map field',
	'type'  => 'map',
)

Data structure:

array(
	'lat' => Latitude,
	'lng' => Longitude,
	'formatted_address' => Formatted address name,
)

editor

WordPress editor.

Attributes:

tinymce: enable Visual tab. Accepts boolean value. Default is false.
quicktag: enable Text tab. Accepts boolean value. Default is true.

array(
	'id'      => 'editor',
	'title'   => 'Editor',
	'type'    => 'editor',
	'tinymce' => true,
)

Note: Require at least tinymce or quicktag is true.

html

This field allows displaying custom HTML.

Attributes:

id, title are unnecessary.
content: the HTML content want to display.

array(
	'type'    => 'html',
	'content' => '<h2>This is HTML content</h2>',
),

colorpicker

WordPress colorpicker input.

Attributes:

alpha: Support rgba() color or not. Accepts boolean value.

array(
	'id'      => 'color',
	'title'   => 'Colorpicker field',
	'type'    => 'colorpicker',
	'alpha'   => true, // Support rgba value.
	'default' => '#c40000',
)

datepicker

An datepicker input uses jQuery UI Datepicker.

*Attributes:

js_options: See here for full list of options. Options as function will not work.

array(
	'id'         => 'date',
	'title'      => 'Datepicker field',
	'type'       => 'datepicker',
	'js_options' => array(
		'minDate'    => '13/10/2017',
		'dateFormat' => 'dd/mm/yy',
	),
),

Note:

Default date format is yy-mm-dd.
The format of value is always yy-mm-dd.

tab

In PuppyFW, tab is treated as a field which contains another fields (of course, the tab fields as well).

Attributes:

title: is unnecessary.
tabs: Array of tabs with key is tab ID and value is tab title.
fields: Array of child fields. This array is same as fields definition array, except each fields has an attribute named tab to determine the tab which it belongs to.

array(
	'id'     => 'tab',
	'type'   => 'tab',
	'tabs'   => array(
		'tab-1' => 'Tab 1',
		'tab-2' => 'Tab 2',
		'tab-3' => 'Tab 3',
	),
	'fields' => array(
		array(
			'id'    => 'textarea_1',
			'title' => 'Textarea 1',
			'type'  => 'textarea',
			'tab'   => 'tab-1',
		),
		array(
			'id'    => 'textarea_2',
			'title' => 'Textarea 2',
			'type'  => 'textarea',
			'tab'   => 'tab-2',
		),
		array(
			'id'    => 'textarea_3',
			'title' => 'Textarea 3',
			'type'  => 'textarea',
			'tab'   => 'tab-3',
		),
	),
),

Note: This field does not affect how the data is stored. Each field in tab is like field outside tab.

prefix_option( 'tab' ); // Return null
prefix_option( 'textarea_1' ); // Return value of textarea 1.
prefix_option( 'textarea_2' ); // Return value of textarea 2.

group

Combine the related fields into one group.

Attributes:

fields: Array of child fields. This array is same as fields definition array.

array(
	'id'     => 'group',
	'title'  => 'Group field',
	'type'   => 'group',
	'fields' => array(
		array(
			'id'    => 'name',
			'title' => 'Name',
			'type'  => 'text',
		),
		array(
			'id'    => 'email',
			'title' => 'Email',
			'type'  => 'text',
		),
	),
)

Note: Unlike tab, group field stores data as an array with key is child field ID and value is child field value. So that, the ID of child field can be same as a field outside group.

prefix_option( 'group' ); // Return array( 'name' => name value, 'email' => email value )
prefix_option( 'name' ); // Return null or value of a field outside group which has id is `name`

Group can be a child of other group, this is called nested group.

array(
	'id'     => 'group',
	'title'  => 'Group',
	'type'   => 'group',
	'fields' => array(
		array(
			'id'    => 'name',
			'title' => 'Name',
			'type'  => 'text',
		),
		array(
			'id'    => 'email',
			'title' => 'Email',
			'type'  => 'text',
		),
		array(
			'id'    => 'nested_group',
			'title' => 'Nested group',
			'type'  => 'group',
			'fields' => array(
				array(
					'id'        => 'test_editor',
					'title'     => 'Nested Editor',
					'type'      => 'editor',
					'tinymce'   => true,
					'quicktags' => true,
				),
			),
		),
	),
)

repeatable

Every fields in PuppyFW can be repeatable in some steps:

// This is a text field.
array(
	'id'    => 'text',
	'title' => 'Normal text',
	'type'  => 'text',
)

// Add an attribute named `repeat_field_type` with value is type of field.
array(
	'id'    => 'text',
	'title' => 'Normal text',
	'type'  => 'text',
	'repeat_field_type' => 'text', // Added
)

// Change type attribute to repeatable. now the text field can be repeatable.
array(
	'id'    => 'text',
	'title' => 'Normal text',
	'type'  => 'repeatable', // Changed.
	'repeat_field_type' => 'text',
)

Repeatable works with both group and nested group.

array(
	'id'                => 'repeatable_group',
	'title'             => 'Repeatable group',
	'type'              => 'repeatable',
	'repeat_field_type' => 'group',
	'fields'            => array(
		array(
			'id'    => 'name',
			'title' => 'Name',
			'type'  => 'text',
		),
		array(
			'id'    => 'email',
			'title' => 'Email',
			'type'  => 'text',
		),
		array(
			'id'                => 'repeatable_nested_group',
			'title'             => 'Repeatable nested group',
			'type'              => 'repeatable',
			'repeat_field_type' => 'group',
			'fields'            => array(
				array(
					'id'                => 'repeatable_editor',
					'title'             => 'Repeatable editor',
					'type'              => 'repeatable',
					'repeat_field_type' => 'editor',
					'tinymce'           => true,
					'quicktags'         => true,
				),
			),
		),
	),
)