Developer’s Custom Fields documentation

Developer’s Custom Fields is a plugin for WordPress. It’s designed to give developers (usually, custom theme developers) tools that make it easy to manage custom fields (a.k.a. metadata) for any post type and for user profiles.

This plugin is still supported, but is no longer being actively developed, and is disabled for new installations on wordpress.org.

Development code is hosted on GitHub. Please find issue tracking there too.

This documentation is for version 1.3.2.

Configuration
- Constants
- Settings
Functions
Shortcodes
Option query placeholders
Hooks
To do + ideas

Configuration

Constants

Some defaults will be overridden if the relevant constant is defined in wp-config.php.

SLT_CF_USE_GMAPS (boolean) (default: true): If set to false, disables all Google Maps functionality.
SLT_CF_GMAPS_API_KEY (boolean) (no default): If set, this will be appended to the Google Maps JS URL, in order to make use of the Google Maps API.
SLT_CF_USE_FILE_SELECT (boolean) (default: true): If set to false, disables the file field type functionality.
SLT_CF_HANDLE_TERM_SPLITTING (boolean) (default: false): If set to true, handles WP 4.2+ term splitting. Consider this beta code, and please read notes in this post.

If for some reason you can’t define these in wp-config.php, just create a simple plugin file to put them in, and name the plugin with something beginning with “A”. Then it’ll load before this plugin with the constants defined.

Settings

By design, this plugin has no settings page. To change any of the default settings, use slt_cf_setting to set the following keys to the required values. (See Functions for syntax.)

prefix (string) (default: '_slt_'): To avoid clashes with other plugins, all custom fields are stored in the database with a prefix on the key name. An underscore at the start means these values won’t show up in the default WordPress custom fields meta box. If you want to use a different prefix, set it at the start of your theme’s functions.php before you start using any custom fields, and never change it!
hide_default_custom_meta_box (boolean) (default: true): Whether or not to hide the default custom fields meta box on post edit screens.
css_url (string): The URL of a stylesheet file to override the built-in slt-cf-admin.css stylesheet.
datepicker_css_url (string) (DEPRECATED): Former key for ui_css_url
ui_css_url (string): The URL of a stylesheet file to override the built-in theme for the jQuery date and time components (Smoothness).
datepicker_default_format (string) (default: 'dd/mm/yy'): The default format for the jQuery datepicker. For available formats, see http://docs.jquery.com/UI/Datepicker/formatDate. This can be overridden for particular fields. NOTE: Change this to yy/mm/dd if you want to be able to easily sort by date fields!
timepicker_default_format (string) (default: 'hh:mm tt'): The default format for the jQuery timepicker. For available formats, see http://trentrichardson.com/examples/timepicker/. This can be overridden for particular fields.
timepicker_default_ampm (boolean) (default: false): The default setting for the jQuery timepicker hour format. Set to true uses 12-hour format; false uses 24-hour format. This can be overridden for particular fields.

Functions

Settings

`<?php slt_cf_setting( $key, $value ); ?>`

Run this function on the init action. NOTE: Since version 0.8, the function attached to the init action that contains this function must be set to lower than normal priority, i.e. 11 or higher, to ensure proper functioning for all settings.

$key (string) (required): The key of the setting you want to update
$value (mixed) (required): The value you want to set the setting to

See Configuration for the various settings.

Registering boxes and fields

`<?php slt_cf_register_box( $box ); ?>`

Run this function on the init action.

$box is an array of values defining the box:

type ( string | array ) (required) ( 'post' | 'user' | 'attachment' ): The type of box, i.e. which type of object its fields are applied to. Field-specific refinement of this is given by each field’s scope parameter (see below). You can pass multiple values in an array.
id (string) (required): A unique ID for the box.
title (string) (required): A title for the box.
description (string) (optional): A description for the box.
context (string) (optional) ( 'normal' | 'advanced' | 'side' | 'above-content' ) (default: 'advanced'): The context for boxes on post edit screens, i.e. where on the edit screen it appears. A special value, above-content, will place the box using the normal setting in the add_meta_box function, but then use jQuery to place it above the content editor.
priority (string) (optional) ( 'low' | 'default' | 'high' ) (default: 'default'): On post edit screens, this governs how high up within the box’s context it will appear.
fields (array) (required): The field definitions for this box.

The fields array should contain an array for each field, defining the following values:

name (string) (required)

