-
Notifications
You must be signed in to change notification settings - Fork 97
Field Arrays
Each field needs at least the minimum of three variables, the label, id, and type. Some fields require more to work and you should also make sure that you equip each field with the proper sanitizer unless the default sanitize_text_field is desired. Here's a rundown of how to call each available field type in the fields array.
Your basic text, textarea, and checkbox fields only require the minimum variables. The library is also equipped to accept the types tel, email, number, and url. Just make sure you add the proper sanitizer to the array so that those values get validated and stored properly.
array( 'label' => 'Text Input', 'desc' => 'A description for the field.', 'id' => $prefix . 'text', 'type' => 'text' ), array( 'label' => 'Textarea', 'desc' => 'A description for the field.', 'id' => $prefix . 'textarea', 'type' => 'textarea', 'sanitizer' => 'wp_kses_data' ), array( 'label' => 'Checkbox Input', 'desc' => 'A description for the field.', 'id' => $prefix . 'checkbox', 'type' => 'checkbox', 'sanitizer' => 'meta_box_santitize_boolean' )
Fields that have preset options will require this additional array to set those. Make sure that as you create the array, you name the key the same as the value of the option because the library will use that to confirm the stored selection. For the select and chosen fields, you can also add 'multiple' => true to turn it into a multi-select box. Try combining chosen and the multiple setting for a real good time!
array( 'label' => 'Select Box', 'desc' => 'A description for the field.', 'id' => $prefix . 'select', 'type' => 'select', 'options' => array ( 'one' => array ( 'label' => 'Option One', 'value' => 'one' ), 'two' => array ( 'label' => 'Option Two', 'value' => 'two' ), 'three' => array ( 'label' => 'Option Three', 'value' => 'three' ) ) ), array( 'label' => 'Chosen Select Box', 'desc' => 'A description for the field.', 'id' => $prefix . 'select', 'type' => 'chosen', 'multiple' => true, 'options' => array ( 'one' => array ( 'label' => 'Option One', 'value' => 'one' ), 'two' => array ( 'label' => 'Option Two', 'value' => 'two' ), 'three' => array ( 'label' => 'Option Three', 'value' => 'three' ) ) ), array ( 'label' => 'Radio Group', 'desc' => 'A description for the field.', 'id' => $prefix . 'radio', 'type' => 'radio', 'options' => array ( 'one' => array ( 'label' => 'Option One', 'value' => 'one' ), 'two' => array ( 'label' => 'Option Two', 'value' => 'two' ), 'three' => array ( 'label' => 'Option Three', 'value' => 'three' ) ) ), array ( 'label' => 'Checkbox Group', 'desc' => 'A description for the field.', 'id' => $prefix . 'checkbox_group', 'type' => 'checkbox_group', 'options' => array ( 'one' => array ( 'label' => 'Option One', 'value' => 'one' ), 'two' => array ( 'label' => 'Option Two', 'value' => 'two' ), 'three' => array ( 'label' => 'Option Three', 'value' => 'three' ) ) )
These fields all require a bit of extra javascript to run, but are fun to have. They are pretty self explanatory.
array( 'label' => 'Date', 'desc' => 'A datepicker field that will store the date in the format yy-mm-dd', 'id' => $prefix . 'date', 'type' => 'date' ), array( 'label' => 'Slider', 'desc' => 'A description for the field.', 'id' => $prefix . 'slider', 'type' => 'slider', 'min' => '0', 'max' => '100', 'step' => '5' ), array( 'label' => 'Image', 'desc' => 'A button that opens the media uploader and displays a thumbnail as a preview, but stores the attachment ID', 'id' => $prefix . 'image', 'type' => 'image' ), array( 'label' => 'File', 'desc' => 'A button that opens the media uploader and stores the file's URL.', 'id' => $prefix . 'file', 'type' => 'file' ), array( 'label' => 'Color', 'desc' => 'Previews the hexidecimal color and opens a color chooser when the field is clicked.', 'id' => $prefix . 'color', 'type' => 'color', )
There are a few options for calling lists of taxonomies and posts of any type as options. If you're including a tax_select field, the library will use that to set the taxonomy terms for the post. Because of this, it will be necessary to remove the taxonomy meta box that WordPress adds, else it and your custom meta box will just try to overwrite each other and nothing will get saved. Also, the id for this field shouldn't include a prefix and should be EXACTLY the taxonomy name in order for it to get and store information correctly.
The post selection fields store the post ID so make sure you sanitize it as an integar. In addition to the post_select field, you can also call a post_chosen in the same manner. This will turn the select box into a chosen field which adds a bit of extra magic. Also note that just like a regular select box, you can set 'multiple' => true to turn it into a multi-select.
You can also use tax_checkboxes and post_checkboxes if you'd prefer to select multiple terms and posts using checkboxes.
array( 'label' => 'Category', 'id' => 'category', 'type' => 'tax_select' ), array( 'label' => 'Post List', 'desc' => 'A description for the field.', 'id' => $prefix . 'post_id', 'type' => 'post_select', 'post_type' => array( 'post', 'page' ), 'sanitizer' => 'intval' )
This field is super niche, but I had to build it for a client and loved the way it turned out, so I figured I would add it to the library. This field has a lot of options, but if you need to store an array of post ID's in a certain order and want to select those by dragging and dropping the posts' set featured image, this is a great, user friendly way to do it. Once you have the field setup, you get at least two drag and drop areas. The ones on the left will be for storing your sorted selection, and the one on the right will be a list of posts to choose from. If you set 'display' = 'thumbnail', the posts will be represented by their featured image.
Since I was originally using this field to select from the Sponsors custom post type and assign those to an even post type, I've left that as my example in the array below.
array( 'label' => 'Sponsors', 'desc' => 'Drag and drop sponsors to their level of sponsorship', 'id' => $prefix . 'sponsors', 'type' => 'post_drop_sort', 'sanitizer' => array ( 'intval' ), 'post_type' => 'sponsor', 'display' => 'thumbnail', 'areas' => array( 'presenting' => array ( 'label' => 'Presenting Sponsor', 'id' => 'presenting' ), 'media' => array ( 'label' => 'Media Sponsor', 'id' => 'media' ), 'partners' => array ( 'label' => 'Partners', 'id' => 'partners' ), 'supporters' => array ( 'label' => 'Supporters', 'id' => 'supporters' ) ) )
There is support for wp_editor but pay very close attention, else you'll be pulling your hair out like I did. You cannot have dashes or underscores in your id/name for this field. You can add in the custom settings for this field (see Codex) and must include this option in the array with a minimum of the textarea_name as outlined below.
array( 'label' => 'WYSIWYG Field', 'desc' => 'A description goes here', 'id' => 'editorField', 'type' => 'editor', 'sanitizer' => 'wp_kses_post', 'settings' => array( 'textarea_name' => 'editorField' ) )
Probably the most popular field of this library is this fancy dancy repeatable. It will add a section of fields and a plus button. Click the plus button to add a new row of fields. Delete a row by clicking it's minus button. Click the row's handle to drag and drop them all into the order you want.
There are two things to pay extra close attention to here. First, make sure you get the arrays nested correctly for the fields, especially if you are adding a more complex one such as a select box. Secondly, your sanitizer HAS to be called and HAS to be an array with the same exact key names in the same exact order as the fields.
Note: As of this writing(January 11, 2013), all of the regular fields previously covered are technically supported, but not all of them have been tested. I can pretty much guarantee you that post_drop_sort is going to break your internets so don't use it.
array( 'label' => 'Repeatable', 'desc' => 'A description for the field.', 'id' => $prefix . 'repeatable', 'type' => 'repeatable', 'sanitizer' => array( 'featured' => 'meta_box_santitize_boolean', 'title' => 'sanitize_text_field', 'desc' => 'wp_kses_data' ), 'repeatable_fields' => array ( 'featured' => array( 'label' => 'Featured Item?', 'id' => 'featured', 'type' => 'checkbox' ), 'title' => array( 'label' => 'Title', 'id' => 'title', 'type' => 'text' ), 'desc' => array( 'label' => 'Description', 'id' => 'desc', 'type' => 'textarea' ) ) ) ;