WordPress Fields Framework
Document Last Modified: February 15 2016, 10:38:35 PM (Europe/London)
Usage Instructions
The functions listed here can be called from a theme's functions.php file or from a plugin but you must ensure not to call them directly though! They must be called using the WordPress init hook.
And for that you must first set up a function which you can attach to the init hook and place your function calls there. The following is an example of how you can go about doing this.
add_action('init', 'my_init_function'); function my_init_function() { /* Make sure the plugin is installed and active */ if(!defined('FF_INSTALLED')) { return; } // Add your function calls here! }
This plugin uses Sections to hold a set of fields. So you must first create a section before you can attach fields to it.
There are currently 6 types of sections that are supported.
If you want to create a section which you can use as a Top Level Menu then you must create a section of type 'admin_menu'.
If you want to create a section which you can use as a Sub Level Menu then you must create a section of type 'admin_sub_menu'.
If you want to create a section which you can use on Posts, Pages or any Custom Post Type then you must create a section of type 'post'.
If you want to create a section which you can use on Categories, Tags or any Custom Taxonomy then you must create a section of type 'taxonomy'.
If you want to create a section which you can use on a Widget then you must create a section of type 'widget'.
If you want to create a section which you can use on User Profile Edit Screen then you must create a section of type 'user'.
Usage Tips
Please make a habit of prefixing your UID's to avoid name clashes with settings using the same name belonging to other plugins or the WP core! Let's say you were working on a project named 'Placerat Dictum Massa' and you wanted to create a field or a section with UID 'Fusce Fringilla' then an example of a good prefixed UID would be 'pdm-fusce-fringilla' where pdm is an acronym of the project name.
Functions
object ff_create_section(string $uid, string $type [, array $arguments = null], $skip_registry = false);
Description
Let's you create a section which you can add fields to.
Return Value
Return's a Section object
Parameters
- uid
- A string which acts as a unique identifier for this section. This also serves as the menu_slug of the administration menu.
- type
-
The type of section you want to create. Current valid values include:
- admin_menu - To create a parent administration menus
- admin_sub_menu - To create a administration sub menu
- post - For Posts, Pages, Attachments and Custom Post Types
- taxonomy - For Categories, Tags and Custom Taxonomies
- widget - For Widgets
- user - For User profiles
- arguments
-
An array of parameters pertaining to the section you are trying to create. These vary depending on the type of section. All possible values for each type of section is listed below. This list also mentions which parameters are required and if whether an optional uses a default value.
Generic Arguments
Arguments used by all sections:
array( 'skip_save' => false /* Set this to true if you would like to create a section which doesn't save it's fields. */ );
Administration Menus
array( 'page_title' => null, /* Required */ 'menu_title' => null, /* Required */ 'capability' => 'manage_options', 'icon_url' => null, 'position' => null, );
Administration Sub Menus
array( 'parent_uid' => null, /* Required. This must be the uid used by the parent administration menu of which you want this to be a sub child of. This is also that parent's menu slug */ 'page_title' => null, /* Required */ 'menu_title' => null, /* Required */ 'capability' => 'manage_options', );
Posts, Pages, Attachments and Custom Post Types
array( 'id' => null, /* Required */ 'title' => null, /* Required */ 'post_types' => array(), /* Required. You must provide at least one post type. Examples include: post, page, attachment or a name of any custom post type. */ 'context' => 'advanced', 'priority' => 'default', 'page_templates' => array(), /* Used by Pages. You can specify file names of page templates here. */ 'page_templates_not' => false /* Set this to true if you want to ignore selected page templates */ 'post_ids' => array(), /* You can specify ids of posts here. */ 'post_ids_not' => false /* Set this to true if you want to ignore selected post ids */ 'post_titles' => array(), /* You can specify titles of posts here. */ 'post_titles_not' => false /* Set this to true if you want to ignore selected post titles */ 'post_slugs' => array(), /* You can specify slugs of posts here. */ 'post_slugs_not' => false /* Set this to true if you want to ignore selected post slugs */ 'post_formats' => array(), /* Used by Posts and and other Custom Post Types. You can specify a list of post formats here. */ 'post_formats_not' => false /* Set this to true if you want to ignore selected post formats */ );
Categories, Tags and Custom Taxonomies
array( 'taxonomies' => array(), /* Required. You must provide at least one taxonomy. Examples include: category, post_tag, or a name of any custom taxonomy */ );
Widget
array( 'title' => null, /* Required */ );
Users
This section takes no parameters.
- skip_registry
- If this is set to true then the section will not be added to the registry
object function ff_create_field($uid, $type, $arguments [, $skip_registry = false]);
Description
Let's you create a field.
Return Value
Return's a Field object
Parameters
- uid
- A string which acts as a unique identifier for this field. This is also used as the 'name' of the field.
- type
-
The type of field you want to create. Current valid values include:
- group
- text
- hidden
- media
- textarea
- checkbox
- radio
- select
- select_posts
- select_terms
- select_users
- editor
- datetime
- colorpicker
- arguments
-
An array of arguments which vary depending on the type of field you are creating.
Generic Arguments
Arguments used by most (but not all) fields includes:
array( 'name' => $uid /* Name attribute for the field you are creating */, 'id' => $uid /* ID attribute for the field you are creating */, 'label' => null /* Label you want to give to this field */, 'class' => null /* Class name you want this field to use. This is set to large-text by default for text, url, email and textarea fields */, 'description' => null /* Description of what this field is */, 'default_value' => null, /* A default value for this field */ 'placeholder' => null /* Text which can be used as a placeholder to describe what must be entered */, 'repeatable' => false /* Set this to true if you want this field to be repeatable. This parameter can be used with all fields except the editor field. */, 'minimal' => false /* Set this to true if you would like minimal HTML wrapping around this field. Setting this true will also remove the Label from appearing around this field. */, 'validator' => array() /* This is used by the client side validator and takes key/value pairs. Please refer to the documentation of the plugin used for validation to learn more about this: http://posabsolute.github.io/jQuery-Validation-Engine/. Examples: Make field required and make sure it is a valid email address: 'validator' => array('validation-engine' => 'validate[required,custom[email]]'), Make field required. This just ensures something is filled before submission: 'validator' => array('validation-engine' => 'validate[required]'), Make sure this field is a valid email address. This field won't be required but if it's filled then it must be a valid email address: 'validator' => array('validation-engine' => 'validate[custom[email]]'), */ );
Field Specific Arguments
Media Field
array( 'library' => null /* You can specify which types of media you want the media selector to display. Separate types by comma, for example: 'image, application/pdf', etc. */, );
Textarea Field
array( 'rows' => 5, 'cols' => 50, );
Select, Checkbox and Radio
array( 'options' => array() /* Must be an array of options. If you don't use a key/value pair, then the array will be treated as an indexed array. */, );
Select and Checkbox
array( 'multiple' => false or true /* This is not the same as the repeatable argument! This specifies whether multiple options can be selected or not. The default value for select field is false where as for checkbox it's true */, );
Select
array( 'size' => 5 /* Used by the select field if multiple is set to true. Specifies number of elements visible in the selection box */, 'prepend_blank' => true, /* If set to true then a blank key/value pair will be prepended to the list of options. You can use the placeholder argument instead if you don't want the value of the prepended option to be blank */ );
Select Posts
array( 'parameters' => array(), /* Refer to the Parameters section on this page: http://codex.wordpress.org/Class_Reference/WP_Query */ );
Select Terms
array( 'taxonomies' => array(), /* Required. You must provide at least one taxonomy. Examples include: category, post_tag, or a name of any custom taxonomy */ 'parameters' => array(), /* Refer to the Arguments section on this page: http://codex.wordpress.org/Function_Reference/get_terms */ );
Select Users
array( 'parameters' => array(), /* Refer to the Parameters section on this page: http://codex.wordpress.org/Function_Reference/get_users */ );
Editor
array( 'settings' => array(), /* Refer to the Arguments section on this page: http://codex.wordpress.org/Function_Reference/wp_editor */ );
DateTime
array( 'date_format' => 'mm/dd/yy', /* Format details for this argument can be found here: http://api.jqueryui.com/datepicker/ - Set this to -1 if you don't want to a Date. */ 'time_format' => 'hh:mm:ss tt', /* Format details for this argument can be found here: http://trentrichardson.com/examples/timepicker/#tp-formatting - Set this to -1 if you don't want to a Time. */ );
- skip_registry
- If this is set to true then the field will not be added to the registry
void function ff_add_field_to_section($section_uid, $field_uid);
Description
Let's you associate a field to a particular section.
Parameters
- section_uid
- A string referring to the unique identifier of the section you want the field assigned to
- field_uid
- A string referring to the unique identifier of the field you want assigned to the section
void ff_add_field_to_field_group($field_group_uid, $field_uid);
Description
Let's you associate a field to a field group.
Parameters
- field_group_uid
- A string referring to the unique identifier of the field group you want the field assigned to
- field_uid
- A string referring to the unique identifier of the field you want assigned to the field group
mixed ff_get_field_from_section($section_uid, $field_uid, $source [, $source_type = null, $object_id = null]);
Description
Let's you fetch a value of a field belonging to a certain section so that you can display it on the frontend.
Parameters
- section_uid
- A string referring to the unique identifier of the section you want the field retrieved from
- field_uid
- A string referring to the unique identifier of the field you want retrieved from the section
- source
- For Posts and Users this should be 'meta' and for Taxonomies and Administration Menus it should be 'options'
- source_type
- For Posts this should be 'post', for Users this should be 'user' and for Taxonomies this should be 'taxonomy'. Leave this blank for Administration Menus
- object_id
- Pass your post, user or taxonomy id depending on your source type. Leave blank for Administration Menus
array ff_get_all_fields_from_section($section_uid, $source [, $source_type = null, $object_id = null]);
Description
Let's you fetch all field values belonging to a certain section so that you can display it on the frontend.
Parameters
- section_uid
- A string referring to the unique identifier of the section you want the field retrieved from
- source
- For Posts and Users this should be 'meta' and for Taxonomies and Administration Menus it should be 'options'
- source_type
- For Posts this should be 'post', for Users this should be 'user' and for Taxonomies this should be 'taxonomy'. Leave this blank for Administration Menus
- object_id
- Pass your post, user or taxonomy id depending on your source type. Leave blank for Administration Menus
do_action('ff_wp_widget', $section_uid, $values);
Description
An action hook which let's you fetch all field values belonging to a Widget section so that you can display them on the frontend. You need to hook a function to this action.
Example
add_action('ff_wp_widget', 'custom_function_name', 10, 2); function custom_function_name($section_uid, $values) { }
Parameters
- section_uid
- A string referring to the unique identifier of the Widget section you want the field retrieved from
- values
- A variable which holds all the values belonging to a Widget
Examples for functions ff_create_section, ff_create_field, ff_add_field_to_section and ff_add_field_to_field_group
Administration Menu
ff_create_section('duis-aliquet-velit', 'admin_menu', array('page_title' => 'Duis Aliquet Velit', 'menu_title' => 'Duis Aliquet Velit' )); ff_create_field('et-interdum', 'text', array( 'label' => 'Et Interdum', 'repeatable' => true )); ff_add_field_to_section('duis-aliquet-velit', 'et-interdum'); ff_create_field('pellentesque-et-leo', 'text', array( 'label' => 'Pellentesque Et leo', 'repeatable' => true )); ff_add_field_to_section('duis-aliquet-velit', 'pellentesque-et-leo'); ff_create_field('vestibulum-quis', 'media', array( 'label' => 'Vestibulum Quis', 'library' => 'image' )); ff_add_field_to_section('duis-aliquet-velit', 'vestibulum-quis');
Administration Sub Menus
ff_create_section('ante-vitae-nisl', 'admin_sub_menu', array('parent_uid' => 'duis-aliquet-velit', 'page_title' => 'Ante Vitae Nisl', 'menu_title' => 'Ante Vitae Nisl' )); ff_create_field('eleifend-varius', 'textarea', array( 'label' => 'Eleifend Varius', ) ); ff_add_field_to_section('duis-aliquet-velit', 'eleifend-varius'); ff_create_field('quisque-urna', 'editor', array( 'label' => 'Quisque Urna', 'repeatable' => true, )); ff_add_field_to_section('duis-aliquet-velit', 'quisque-urna'); ff_create_field('sollicitudin-justo', 'hidden', array('value' => 'Vitae Rhoncus')); ff_add_field_to_section('duis-aliquet-velit', 'sollicitudin-justo'); ff_create_field('nam-tempor', 'select', array( 'label' => 'Nam Tempor', 'options' => array('Quisque vel augue', 'Proin rutrum nulla', 'Etiam at nulla', 'Nullam quis dolor', 'Nulla et velit', 'Morbi ac nisi' ), 'multiple' => true, 'repeatable' => true )); ff_add_field_to_section('duis-aliquet-velit', 'nam-tempor'); ff_create_field('praesent-pellentesque', 'checkbox', array( 'label' => 'praesent-pellentesque', 'options' => array('Donec vitae', 'Mauris pretium', 'Nullam accumsan justo', 'Aliquam imperdiet', 'Morbi nec turpis', 'Nulla ut felis' ), 'multiple' => true, )); ff_add_field_to_section('duis-aliquet-velit', 'praesent-pellentesque');
Posts, Pages, Attachments and Custom Post Types
ff_create_section('donec-feugiat-dui', 'post', array( 'post_types' => array('post'), 'title' => 'Donec Feugiat Dui', )); ff_create_field('maecenas-aliquet', 'group', array( 'label' => 'Maecenas Aliquet', 'repeatable' => true )); ff_add_field_to_section('donec-feugiat-dui', 'maecenas-aliquet'); ff_create_field('vestibulum-lobortis', 'text', array( 'label' => 'Vestibulum Lobortis', )); ff_add_field_to_field_group('maecenas-aliquet', 'vestibulum-lobortis'); ff_create_field('ut-quis-libero', 'text', array( 'label' => 'Ut Quis Libero', )); ff_add_field_to_field_group('maecenas-aliquet', 'ut-quis-libero'); ff_create_field('integer-rutrum', 'text', array( 'label' => 'Integer Rutrum', 'repeatable' => true )); ff_add_field_to_field_group('maecenas-aliquet', 'integer-rutrum'); ff_create_field('donec-bibendum', 'group', array( 'label' => 'Donec Bibendum', 'repeatable' => true )); ff_add_field_to_field_group('maecenas-aliquet', 'donec-bibendum'); ff_create_field('maecenas-posuere', 'text', array( 'label' => 'Maecenas Posuere', 'repeatable' => true )); ff_add_field_to_field_group('donec-bibendum', 'maecenas-posuere'); ff_create_field('etiam-commodo-erat', 'text', array( 'label' => 'Etiam Commodo Erat', 'repeatable' => true )); ff_add_field_to_field_group('donec-bibendum', 'etiam-commodo-erat');
Categories, Tags and Custom Taxonomies
ff_create_section('donec-pharetra-neque', 'taxonomy', array( 'taxonomies' => array('category'), )); ff_create_field('aenean-consequat', 'text', array( 'label' => 'Aenean Consequat', )); ff_add_field_to_section('donec-pharetra-neque', 'aenean-consequat');
Users
ff_create_section('mauris-id-arcu-quis', 'user'); ff_create_field('cras-vel-metus', 'group', array( 'label' => 'Cras Vel Metus', 'repeatable' => true )); ff_add_field_to_section('mauris-id-arcu-quis', 'cras-vel-metus'); ff_create_field('curabitur-a-ligula', 'text', array( 'label' => 'Curabitur a Ligula', )); ff_add_field_to_field_group('cras-vel-metus', 'curabitur-a-ligula'); ff_create_field('fusce-quis-libero', 'text', array( 'label' => 'Fusce Quis Libero', )); ff_add_field_to_field_group('cras-vel-metus', 'fusce-quis-libero');
Frontend Functions
echo '<pre>'; print_r(ff_get_all_fields_from_section('donec-feugiat-dui', 'meta', 'post', 292)); print_r(ff_get_all_fields_from_section('donec-feugiat-dui', 'meta', 'post', $post->ID)); print_r(ff_get_all_fields_from_section('donec-feugiat-dui', 'meta', 'post', get_queried_object()->ID)); print_r(ff_get_field_from_section('donec-pharetra-neque', 'integer-viverra-volutpat', 'options', 'taxonomy', 5)); print_r(ff_get_field_from_section('donec-pharetra-neque', 'integer-viverra-volutpat', 'options', 'taxonomy', get_queried_object()->term_taxonomy_id)); echo '</pre>';