A unique name for the field.

label (string) (required)

A label for the field. For multiple checkboxes and radio buttons, this label is actually for the legend element; each input’s label is created from the specified options.

The type of input for the field.

File uploads are currently not allowed for user profiles or attachments.
The notice field type isn’t an actual form field; just use the description parameter to output a notice to the user.
The attachments_list field type can only be used for posts (not user profiles or attachments). This outputs all the uploads attached to the current post. Further options can be configured using the attachments_list_options parameter.

scope (array) (required)

The box’s type parameter defines whether the box will appear for posts, users, or attachments (see above). This scope parameter further refines which fields will appear in the box for any given edit screen.

For fields in post meta boxes, the scope defines which post type(s) the field should apply to, e.g. array( 'post', 'page' ).
To apply to posts (of any type) assigned to terms in a taxonomy, pass the taxonomy name as the key, with an array of term names as the value, e.g. array( 'category' => array( 'A Category' ) ).
To apply to posts with particular formats, use array( 'post_format' => array( 'video', 'link' ) ).
To apply to pages associated with particular templates, use array( 'template' => array( 'page_template.php' ) ).
For fields in user profiles, the scope defines which user role(s) the field should apply to, e.g. array( 'administrator', 'editor' ). Note that to include the field in the registration form and the new user form, the value 'registration' should be included, and the New User Default Role (in Settings > General Settings) should also be present.
For fields for attachments, the scope can define the MIME types the field should apply to, e.g. array( 'image/png', 'image/jpeg', 'image/gif' ) (pass an empty array to apply to all attachments).
To apply to particular posts, users or attachments by ID, use something like array( 'posts' => array( 49, 66 ) ).
To exclude particular posts or attachments, add 'except_posts' => array( 67, 42 ) to the array.
There’s also an except_users option to exclude particular users.

label_layout (string) (optional) ( 'block' | 'inline' ) (default: 'block')

How to position the label in relation to the input.

‘block’ puts the label on its own line above the input.
For text, file uploads and selects, ‘inline’ will put the input on the same line as the label.
Textarea and WYSIWYG fields always have ‘block’ labels; single checkboxes always have ‘inline’ labels.

hide_label (boolean) (optional) (default: false)

Whether to hide the label. Use with care!

file_button_label (string) (optional) (default: 'Select file')

A label for the button in when field type is file.

file_attach_to_post (boolean) (optional) (default: true)

For file fields, this signals whether to attach uploaded files to the current post.

file_removeable (boolean) (optional) (default: true)

For file fields, this signals whether to include a checkbox to remove the file from the field.

file_dialog_title (string) (optional) (default: 'Select file')

For file fields, this is the title for the media upload/select dialog.

file_restrict_to_type (string) (optional) (default: '')

For file fields, this restricts the type of file output in the upload/select dialog. Options are: '' (shows all files) and 'image' or 'audio' or 'video'.

input_prefix (string) (optional)

A prefix to place before the input. Only applicable to text and single-choice select fields.

input_suffix (string) (optional)

A suffix to place after the input. Only applicable to text and single-choice select fields.

description (string) (optional)

A description for the field.

default (mixed) (optional)

Default value(s) for the field. For multiple select inputs and checkboxes, this should be an array of values. (Note: for checkboxes that are sortable, you can pass 'force-all' here, and all items will be checked by default. This allows such fields to be used purely for sorting.) For gmap fields, it should also be an array, with the following keys: centre_latlng, zoom, marker_latlng.

multiple (boolean) (optional) (default: false)

For select inputs, whether the select should allow multiple values.

sortable (boolean) (optional) (default: false)

For multiple checkbox inputs, setting this option to true makes use of jQuery UI Sortable. An extra field is automatically created to store the order. When a sortable field’s values are returned using any of this plugin’s functions, they are returned in the right order. The ordering can be obtained independently with the slt_cf_field_values_order() function.

checkboxes_thumbnail (boolean) (optional) (default: false)

For multiple checkbox inputs that list attachment images, whether a thumbnail should be shown in the list. Use the slt_cf_checkboxes_thumbnail_size filter to alter the image size used.

options_type (string) (optional) ( 'static' | 'posts' | 'users' | 'terms' ) (default: 'static')

For multiple select inputs and checkboxes, what type of options are being supplied.

