> Fields > Field Parameters

Field Parameters

This is a full list of available parameters for Piklist fields.

add_more (repeater)

Piklist allows you to turn ANY field, or group of fields, into a repeater field, by simple adding the add_more parameter.

Displaying Data To display the results of the Add-More in your theme, pull the data like you normally would. Add more’s save data as an array, so you can loop though the data to display.

Input: boolean
Default: false

Example: 'add_more' => true

attributes

Adds HTML attributes to your field.

Input: array 8 values: An array of HTML attributes piklist

Example:

array(
	'placeholder' => 'Enter text'
	,'class' => 'large-text'
)

capability

Set the user capabilities that will see this field.

Input: comma-delimited
Default: none

Examples: 'capability' => 'create_users' 'capability' => 'create_users, edit_posts'

child_add_more

Input: boolean
Default: false

child_field

Input: boolean
Default: false

choices

Create a list of choices. Used with the following fields: checkbox, radio, select.

Input: array
values: An array of choices

Example:

'choices' => array(
	'first' => 'First Choice',
	'second' => 'Second Choice',
	'third' => 'Third Choice'
)

columns

Piklist uses a 12 column grid system to help you layout your fields. The grid system is really helpful when laying out group fields.

Input: numeric
values: Any number 1-12

Examples: 'columns' => 1 'columns' => 12

Conditions

Set conditions for your fields.

Input: parameters
values: An array of conditions

Sub Parameters:

relation (sub parameter)

When using multiple conditions, the default logic is AND. Use this parameter to change the logic to OR. Examples: 'relation' => 'or' 'relation' => 'and'

field (sub parameter)

The name of the field you will be watching for Hide/Show, or the field you will be Updating. Example: 'field' => 'my_field'

value (sub parameter)

The value(s) of the field that will trigger the condition. This parameter also accepts an array of values. Examples: 'value' => 'yes' 'value' => array('yes', 'maybe')

reset (sub parameter)

By default, any field that is hidden/shown will have their values reset. To prevent this set reset to false. Example: 'reset' => 'false'

compare (sub parameter)

Operator to test the value against. Currently only two values are supported: == and !=.

default: ==

Example: 'compare' => '!='

type (sub parameter)

Piklist supports two condition types; toggle and update.

default: toggle

Example: 'type' => update

scope (sub parameter)

IMPORTANT: Only use if you manually set the scope in the field you are monitoring for Hide/Show. Example: 'scope' => taxonomy

post_status_hide (sub parameter)

post_status_value (sub parameter)

