Overview
Each field contains a number of settings. These are made up of both global (field label, field name, etc) and type specific (image field preview size, etc). These settings specify how a field will appear and function throughout the admin & theme. It is possible to create your own field settings!
Change Log
acf_render_field_setting()function added in version 5.0.0
Global settings
Global field settings appear for all fields. The following example shows how to add a new setting called ‘Admin Only’ which will add a ‘Yes/No’ setting to all fields allowing them to be hidden from non admin users.
1. Adding the setting
A global setting can be added using the action acf/render_field_settings and the function acf_render_field_setting(). The following snippet will add a global setting. Please note that the third parameter for acf_render_field_setting() is set as true to acknowledge this is a global setting.
functions.php
add_action('acf/render_field_settings', 'my_admin_only_render_field_settings');
function my_admin_only_render_field_settings( $field ) {
acf_render_field_setting( $field, array(
'label' => __('Admin Only?'),
'instructions' => '',
'name' => 'admin_only',
'type' => 'true_false',
'ui' => 1,
), true);
}2. Using the setting
With the new ‘admin_only’ setting added and a new field added (using the setting), we can hook into any part of ACF and use the setting. The following code will hook into the acf/prepare_field filter which is run just before a field is rendered into a form. This will allow us to check if the current user is an administrator, and if not, prevent the field from being displayed.
functions.php
add_filter('acf/prepare_field', 'my_admin_only_prepare_field');
function my_admin_only_prepare_field( $field ) {
// bail early if no 'admin_only' setting
if( empty($field['admin_only']) ) return $field;
// return false if is not admin (removes field)
if( !current_user_can('administrator') ) return false;
// return
return $field;
}3. Testing the setting
With the above code added to the functions.php file and a field using the ‘admin_only’ setting, we can now login with either an administrator or editor account and note the field’s existence!
Type specific fields
Field settings can also be added to specific types (text, image, etc). The following example shows how to add a new setting called ‘exclude words’ to all textarea fields which will add an extra text input allowing specific words to be checked during validation.
1. Adding the setting
A field type specific setting can be added using the action acf/render_field_settings/type={$type} and the function acf_render_field_setting(). The following snippet will add a setting. Please note that the third parameter for acf_render_field_setting() is excluded making it specific to $field.
functions.php
add_action('acf/render_field_settings/type=textarea', 'my_textarea_render_field_settings');
function my_textarea_render_field_settings( $field ) {
acf_render_field_setting( $field, array(
'label' => __('Exclude words'),
'instructions' => __('Enter words separated by a comma'),
'name' => 'exclude_words',
'type' => 'text',
));
}2. Using the setting
With the new ‘exclude_words’ setting added and a new textarea field added (using the setting), we can hook into any part of ACF and use the setting. The following code will hook into the acf/validate_value filter which is run during validation. This will allow us to check if the current value contains any words from the ‘exclude list’ and notify the user via a validation error message.
functions.php
add_filter('acf/validate_value/type=textarea', 'my_textarea_validate_value', 10, 4);
function my_textarea_validate_value( $valid, $value, $field, $input ){
// bail early if value is already invalid
if( !$valid ) return $valid;
// bail early if no 'exclude_words' setting
if( empty($field['exclude_words']) ) return $valid;
// explode words
$words = explode(',', $field['exclude_words']);
$words = array_map('trim', $words); // trim white spaces
$words = array_values($words); // remove empty values
// loop
foreach( $words as $word ) {
// check if word exists
if( stripos($value, $word) !== false ) {
$valid = sprintf(__('Value must not include "%s"'), $word);
break;
}
}
// return
return $valid;
}3. Testing the setting
With the above code added to the functions.php file and a field using the ‘exclude_words’ setting, we can now edit a post and attempt to save a value.
Conclusion
Adding extra field settings in ACF is easy and the possibilities are endless!