‘static’ means you need to supply the options
‘posts’ means the input will be populated with the results of a WP_Query query
‘users’ means the input will be populated with users
‘terms’ means the input will be populated with taxonomy terms

make_query_var (boolean) (optional) (default: false)

If set to true, the custom field will be automatically registered as a query variable, so WP_Query will recognise it in a query string when parsing the request.

NOTE: Query vars from the query string are normally only recognised by the main loop query. To get custom fields to apply to custom queries, pass dcf_use_query_string (set to true) to your custom WP_Query.
To determine how multiple values for a single query var are matched, use dcf_query_string_matching in your query – set to 'inclusive' (default) or 'exclusive'.
By default, custom taxonomies will also be parsed from the query string when dcf_use_query_string is set. If for some reason you want a custom query to only deal with custom field vars in the query string, set dcf_custom_field_query_vars_only to true as well.
NOTE: If the Simple Events plugin is being used, the start date field can be made into a query variable by setting the constant SLT_SE_EVENT_DATE_QUERY_VAR_FORMAT in your theme, to either ‘Y’ or ‘mY’, according to the format.

options (array) (optional)

For ‘static’ options type fields (see above), an array of option values.

The format should be: array( 'Field label 1' => 'Field value 1', 'Field label 2' => 'Field value 2' ).
Option groups for select inputs are supported; include entries in the array like this: array( 'Option group label' => '[optgroup]' ).

options_query (array) (optional) (default for posts: array( 'posts_per_page' => -1 ); default for users: array())

The query parameters when options_type isn’t ‘static’.

For ‘posts’ option type fields, this value is passed to WP_Query to populate the options.
For ‘users’ option type fields, this should be an array of roles from which users are selected; an empty value means all users.
For ‘terms’ option type field, this should be an array that will be passed as the $args parameter of a call to get_terms. A taxonomies key should be included in the array – it will be extracted and passed as the $taxonomies parameter for get_terms, e.g. 'options_query' => array( 'taxonomies' => 'category', 'hide_empty' => false ).
Dynamic placeholders can also be used: see Option Query Placeholders.

no_options (string) (optional) (default: 'No options to choose from.')

Text to display if there’s no options returned for populating the field.

exclude_current (boolean) (optional) (default: true)

For posts and users options queries, whether to exclude the object being edited from the options. Note that even more flexibility can be achieved with the Option Query Placeholders.

single (boolean) (optional) (default: true)

For fields that have multiple values (e.g. multiple checkboxes and selects), setting this to false will create multiple fields in the postmeta table, instead of storing a serialized array of values in one field. This allows for more flexible use of the meta_query parameter for queries. When you grab this kind of field with all other fields using slt_cf_all_field_values, remember to pass this field’s key in the $multiple_fields array.

required (boolean) (optional) (default: false)

Currently only relevant for non-static options type fields. By default, an empty option will be included to allow no option to be selected. The empty option will use the empty_option_text value.

empty_option_text (string) (optional) (default: '[None]')

If required is false, this is the text used for the empty option.

group_options (boolean) (default: false)

For non-static option types, setting this to true means the items will be grouped, e.g. for users, by role; for posts, by category (unless group_by_post_type is active). Currently only works properly with select field types.

group_by_post_type (boolean) (default: false)

For post queries that include multiple post types, setting this to true will group items by post type (note: overrides any grouping activated by group_options). Currently only works properly with select field types.

abbreviate_option_labels (boolean) (optional) (default: true)

By default, label text for select options populated by an options_query is abbreviated (long labels can cause problems with select where the vertical scrollbar is lost off the side of the screen, and are generally unwieldy). If this abbreviation is causing problems, use this flag to turn it off.

width (integer) (optional)

A width in em units for the input. For the gmap field type, the unit is pixels.

height (integer) (optional)

A height in em units for the input. For the gmap field type, the unit is pixels.

capabilities (array) (optional) (default for posts: array( 'edit_posts' ); default for users: array( 'edit_users' ))

The capabilities define which capabilities allow a user to manage this field. The field will appear for a user who has any of the capabilities given.

edit_on_profile (boolean) (optional) (default: false)

If this is set to true for a user field, even if the logged in user doesn’t have the capability to edit the field (as defined by capabilities), they will be able to edit this field on their own profile. If capabilities is passed an empty array and this is set to true, the field will only be editable by anyone for themselves, on their profile.

charcounter (boolean) (optional) (default: false)

