Adding custom settings to fields

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.

acf-global-field-setting

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.

acf-global-field-type-setting

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 earlu 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 whitespaces
	$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.

acf-field-type-setting-input

Conclusion

Adding extra field settings in ACF is easy and the possibilities are endless!

Save

Save

Related