Create User Groups in a Plugin

As I said in my previous blog article, Plugins can be a great way to automate repetitive tasks in MODX. In this article, we’ll look at an example that puts users into a user group based on their zip code (or whatever is in the zip field of the user profile), creating the user group if necessary.

General Approach

In our Plugin, which will only execute for new users, we’ll first get the content of the zip field of the user profile. If it’s not empty, we’ll check to see if there is a user group by that name (after adding the “Group.” prefix). If not we’ll create it. Finally, we’ll add the user to the group.

The Code

/* UserGroupFromZip plugin --
   attached to OnUserFormSave event */

/* Do nothing if it's not a new user */
if ($mode !== modSystemEvent::MODE_NEW) {
    return;
}

/* Get the User Profile */
$profile = $user->getOne('Profile');

/* Make sure the user has a profile */
if ($profile) {

    /* get the content of the 'zip' field, if any */
    $zip = $profile->get('zip');

    if (! empty($zip)) {
        /* add our prefix */
        $groupName = 'Group' . $zip;

        /* See if the group already exists */
        $userGroup = $modx->getObject('modUserGroup',
            array('name' => $groupName));

        /* Create the group if necessary */
        if (! $userGroup) {
            $userGroup = $modx->newObject('modUserGroup');
            $userGroup->set('name', $groupName);
            $userGroup->save();
        }
        $user->joinGroup($groupName);
    }
}
return;

Setting $groupName as a variable is not strictly necessary, but it’s a good programming practice, since we use the name in several places. Without the variable, one of those instances could contain a mistake that would make the Plugin fail. It might take some time to find the problem. In addition, if you decide you want to change the form of the group name, with the variable, you only have to change it in one place.

Many MODX methods will let you identify the object you want either by name or by id. The joinGroup() method, for example, will let you send the name of the user group or its ID. To prevent confusion, it’s a good general principle not to use names that start with a number. It makes it absolutely clear what we’re sending. That’s why our example prefixes the zip-code group names with “Group”. Many MODX Extras use the PHP function is_numeric() to figure out if they’re getting a name or an ID and any name composed entirely of numbers will be interpreted as an ID.

Creating the Plugin

Right-click on the “Plugins” folder in the Elements tree and select “New Plugin”
Name the Plugin UserGroupFromZip
Paste in the code above
On the “System Events” tab, put a checkmark next to OnUserFormSave
Save the Plugin

Once the Plugin has been saved, all new users will be placed in a user group based on the content of the zip field.

Customization

The Plugin described above could be modified to perform a variety of user-group tasks. You could, for example, create a new user group based on the user’s name, so each user would be in his or her own user group. You could group users by city, telephone prefix, gender, date-of-birth, or anything else that’s available in the user profile. Note that for some fields, you may have to add a little code to create the group name. For the telephone prefix, you’d have to make sure the number has a prefix and extract it. For the gender field, the value is a 1 or a 0, so you’d probably want to translate that.

For our Plugin above, you’ll want to add some code that validates and normalizes the zip code value. We’ll look at how to do that in the next article.

Other Uses

If you connect the Plugin to another event and modify it, you could do lots of other things with it. In a future article, for example, we’ll look at how to set the value of Resource fields and Template variables in a similar Plugin attached to the OnDocFormSave event.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.