For textarea and textile fields, whether a JavaScript character counter should appear.

color_preview (boolean) (optional) (default: false)

For non-multiple selects, radio buttons and plain text inputs, if the current value is a valid hex colour, this will display a preview of the color next to the input.

allowtags (array) (optional) (DEPRECATED)

For text and textarea field types, this array can specify HTML tags to be allowed, e.g. array( 'a', 'em', 'strong' ). By default, all tags are stripped. Note: as of version 0.7.2 of this plugin, the allowed_html parameter should be used instead of this.

allowed_html (array) (optional)

For text, textarea and WYSIWYG field types, this array can specify HTML tags to be allowed. The array is passed to wp_kses(), and it should follow the format for its $allowed_html parameter, e.g. array( 'p' => array(), 'a' => array( 'href', 'title' ) ). By default, if the user does not have the unfiltered_html capability, all tags are stripped from text and texarea fields; for WYSIWYG fields, the default allowed HTML is take from the WordPress $allowedposttags variable (see Otto’s post). If the user has the unfiltered_html capability, and nothing is passed for this parameter, nothing is stripped.

autop (boolean) (optional) (default: false)

For textarea and textile fields, whether to automatically add paragraph and line break tags.

wysiwyg_settings (array) (optional) (default: array( 'teeny' => true, 'media_buttons' => false ))

For WYSIWYG fields (WordPress 3.3+ only), this array is passed as the $settings to the wp_editor function. See WP source for details.

preview_size (string) ( 'thumbnail' | 'medium' | 'large' | 'full' ) (optional) (default: 'medium')

For file uploads, this specifies the size of image that should be shown when an image has been uploaded.

datepicker_format (string) (optional) (default: datepicker_default_format)

The format for the jQuery datepicker. For available formats, see http://docs.jquery.com/UI/Datepicker/formatDate. Note that if you’re going to order queries by this field, you’ll need to format accordingly, e.g. yy/mm/dd.

timepicker_format (string) (optional) (default: timepicker_default_format)

The format for the jQuery timepicker. For available formats, see http://trentrichardson.com/examples/timepicker/.

timepicker_ampm (string) (optional) (default: timepicker_default_ampm)

The jQuery timepicker hour format. Set to true uses 12-hour format; false uses 24-hour format.

location_marker (boolean|int) (optional) (default: 1)

For gmap fields, this signals whether or not markers can be placed to pinpoint locations. Since 1.3, besides accepting boolean values, this also accepts integers in order to control how many markers can be set. Using 0 (zero) is the same as passing false.

gmap_type (string) (optional) ( 'hybrid' | 'roadmap' | 'satellite' | 'terrain' ) (default: 'roadmap')

For gmap fields, sets the initial map view type.

attachments_list_options (array) (optional)

For attachments_list fields, which display all the uploads attached to the current post. Options are as follows:

post_mime_type (string) (optional) (default: image) – MIME type of files to list – corresponds to the same parameter for get_children(). Pass an empty value to list all attachments.
image_display_size (string) (optional) (default: thumbnail) – Size to display images in list. If non-image files are being listed, this image size will be used for the blocks representing each file.
unattach_checkboxes (boolean) (optional) (default: true) – Whether or not to include checkboxes to unattach files.

Retrieving values

`<?php slt_cf_field_value( $key [, $type, $id, $before, $after, $echo, $single ] ); ?>`

$key (string) (required): The key of the field. The prefix is added automatically.
$type (string) (optional) ( 'post' | 'user' ) (default: 'post'): The type of object this field applies to.
$id: (integer) (optional) – The ID of the object this field applies to. When $type is set to ‘post’, this defaults to the current post ID.
$before (string) (optional) (default: ''): Some text or HTML to prepend to the value. Only included if there is a value to return.
$after (string) (optional) (default: ''): Some text or HTML to append to the value. Only included if there is a value to return.
$echo (boolean) (optional) (default: false): Whether to echo or return the value.
$single (boolean) (optional) (default: true ): Set this to false when the field has been defined with single set to false.

`<?php slt_cf_all_field_values( [ $type, $id, $multiple_fields ] ); ?>`

$type (string) (optional) ( 'post' | 'user' | 'attachment' ) (default: 'post'): The type of object.
$id (integer) (optional): The ID of the object. When $type is set to ‘post’, this defaults to the current post ID.
$multiple_fields (array) (optional): Keys for all the fields that are stored in multiple meta table fields, and should be returned as arrays. This is usually when you’ve set the $single parameter for a field to false.

