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

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

field

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

value

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

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

compare

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

Example: 'compare' => '!='

type

Piklist supports two condition types; toggle and update. * default: toggle

Example: 'type' => update

scope

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

post_status_hide

post_status_value

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. This is the name that will be saved to your database.

  • Input: string Example: 'field' => 'my_field'

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

The position of your label relative to your field.

  • 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:

'on_post_status' => array(
	'value' => 'publish'
)
'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

request_value

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

The default value for this field.

  • Input: string
  • Default: null

Have ideas for improving the documentation?

This documentation is a community effort. Please create an issue or pull request to help!

Improve this page