Example:

  // Demonstrates a lot of conditional fields working together


  // Show this field if (guest_meal == steak) or (guest_one_meal == steak) or (guest_two_meal == steak)
  piklist('field', array(
    'type' => 'html'
    ,'field' => '_message_meal'
    ,'value' => __('We only serve steaks rare.', 'piklist-demo')
    ,'attributes' => array(
      'class' => 'piklist-error-text'
    )
    ,'conditions' => array(
      'relation' => 'or'
      ,array(
        'field' => 'guest_meal'
        ,'value' => 'steak'
      )
      ,array(
        'field' => 'guest_one_meal'
        ,'value' => 'steak'
      )
      ,array(
        'field' => 'guest_two_meal'
        ,'value' => 'steak'
      )
    )
  ));

  // Update the field 'guests' to 'yes', if this field is set to ('yes' or 'maybe')
  piklist('field', array(
    'type' => 'select'
    ,'field' => 'attending'
    ,'label' => __('Are you coming to the party?', 'piklist-demo')
    ,'choices' => array(
      '' => ''
      ,'yes' => 'Yes'
      ,'no' => 'No'
      ,'maybe' => 'Maybe'
    )
    ,'conditions' => array(
      array(
        'field' => 'guests'
        ,'value' => array('yes', 'maybe')
        ,'update' => 'yes'
        ,'type' => 'update'
      )
    )
  ));

  // Show this field if the field 'attending' is not eqaual to (empty or 'no')
  piklist('field', array(
    'type' => 'radio'
    ,'field' => 'guest_meal'
    ,'label' => __('Choose meal type', 'piklist-demo')
    ,'choices' => array(
      'chicken' => 'Chicken'
      ,'steak' => 'Steak'
      ,'vegetarian' => 'Vegetarian'
    )
    ,'conditions' => array(
      array(
        'field' => 'attending'
        ,'value' => array('', 'no')
        ,'compare' => '!='
      )
    )
  ));

   // Show this field if the field 'attending' is not eqaual to (empty or 'no')
  piklist('field', array(
    'type' => 'select'
    ,'field' => 'guests'
    ,'label' => __('Are you bringing guests', 'piklist-demo')
    ,'description' => __('Coming to party != (No or empty)', 'piklist-demo')
    ,'choices' => array(
      'yes' => 'Yes'
      ,'no' => 'No'
    )
    ,'conditions' => array(
      array(
        'field' => 'attending'
        ,'value' => array('', 'no')
        ,'compare' => '!='
      )
    )
  ));

  // Show this field if the field 'guests_number' is 3
  piklist('field', array(
    'type' => 'html'
    ,'field' => '_message_guests'
    ,'value' => __('Sorry, only two guests are allowed.', 'piklist-demo')
    ,'attributes' => array(
      'class' => 'piklist-error-text'
    )
    ,'conditions' => array(
      array(
        'field' => 'guests_number'
        ,'value' => '3'
      )
    )
  ));

  // Show this field if the field 'attending' is not equal to (empty or 'no')
  // AND the field 'guests' is 'yes'
  piklist('field', array(
    'type' => 'number'
    ,'field' => 'guests_number'
    ,'label' => __('How many guests?', 'piklist-demo')
    ,'description' => __('Coming to party != (No or empty) AND Guests = Yes', 'piklist-demo')
    ,'value' => 1
    ,'attributes' => array(
      'class' => 'small-text'
      ,'step' => 1
      ,'min' => 0
    )
    ,'conditions' => array(
      array(
        'field' => 'attending'
        ,'value' => array('', 'no')
        ,'compare' => '!='
      )
      ,array(
        'field' => 'guests'
        ,'value' => 'yes'
      )
    )
  ));

   // Show this field if the field 'guests_number' not equals (empty or 0)
   // AND the field 'guests' is 'yes'
   // AND 'attending' is not equal to (empty or 'no')
  piklist('field', array(
    'type' => 'group'
    ,'label' => __('Guest One', 'piklist-demo')
    ,'description' => __('Number of guests != empty', 'piklist-demo')
    ,'fields' => array(
      array(
        'type' => 'text'
        ,'field' => 'guest_one'
        ,'label' => __('Name', 'piklist-demo')
      )
      ,array(
        'type' => 'radio'
        ,'field' => 'guest_one_meal'
        ,'label' => __('Meal choice', 'piklist-demo')
        ,'choices' => array(
          'chicken' => 'Chicken'
          ,'steak' => 'Steak'
          ,'vegetarian' => 'Vegetarian'
        )
      )
    )
    ,'conditions' => array(
      array(
        'field' => 'guests_number'
        ,'value' => array('', '0')
        ,'compare' => '!='
      )
      ,array(
        'field' => 'guests'
        ,'value' => 'yes'
      )
      ,array(
        'field' => 'attending'
        ,'value' => array('', 'no')
        ,'compare' => '!='
      )
    )
  ));

  // Show this field if the field 'guests_number' not equals (empty or 0 or 1)
  // AND 'attending' is not equal to (empty or 'no')
  piklist('field', array(
    'type' => 'group'
    ,'label' => __('Guest Two', 'piklist-demo')
    ,'description' => __('Number of guests != (empty or 1)', 'piklist-demo')
    ,'fields' => array(
      array(
        'type' => 'text'
        ,'field' => 'guest_two'
        ,'label' => __('Name', 'piklist-demo')
      )
      ,array(
        'type' => 'radio'
        ,'field' => 'guest_two_meal'
        ,'label' => __('Meal choice', 'piklist-demo')
        ,'choices' => array(
          'chicken' => 'Chicken'
          ,'steak' => 'Steak'
          ,'vegetarian' => 'Vegetarian'
        )
      )
    )
    ,'conditions' => array(
      array(
        'field' => 'guests_number'
        ,'value' => array('', '0', '1')
        ,'compare' => '!='
      )
      ,array(
        'field' => 'attending'
        ,'value' => array('', 'no')
        ,'compare' => '!='
      )
    )
  ));