`<?php slt_cf_field_key( $key[, $object_type ] ); ?>`

$key (string) (required): The key to put the prefix on.
$object_type (string) (optional) ('post' | 'user' | 'attachment') (default: 'post'): The object type. It’s only really important to pass this when the object is an attachment, because attachments get the leading underscore stripped from the prefix.

`<?php slt_cf_field_values_order( $key [, $type, $id ] ); ?>`

Returns comma-delimited ordered list of values. Only applicable to multiple checkbox fields with the sortable flag set. Note that the above functions to return values will automatically return them ordered according to this list.

$key (string) (required): The key of the field. The prefix is added automatically.
$type (string) (optional) ( 'post' | 'user' ) (default: 'post'): The type of object this field applies to.
$id: (integer) (optional) – The ID of the object this field applies to. When $type is set to ‘post’, this defaults to the current post ID.

`<?php slt_cf_reverse_date( $date_string[, $sep, $to_timestamp ] ); ?>`

If you’ve set the format for a date field to yy/mm/dd, to enable easy sorting, when you output the date you can use this function to reverse it. It optionally returns a timestamp for alternative formatting using date:

$date_string (string) (required): The date string to reverse.
$sep (string) (optional) (default: '/'): The separator character.
$to_timestamp (boolean) (optional) (default: false): Whether to return a timestamp or not.

Other useful functions

`<?php slt_cf_get_posts_by_custom_first( $key [, $query, $custom_order, $numeric, $object_type] ); ?>`

NOTE: This function currently doesn’t work. Probably needs a new approach. Let me know if you have one!

This function gets posts, but sorts first by the specified custom field key, then by a standard WordPress field.

$key (string) (required): The key of the custom field to sort by first (prefix not needed).
$query (array) (optional) (default: array()): The WP_Query parameters, as per http://codex.wordpress.org/Function_Reference/WP_Query#Parameters – including the second lot of ordering parameters.
$custom_order (string) (optional) ( 'ASC' | 'DESC' ) (default: 'DESC'): The order value for the custom field ordering.
$numeric (boolean) (optional) (default: false): Set to true if the custom field value to be ordered by is numeric.
$object_type (string) (optional) ( 'post' | 'attachment' ) (default: 'post'): The… er… object type.

Google maps

`<?php slt_cf_gmap( $type = 'output', $name = 'gmap', $values = 'stored_data', $width = 500, $height = 300, $location_markers = null, $map_type_id = 'roadmap', $echo = true, $js_callback = '', $required = true, $object_type = 'post' ); ?>`

This function outputs a Google Map, for display or for use in a form. It’s used internally, but is also designed to be leveraged by theme code or by other plugins.

$type (string) (optional) ( 'output' | 'input' ) (default: 'output')

Whether the map is for display or for use in a form.

$name (string) (optional) (default: 'gmap_{count}')

For input type maps, a name used as a base for the hidden input field names; for output type maps, this is used as based for the ID of the map container (it will be $name_map_container).

$values (mixed) (optional) (default: 'stored_data')

Pass the default or current values as an array. The array keys, representing the values stored by the map, are:

centre_latlng (the latitude and longitude values for the map’s centre, comma-separated)
zoom (the zoom level)
marker_latlng (the latitude and longitude values for the location marker).
If this is set to stored_data, the function will attempt to get values from the current post / user metadata.

$width (integer) (optional) (default: 500)

Map width in pixels.

$height (integer) (optional) (default: 300)

Map height in pixels.

$location_markers (integer) (optional) (default: null)

How many location markers to output. Defaults to the number of markers in the stored data.

$map_type_id (string) (optional) ( 'hybrid' | 'roadmap' | 'satellite' | 'terrain' ) (default: 'roadmap')

Sets the initial map view type.

$echo (boolean) (optional) (default: true)

Whether to echo or return the generated output.

$js_callback (string) (optional) (default: '')

If given, this will be the name of a JavaScript function to be called once the map has been written to the page. The callback will be passed a reference to the Google Map object.

$required (boolean) (optional) (default: true)

For maps in a form (type = ‘input’), if this is set to false, a checkbox will be included, unchecked by default, controlling whether or not to use the map.

$object_type (string) (optional) ( 'post' | 'user' | 'custom' ) (default: 'post')

