Bob's Guides

DefaultUserGroup Plugin Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

This plugin automatically assigns new Users to one or more specified User Groups with the option to assign roles in the group.

Overview

The DefaultUserGroup plugin places all new users into a default User Group or groups. It will not change the User Group settings of existing users when you edit them. If you select certain User Groups when creating the new user, those selections will be honored, but the plugin will also add the user to the specified default User Groups.

The plugin will work on new users created in Manage -> Users, but it will not work if you create a new user in PHP code. There, you will have to use $user->joinGroup('group name');

Installing DefaultUserGroup for MODX Revolution

Go to Extras -> Installer on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository. Put DefaultUserGroup in the search box and press Enter. Click on the "Download" button. When the download finishes, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to DefaultUserGroup in the grid. The DefaultUserGroup snippet should now be installed. The plugin is enabled by default.

Properties

There are only two properties for the plugin. The dug_groups property should contain either the name of a specific User Group to put new users in, or a comma-separated list of User Group names (use no spaces). The dug_roles property is optional and can contain the name of a single Role, or a comma-separated list with the names of several Roles.

• If dug_roles is empty, all users will get the Role of Member
• If dug_roles specifies one Role, users will get that Role in all groups
• If dug_roles specifies more than one Role, the Roles will be matched to the list of user groups in dug_groups

Important: If you specify multiple Roles, make sure the number of Roles is equal to the number of groups!

Rather than changing the default properties of the plugin to set the dug_groups and dug_roles properties, you should always create a Property Set.

Important: Be sure to clear the site cache after setting or changing the properties.

Creating a Property Set for the Plugin

If a plugin has default properties, you can set those properties on the Properties tag when editing the plugin. This is a bad practice, however, because the values you set may be overwritten when the plugin is upgraded. Instead, you should create your own Property Set for the plugin and then attach it to the plugin.

— Creating the Property Set

1. Right-click on the plugin in the Element tree and select "Edit Plugin"
2. On the right panel, click on the "Properties" tab
3. Click on the "Add Property Set" button
4. Check the "Create New Property Set" checkbox
5. Give the Property set a unique name (e.g., MyPluginNameProperties)
6. Click on the "Save" button
7. You should see the Property Set name above the grid
8. (If you see 'Default' instead of your property set name, click on it and select your Property Set from the drop-down list)
9. Note that your Property Set has not been saved
10. Set property values by double-clicking in the "Value" column or right-clicking on the property and selecting "Update Property"
11. When finished setting values, click on the "Save Property Set" button at the upper right

As you edit plugin values, you will see the default properties in the grid, but they are not really "in" your Property Set. They're just there for your information. The only properties truly in your Property Set are the ones you've changed. After you save the Property Set, the properties you've changed will be in a different color (usually green). If you add new properties to your Property Set that are not in the default properties (using the "Create Property" button), they will be in yet another color (usually purple).

Important! Whenever you go back to edit the Property Set in the future, select it from the drop-down list at top of the grid (where it says 'default'). Don't forget to save your changes by clicking on the "Save Property Set" button.

— Attaching the Property Set to the Plugin

The values in your Property Set will have no effect until you attach them to your plugin. To attach them, follow these steps:

1. While still editing the plugin, click on the "System Events" tab
2. Scroll down to see which System Events the plugin is connected to
3. In the row of the System Event, you should see two numbers on the right
4. The left number (in the "Property Set" column) specifies the Property Set
5. Often, you will see a 0 there, which tells the plugin to use the default properties
6. If you double-click on the number, you should see a drop-down list
7. Select your Property Set from the list
8. If the plugin listens to multiple events, be sure to set the Property Set on all of them
9. Click on the "Save" button at the upper right to save the plugin and the Property Set specification

If the plugin listens to more than one event, you can have a different Property Set for each event, but it's also fine to put all the properties in one Property Set and specify that set for all events.

Enabling the DefaultUserGroup Plugin

When installed, the plugin is disabled. Once you have set up your property set and designated the User Groups to assign new Users to, edit the plugin, and on the main tab, edit the plugin and set it as active. Save the plugin.

Copyright © 2011-2025
Bob Ray