data_id

Input: string
Default: null

description

The description of your field.

Input: string

Example: 'description' => 'This is my description'

disable_label

Input: boolean
Default: true

display

Input: boolean
Default: true

embed

Input: boolean
Default: false

errors

Input: boolean
Default: false

field

The name of your field.

For scope: post_meta, term_meta, option: this is the name of the field that will be saved to your database.

For scope: post, taxonomy: use the name of the post_type or taxonomy you want to save your data to.

Input: string Examples:

'field' => 'my_field'

'field' => 'post_type_name'

'field' => 'taxonomy_name'

group_field

Input: boolean
Default: false

help

Adds tooltip help to your field. This will only display if a label is set for your field.

Input: string

Example: 'help' => 'Some help text'

id

Adds tooltip help to your field. This will only display if a label is set for your field.

Input: string
Default: null

label

The label for your field.

Input: string

Example: 'label' => 'My field'

label_position

The position of your label relative to your field.

Input: string
values: before, after
Default: before

Example: 'label_position' => 'after'

label_tag

Input: boolean
Default: true

list

Display a list field (Checkbox, Radio or Select) as a vertical list or not. True is vertical.

Input: boolean
Default: true

Example: 'list' => false

list_type

Input: string
Default: null

list_type_item

Input: string
Default: null

logged_in

Show field to only logged in users.

Input: boolean
Default: false

meta_query

Input: parameters

multiple

Input: string

name

Input: string
Default: null

object_id

Input: string
Default: null

on_post_status

Lock the field value when your post is in a certain post status. A range of post statuses can be used by separating them with two hyphens (–).

Only used for Post data. on_post_status is now part of the conditions array: post_status_hide, post_status_value

Input: parameters

Examples:

// lock on publish
'on_post_status' => array(
	'value' => 'publish'
)

// lock on draft or publish
'on_post_status' => array(
	'value' => array('draft','publish')
)

// lock on all statuses between repair and closed
'on_post_status' => array(
	'value' => 'repair--closed'
)

options

Input: parameters

position

Input: string
Default: null

prefix

Input: boolean
Default: true

query

Input: parameters

redirect

Input: string
Default: null

relate

Allow this field to relate to a post type, user, comment or taxonomy.

Input: array
Default: none

Sub Parameter:

scope

The scope of the item you want to relate to.

Examples: "scope" => "post" "scope" => "user"

relate_to

Input: string
Default: null

request_value

Input: string
Default: null

required

Make a field required. If this field is not filled in the form will not save.

NOTE: Piklist uses server-side authentication instead of browser-side authentication to do required verification. The pro is that it’s more secure, the con is that the user has to press “save” before the validation kicks in.

If you want the convenience of browser-side verification you could add the HTML5 “required” attribute as well. See example below.

Input: boolean
Default: false

// required with Piklist
  piklist('field', array(
    'type' => 'text'
    ,'field' => 'text_required'
    ,'label' => 'Enter some required text'
    ,'required' => true
  ));

// required with Piklist and HTML 5
  piklist('field', array(
    'type' => 'text'
    ,'field' => 'text_required_2'
    ,'label' => 'Enter some required text'
    ,'required' => true
    ,'attributes' => array(
      'required' => 'required' // HTML 5 validation
    )
  ));