If you’re not outputting a map related to a post object, make sure you set this. The ‘custom’ setting should be used if the map isn’t object-related, e.g. it’s a map created as part of theme options.

For input maps, when the form is submitted, $_POST[$name] will be an array containing the values set by the manipulation of the map, with keys corresponding to the values detailed above.

File selection

`<?php slt_cf_file_select_button( $name, $value, $label = 'Select file', $preview_size = 'thumbnail', $removable = true ); ?>`

This function inserts a file select field, which includes a button to open the Media Library overlay, an optional ‘Remove’ checkbox, a hidden field containing the file’s ID, and a preview where appropriate. It’s used internally, but is also designed to be leveraged by theme code or by other plugins. If you use it outside this plugin, remember to call slt_cf_file_select_button_enqueue() in your admin_enqueue_scripts function.

$name (string) (required): The name for the field containing the file’s ID.
$value (string) (required): The current value of the field.
$label (string) (optional) (default: 'Select file'): A label for the button.
$preview_size (string) (optional) (default: 'thumbnail'): The size for the preview of images.
$removable (boolean) (optional) (default: true): Should there be a checkbox allowing users to remove the selected file from the field?

Shortcodes

`[slt-cf-gmap]`

This shortcode, when used in a post’s content, will display the map (if available) for that post. You can use the following optional attributes:

name (string) (default: value set for the first map field): The name of the map field to use. By default, the first map field set for the post will be used.
width (integer) (default: value set for the map field): Width in pixels.
height (integer) (default: value set for the map field): Height in pixels.

The map container generated will have the ID {$name}_map_container.

Option query placeholders

Sometimes you want to pass data to queries that is only available at runtime. For instance, you might want a field to be populated with posts, via the options_query parameter, that are selected according to another custom field which contains post IDs.

The following placeholders can be used in option queries:

[OBJECT_ID]: Replaced with the ID of the object currently being edited (note that by default the current object is automatically excluded from options queries via the exclude_current flag; see above)
[PARENT_ID]: Replaced with the ID of the parent of the object currently being edited (only applicable for hierarchical post types, e.g. pages)
[TERM_IDS]: Replaced with the IDs of terms from the specified taxonomy that are associated with the current object (not applicable to users). It’s assumed that this will be used as the value for the terms parameter within the tax_query parameter; the taxonomy will be read from that array.

So, say you have issue and article as custom post types for an online magazine. Each article is associated with an issue, and you want to define a field to set to set the “featured article” when editing an issue. You’d use something like this:

slt_cf_register_box( array(
	'type' => 'post',
	'title' => 'Featured article',
	'id' => 'featured-box',
	'context' => 'normal',
	'fields' => array(
		array(
			'name' => 'featured',
			'label' => 'Featured article',
			'hide_label' => true,
			'type' => 'select',
			'options_type' => 'posts',
			'options_query' => array(
				'posts_per_page' => -1,
				'post_type' => 'article',
				'meta_key' => slt_cf_field_key('article-issue'),
				'meta_value' => '[OBJECT_ID]'
			),
			'scope' => array( 'issue' ),
			'capabilities' => array( 'edit_pages' )
		)
	)
));

This field would be populated by all articles where the article-issue field (indicating which issue the article is assigned to) is set to the ID of the issue currently being edited.

The placeholders can be used in query parameter values that are arrays as well as simple values.

Hooks

The plugin provides various hooks to let developers extend its functionality without hacking the plugin code.

`slt_cf_init` (action)

A generic hook, mostly for dependent plugins to hook to – see: http://core.trac.wordpress.org/ticket/11308#comment:7

`slt_cf_pre_save` (action)

Run just before the custom field is saved.

`slt_cf_init_boxes` (filter)

This is applied to the registered boxes array after it’s been initialized. Should return the (possibly modified) boxes array.

`slt_cf_check_scope` (filter)

Run when none of the built-in scope checks matches. Should return a boolean value which determines whether the scope check has passed or not. These arguments are passed to help decide on the scope check outcome:

$scope_match (boolean): The current value of the scope match test (usually false).
$request_type (string): The type of the current admin request, e.g. ‘post’ for any type of post editing or ‘user’ for editing a user profile.
$scope (string): The scope of the current request, e.g. the post type or user’s role.
$object_id (integer): The ID of the post or user being edited.
$scope_key (mixed): The key of the scope being checked.
$scope_value (mixed): The value of the scope being checked.
$field (array): The settings for the field being checked.

