Custom location rules

Last updated Oct 30, 2023

Overview

Each field group contains a set of location rules. These rules are used to decide where to show the field group throughout the WP admin. It is possible to create your own location rules, or even modify existing rules using the following filters.

Change Log

  • 5.8.0 – Added $field_group parameter to 'acf/location/match_rule' filter.
  • 5.3.5 – Added 'acf/location/screen' filter.

Adding a new rule

Adding a custom location rule consists of 4 simple steps. 3 of these are to define the rule settings and the last is to use these settings to match the rule to the edit screen.

1. Adding a custom rule type

When editing a field group, the ‘types’ drop down is the first dropdown in the location rule row.

Note that the list is broken into groups. This is important to keep in mind when editing the choices for this dropdown. Use the ‘acf/location/rule_types’ filter to customize this list. Here is an example of adding “user” to the ‘Basic’ group in the dropdown choices:

add_filter('acf/location/rule_types', 'acf_location_rules_types');

function acf_location_rules_types( $choices ) {
    
    $choices['Basic']['user'] = 'User';

    return $choices;
    
}
  • Tip: use a print_r or var_dump to get a better idea of the $choices array.

2. Add custom rule operators

This step is optional and not required for your custom location rule to work. When editing a field group, the ‘operators’ drop down is the second dropdown in the location rule row.

By default, this list has ‘==’ and ‘!=’ operators. This can also be customized with the ‘acf/location/rule_operators’ filter. To add in ‘<‘ and ‘>’ operators, you could use something like this:

add_filter('acf/location/rule_operators', 'acf_location_rules_operators');

function acf_location_rules_operators( $choices ) {
    
    $choices['<'] = 'is less than';
    $choices['>'] = 'is greater than';

    return $choices;
    
}

3. Add custom rule values

When editing a field group, the ‘values’ drop down is the third dropdown in the location rule row. This list is dynamically updated based on the ‘type’.

This list must have a choice to select from. To populate this list, use the ‘acf/location/rule_values/$type’ filter. Please note that the variable $type in the filter name should match the ‘type’ value.

This code will populate the list with all the available users. The list will save the user_id but display the user display_name:

add_filter('acf/location/rule_values/user', 'acf_location_rule_values_user');

function acf_location_rule_values_user( $choices ) {
    
    $users = get_users();

    if( $users ) {
        
        foreach( $users as $user ) {
            
            $choices[ $user->data->ID ] = $user->data->display_name;
            
        }
        
    }

    return $choices;
}

4. Matching the rule

After following the above steps, you should now have a custom location rule applied to your field group. The last step is to create a function for matching this rule to an edit screen.

When viewing an edit screen (page / post / user / taxonomy / attachment / etc), ACF will find all available field groups and run matching functions on the field group’s location rules. These matching functions will return either true or false and determine if a field group gets shown or not.

To create a location rule_match function for your custom location rule, use the ‘acf/location/rule_match/$type’ filter. Please note that the variable $type in the filter name should match the ‘type’ value.

This filter accepts 3 parameters:

  1. $match – the true / false variable which must be returned
  2. $rule – the current rule that you are matching against. This is an array with keys for ‘param’, ‘operator’, ‘value’.
  3. $options – an array of data about the current edit screen (post_id, page_template, post_type, etc). This array will also include any data posted in an ajax call (ajax calls are made on a post / page when you change the category, page_template, etc)

The following code will create a rule_match for ‘user’ where if the current_user is equal to the user selected (in the field group’s rule) the field group will be shown (unless another rule did not match)

add_filter('acf/location/rule_match/user', 'acf_location_rule_match_user', 10, 4);
function acf_location_rule_match_user( $match, $rule, $options, $field_group )
{
    $current_user = wp_get_current_user();
    $selected_user = (int) $rule['value'];

    if($rule['operator'] == "==")
    {
        $match = ( $current_user->ID == $selected_user );
    }
    elseif($rule['operator'] == "!=")
    {
        $match = ( $current_user->ID != $selected_user );
    }

    return $match;
}

Modifying the rule_match options

The above rule_match filter contains a parameter called $options. This parameter contains an array of information about the current edit screen such as post_id, post_parent, etc.

It is possible to modify this array by hooking into the filter acf/location/screen and either edit or append screen data.

add_filter('acf/location/screen', 'acf_location_screen_options', 10, 1);

function acf_location_screen_options( $options ) {
    $options['foo'] = 'bar';
    return $options;
}

Wrapping up

The above filters give you the ability to create custom location rules for you custom field groups. Honestly, the possibilities are endless in terms of what you can compare.

These filters could also be used in a plugin. Such as creating location rules for the post_template plugin!