role

Set the user role that will see this field.

Input: comma-delimited
Default: none

Examples: 'role' => 'editor' 'role' => 'super-editor, editor, author'

sanitize

Untrusted data entered into your form should be sanitized and validated before saving. By default Piklist uses the WordPress $wpdb->prepare method to handle your data, insuring it is SQL-escaped before saving to prevent against SQL injection attacks.

Piklist also adds another level of sanitization you can use at the field level, and makes it easy to use. A library of sanitization functions are included with Piklist, or you can create your own.

Since data sanitization depends on the type of data and the context in which it is used, the sanitize parameter allows you to choose how to clean your data, and accepts the following parameters:

Input: parameters

Sub Parameters:

type

The type of sanitization function to run. 'type' => 'html_class'

options

An array of arguments to pass to the function. 'options' => array( 'fallback' => 'my-default-fallback' )

callback

Override the default Piklist callback function with your own. 'callback' => 'my-custom-callback

Examples:

// sanitize parameter example. Must be in field function
,'sanitize' => array(
  array(
   'type' => 'html_class'
   ,'options' => array(
     'fallback' => 'my-default-class'
   )
   ,'callback' => 'my-custom-callback'
 )
)

// Use the built-in sanitize function: file_name
  piklist('field', array(
    'type' => 'text'
    ,'label' => 'File Name'
    ,'field' => 'sanitize_file_name'
    ,'description' => 'Converts multiple words to a valid file name'
    ,'sanitize' => array(
      array(
        'type' => 'file_name'
      )
    )
  ));

save_as

Input: string

save_id

Input: string
Default: null

scope

The scope parameter tells Piklist where to save field data. In many cases this is the WordPress database table (i.e. post, post_meta, term, term_meta)

When creating fields for the WordPress admin, in most cases, you do not have to define scope. Piklist will automatically set it for you.

You MUST define scope when creating front-end forms.

Piklist allows you to mix-and-match field types within a form. So, one form can have fields that save information as post_meta, while other fields save to a taxonomy. Scope is what determines where the field data is saved. If you don’t set the scope parameter then it will default to where the field is used. For example, if you are creating a meta-box, then scope will automatically be set to post_meta. When working with front-end forms, you must set the scope for each field, so Piklist knows where to save your data.

If you want create a field that saves the post_title, then you would set scope to post, since the post_title field is in the wp_posts database table.

Input: string
Default: piklist_form::get_field_scope()

Example: 'scope' => 'post'

sortable

If set to false, will stop an add_more field from being sortable.

Input: boolean
Default: true

tax_query

Input: parameters

template

Define a Piklist field template.

Input: string

type

The type of field.

Input: string
Default: text

Examples: 'type' =>'text' 'type' =>'radio' 'type' =>'editor' 'type' =>'group'

validate

Validate this field with a set of validation rules.

Input: parameters

value

The default value for this field.

Input: string
Default: null

wrapper

Input: string
Default: null

Field Parameters

add_more (repeater)

attributes

capability

child_add_more

child_field

choices

columns

Conditions

Sub Parameters:

relation (sub parameter)

field (sub parameter)

value (sub parameter)

reset (sub parameter)

compare (sub parameter)

type (sub parameter)

scope (sub parameter)

post_status_hide (sub parameter)

post_status_value (sub parameter)

data_id

description

disable_label

display

embed

errors

field

group_field

help

id

label

label_position

label_tag

list

list_type

list_type_item

logged_in

meta_query

multiple

name

object_id

on_post_status

options

position

prefix

query

redirect

relate

Sub Parameter:

scope

relate_to

request_value

required

role

sanitize

Sub Parameters:

type

options

callback

save_as

save_id

scope

sortable

tax_query

template

type

validate

value

wrapper

Have ideas for improving the documentation?