Example:

add_action( 'slt_cf_check_scope', 'my_scope_check', 10, 7 );
function my_scope_check( $scope_match, $request_type, $scope, $object_id, $scope_key, $scope_value, $field ) {
    // This example will make sure fields with a 'global' scope apply everywhere the containing box appears
    if ( $scope_key == 'global' )
        $scope_match = true;
    return $scope_match;
}

`slt_cf_populate_options` (filter)

Run when none of the built-in option types match. Should return an array of options for select, checkboxes, radios, etc., in the same format as described for the options passed when options_type is ‘static’. These arguments are passed to help decide on how to populate the options:

$options (array): The current array of options (usually empty).
$request_type (string): The type of the current admin request, e.g. ‘post’ for any type of post editing or ‘user’ for editing a user profile.
$scope (string): The scope of the current request, e.g. the post type or user’s role.
$object_id (integer): The ID of the post or user being edited.
$field (array): The array of settings for the field being checked.

`slt_cf_default_value` (filter)

Filters the default value for fields. This allows more flexibility. As slt_cf_register_box is usually hooked to init, often useful information—like get_post_type() isn’t available at that point. Using this filter, defaults can be set at ‘runtime’.

$default (mixed): The pre-defined default value.
$request_type (string): The type of the current admin request, e.g. ‘post’ for any type of post editing or ‘user’ for editing a user profile.
$object_id (integer): The ID of the post or user being edited.
$object (object): The entire object being edited.
$field (array): The array of settings for the field being saved.

`slt_cf_pre_save_value` (filter)

Run just before the custom field value is saved. Should return the possibly modified value. These arguments are passed:

$value (mixed): The field value.
$request_type (string): The type of the current admin request, e.g. ‘post’ for any type of post editing or ‘user’ for editing a user profile.
$object_id (integer): The ID of the post or user being edited.
$object (object): The entire object being edited.
$field (array): The array of settings for the field being saved.

Example:

add_action( 'slt_cf_pre_save_value', 'my_value_filter', 10, 5 );
function my_value_filter( $value, $request_type, $object_id, $object, $field ) {
    // This example will make sure the 'important-notice' field has 'IMPORTANT!' prepended
    if ( $field['name'] == 'important-notice' && $value && substr( $value, 0, 10 ) != 'IMPORTANT!' )
        $value = 'IMPORTANT! ' . $value;
    return $value;
}

`slt_cf_field_value` (filter)

Run at the start of the slt_cf_field_value() function. Allows this function’s action to be intercepted. Return something non-null to have that returned instead of the function proceeding; return null to let it proceed. These arguments are passed:

$check (null): Passed in as default return value.
$key (string): The key of the field to be checked.
$type (string): The type of field, i.e. ‘post’, ‘attachment’ or ‘user’.
$id (integer): The ID of the post or user whose field is being checked.
$before (string): Text to go before the value.
$after (string): Text to go after the value.
$echo (boolean): Whether to echo or not.
$single (boolean): If the field is being stored as a single meta field or multiple.

`slt_cf_field_exists` (filter)

Run at the start of the slt_cf_field_exists() function. Allows this function’s decision to be intercepted. Return something true or false to have that returned instead of the function proceeding; return null to let it proceed. These arguments are passed:

$check (null): Passed in as default return value.
$key (string): The key of the field to be checked.
$type (string): The type of field, i.e. ‘post’, ‘attachment’ or ‘user’.
$id (integer): The ID of the post or user whose field is being checked.

`slt_cf_attachments_list_query` (filter)

Filters the default query arguments array passed to get_children to get results for attachments_list field types.

$args (array): The default arguments.
$post_id (integer): The ID of the post being edited.
$post (object): The entire post being edited.
$field (array): The array of settings for the field being saved.

`slt_cf_checkboxes_thumbnail_size` (filter)

Should return a registered image size for the thumbnail image output with multiple checkbox options when the checkboxes_thumbnail option is set.

$size (string): The default size.
$field (array): The array of settings for the field being saved.

To do + ideas

