Documentation

Custom location rules

Overview

New to v3.5.7 is the ability to add custom location rules. Location rules are used by ACF to decide whether or not to show  a field group when editing a page / post.

Adding a custom location rule consists of 4 steps:

1. Add custom types

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 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 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_rules_values_user');
function acf_location_rules_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_rules_match_user', 10, 3);
function acf_location_rules_match_user( $match, $rule, $options )
{
    $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;
}

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!