gwp_user_role
The gwp_user_role modifier for Gravity Forms merge tags allows you to retrieve and display user roles based on the user’s login, email, or ID, and offers customization options such as specifying a subset of roles, changing the separator character, and limiting the number of roles returned.
Usage
The basic syntax for the `gwp_user_role` modifier looks like this:
{field:1:gwp_user_role match=login subset="subscriber,editor" separator=- return=1 unknown="not found"}Attributes
- match: Specifies the method to match the user. Options include `login` , `email` , or `id` . Default is `login` .
- subset: Defines a comma-separated list of user roles to filter the output. Only roles listed will be returned.
- separator: Determines the character(s) used to separate multiple roles in the output. Default is `,` .
- return: Controls the number of roles to return. `all` returns all matching roles, while a numeric value specifies the maximum number of roles to return.
- unknown: Defines the output when no matching user was found. By default it will return an error message or nothing (depending on the global settings of the plugin).
Functionality
- User Role Retrieval: The modifier retrieves the roles of a user based on the specified `match` attribute (login, email, or ID).
- Role Filtering: If a `subset` is defined, only roles within this subset are considered. This allows for precise control over which roles are output.
- Output Formatting: The `separator` attribute allows for customization of the output format, especially useful when multiple roles are returned.
- Return Control: The `return` attribute limits the number of roles displayed, providing flexibility in how much information is shown.
- Handling Unknown Users: The `unknown` attribute offers a way to customize the response when no matching user is found.
Examples
To display the role of a user based on their email, filtering to only show “subscriber” or “editor” roles, using a hyphen as a separator, and limiting the output to the first matching role:
{field:1:gwp_user_role match=email subset=subscriber,editor separator=- return=1}
Example 1: Basic Usage
To display the first role of the user based on their email, where the user’s email is the value of field 1:
{field:1:gwp_user_role match=email}This example doesn’t specify any attributes like subset , separator , return , or unknown , so it will use the function’s defaults. It will return all roles associated with the user in a comma-separated list.
Example 2: Subset and Separator
To display roles from a specific subset and use a custom separator:
{field:1:gwp_user_role match=login subset="subscriber,editor" separator="-"}In this case, if the user has roles subscriber and editor , and the value of field 1 matches their login, this merge tag might output something like “subscriber-editor”. If they have additional roles not listed in the subset, those are ignored.
Example 3: Limited Return
To only return a specific number of roles:
{field:1:gwp_user_role match=login return=1}This will return the first role found for the user whose login is the value in field 1. If they have multiple roles, only the first one encountered is displayed.
Example 4: Handling Unknown Users
To provide a custom message for unknown users:
{field:1:gwp_user_role match=login unknown="not found"}If there’s no user matching the login provided in field 1, this merge tag will output “not found”.
Example 5: Complex Usage
Combining multiple attributes for a detailed query:
{field:1:gwp_user_role match=login subset="subscriber,editor" separator="-" return=1 unknown="not found"}
This merge tag is set to look for users based on the login provided in field 1, but it only considers the roles subscriber and editor . It will return the first role it finds from this subset, separate any additional roles with a hyphen (though only one role is returned in this case due to return=1 ), and outputs “not found” if the user doesn’t exist or doesn’t have the specified roles.
