====== AutoGroup Plugin ======

---- plugin ----
description: Provides a way to automatically group users based on account values
author     : Michael Wilmes
email      : michael.wilmes@gmail.com 
type       : Action
lastupdate : 2018-08-06
compatible : Greebo
depends    : 
conflicts  : 
similar    : virtualgroup
tags       : groups

downloadurl: https://github.com/wilminator/dokuwiki-plugin-autogroup/zipball/master
bugtracker : https://github.com/wilminator/dokuwiki-plugin-autogroup/issues
sourcerepo : https://github.com/wilminator/dokuwiki-plugin-autogroup
donationurl: 

screenshot_img : 
----

===== Installation =====

Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

===== Configuration =====

After installing, the automatic grouping can be configured exclusively in the Configuration page in the Admin Menu.

There are three settings:
  - The first turns on the addition of users to groups when they amtch the grouping rules.
  - The second turns on  the removal of users when they do not match the rules.
  - The last is a list if group matching rules, with one rule per line.

This plugin uses the wiki's assigned authentication module.  It is shown to work on the default auththenication module, and should support any module where the users can be listed AND the groups modified.

===== Rule Syntax =====

<code><group name>,<account value>,<PCRE regular expression></code>
  * The group name is the name of the group you would like to alter the membership of.
  * The account value is either ''login'' for the username, ''name'' for the wiki visible name, or ''mail'' for the email address.
  * The PCRE is a Perl Regular Expression that is supplied to the PHP [[http://php.net/manual/en/function.preg-match.php|preg_match]] function to test the account value associated with the user. Common formats are ''/expression/'' for case sensitive matches and ''/expression/i'' for case insensitive matches. Please refer to [[http://php.net/manual/en/book.pcre.php|PHP PCRE documentation]] for further information. 
There can be more than one rule per group. In that case, a user is included in the group if any rule matches and removed if all rules fail.

===== Examples/Usage =====

Find any username containing ''mike'' and add them to the ''mikes'' group:
<code>mikes,login,/mike/</code>
The above rule with a case insensitive search:
<code>mikes,login,/mike/i</code>
Add all users with a Gmail email address to the ''Gmail'' group:
<code>Gmail,mail,/@gmail.com$/i</code>
Add the user to the ''Dirty'' group if their username contains ''dishes'' (case insensitive), their given name contains the word ''Harry'' (case sensitive), or their email ends in ''@dirty.com'' (case insensitive):
<code>Dirty,login,/dishes/i
Dirty,name,/\bHarry\b/
Dirty,mail,/@dirty.com$/i</code>

===== Testing Rules =====

The recommended method to test is to use an online PCRE testing tool and test your scenarios out there. One such site is [[https://regex101.com/|Regular Expressions 101]].

This plugin also supports the Dokuwiki debug framework.  If you enable the allow debug setting in the wiki's configuration, then this module will display the groups a user is assigned to or removed from.  Please note that the debug option is not meant to be left on, so disable it when you are done testing.

=== Change Log ===

{{rss>https://github.com/wilminator/dokuwiki-plugin-autogroup/commits/master.atom date}}

=== Known Bugs and Issues ===

  * This plugin does not allow for rules to remove users on match, only to add on match and remove with no match.  For now, rewite the rules to not match the users that should be removed.

=== ToDo/Wish List ===

There are no plans at this time for any new features.  If you have a feature request, then please file it as an issue at GitHub by clicking on the "Submit Bug" button at the top of this page.