Make the field scope optional, default to “all”, i.e. an array populated with all post types, user roles, etc.
More targetted script / CSS inclusion
GMap output for users? Default object ID for users is current user – doesn’t work for user profile front-end output
Proper errors for missing ‘type’ parameter for boxes
A reciprocal flag for fields. That is, if a field on post edit screens allows the selection of users, and the reciprocal flag is set, user profiles would automatically allow selection of the posts they’re attached to.
Add support for multiple values for the same field (underway but stalled – called ‘cloning’)
Extend use of required field setting to enforce validation of field entries
The capabilities system could be improved. Currently, if a field applies to a post type and a user role, you have to supply capabilities to edit that post type and to edit users for the capabilities check; if the user has either, they’ll be able to use that field. Should capabilities be more closely related to corresponding items in the scope array?
Add more hooks?
More control over TinyMCE, removing irrelevant buttons, etc.
File uploads for user profiles – how to ‘attach’ media library items to users?
Add validation mechanisms
slt_cf_field_value to handle echoing non-string values?
Parameters to apply content filters / parse shortcodes from slt_cf_field_value?

Developer’s Custom Fields documentation

Configuration

Constants

Settings

Functions

Settings

<?php slt_cf_setting( $key, $value ); ?>

Registering boxes and fields

<?php slt_cf_register_box( $box ); ?>

Retrieving values

<?php slt_cf_field_value( $key [, $type, $id, $before, $after, $echo, $single ] ); ?>

<?php slt_cf_all_field_values( [ $type, $id, $multiple_fields ] ); ?>

<?php slt_cf_field_key( $key[, $object_type ] ); ?>

<?php slt_cf_field_values_order( $key [, $type, $id ] ); ?>

<?php slt_cf_reverse_date( $date_string[, $sep, $to_timestamp ] ); ?>

Other useful functions

<?php slt_cf_get_posts_by_custom_first( $key [, $query, $custom_order, $numeric, $object_type] ); ?>

Google maps

<?php slt_cf_gmap( $type = 'output', $name = 'gmap', $values = 'stored_data', $width = 500, $height = 300, $location_markers = null, $map_type_id = 'roadmap', $echo = true, $js_callback = '', $required = true, $object_type = 'post' ); ?>

File selection

<?php slt_cf_file_select_button( $name, $value, $label = 'Select file', $preview_size = 'thumbnail', $removable = true ); ?>

Shortcodes

[slt-cf-gmap]

Option query placeholders

Hooks

slt_cf_init (action)

slt_cf_pre_save (action)

slt_cf_init_boxes (filter)

slt_cf_check_scope (filter)

slt_cf_populate_options (filter)

slt_cf_default_value (filter)

slt_cf_pre_save_value (filter)

slt_cf_field_value (filter)

slt_cf_field_exists (filter)

slt_cf_attachments_list_query (filter)

slt_cf_checkboxes_thumbnail_size (filter)

To do + ideas

`<?php slt_cf_setting( $key, $value ); ?>`

`<?php slt_cf_register_box( $box ); ?>`

`<?php slt_cf_field_value( $key [, $type, $id, $before, $after, $echo, $single ] ); ?>`

`<?php slt_cf_all_field_values( [ $type, $id, $multiple_fields ] ); ?>`

`<?php slt_cf_field_key( $key[, $object_type ] ); ?>`

`<?php slt_cf_field_values_order( $key [, $type, $id ] ); ?>`

`<?php slt_cf_reverse_date( $date_string[, $sep, $to_timestamp ] ); ?>`

`<?php slt_cf_get_posts_by_custom_first( $key [, $query, $custom_order, $numeric, $object_type] ); ?>`

`<?php slt_cf_gmap( $type = 'output', $name = 'gmap', $values = 'stored_data', $width = 500, $height = 300, $location_markers = null, $map_type_id = 'roadmap', $echo = true, $js_callback = '', $required = true, $object_type = 'post' ); ?>`

`<?php slt_cf_file_select_button( $name, $value, $label = 'Select file', $preview_size = 'thumbnail', $removable = true ); ?>`

`[slt-cf-gmap]`

`slt_cf_init` (action)

`slt_cf_pre_save` (action)

`slt_cf_init_boxes` (filter)

`slt_cf_check_scope` (filter)

`slt_cf_populate_options` (filter)

`slt_cf_default_value` (filter)

`slt_cf_pre_save_value` (filter)

`slt_cf_field_value` (filter)

`slt_cf_field_exists` (filter)

`slt_cf_attachments_list_query` (filter)

`slt_cf_checkboxes_thumbnail_size` (filter)