The group system is a way for administrators to sort and email contacts.

Types of Groups

• System Groups - not actual group objects, they are determined by using Eloquent queries retrieving records from the database.

  • All Contacts - All contacts in the system, including admins, applicants from all years(with duplicates if someone has applied for more than one year), sponsors and custom contacts.
  • Admins - all registered users on the site. These will only be admins.
  • Sponsors - all sponsors entered into the system.
  • Other contacts - user created contacts
  • Subscribers - all people who have signed up for updates. Subscribers do not appear on the 'All Contacts' list.

• Custom Groups - These groups can be defined by admins. They can be given a name, avatar and have members manually added or removed.

Creating Groups

Administrators can create groups on the Group Management page. When editing or creating a custom group the administrator can set a group icon. If they do not do this, the icon will be the default system icon. There is a custom_icon boolean that is set during this process. In the blade a turnery operator determines if the group icon or default icon is displayed. At this time, icons are meaningless, but they allow groups to be more easily recognised by administrators.

Refreshing Group Icons in Storage

Custom artisan commands have been configured to make this task easier. See here for more information.

---

Group Membership is programmatically handled by the Groupable trait. For more information see the documentation below.

---

Groupables

The trait 'Groupable' is added to all classes that are to be added to groups. Currently, this includes:

• Users
• Applicants
• Sponsors
• Subscribers
• Contacts (i.e. people who do not fit into any other category)

Please note: The contenders class has been excluded deliberately. Contenders can be identified as applicants whose isContender() function returns true.

Groupable Trait Features

The groupable trait brings the following features to any $groupable object:

• $groupable->addToGroup($groupId) - returns void
• $groupable->removeFromGroup($groupId) - returns void
• $groupable->groups - returns Eloquent collection of group objects

Please note that on '->groups' you should not have any parentheses (), as this is accessed as a property rather than a method. The use of parentheses may have unintended results

Adding to a group

To add a groupable object to a group, retrieve the object, then call the addToGroup() function and pass it the id of the group.

If the groupable is already a member of this group, it will not be added again.

Removing from a group.

To remove a groupable object from a group, retrieve the object, then call the removeFromGroup() function and pass it the id of the group. If the groupable being removed is a 'Contact' type, the application will delete this Contact from the database if it is no longer a member of any groups.

Viewing a Groupables memberships

To see which groups a groupable belongs to, use $groupable->groups.

Example usage:

foreach($groupable->groups as $group){
 echo('Group ID: '.$group->id.' Group Name: '.$group->name);
}

Groups

Retrieving all members of a group

To retrieve all members of a group, call the recipients() function. This function returns an array of associative arrays. Each associative array has four keys:

• 'name'
• 'email'
• 'role'
• 'phone'

Example usage:

foreach($group->recipients() as $recipient){
   $name = $recipient['name'];
   $email = $recipient['email'];
   $role = $recipient['role'];
   $phone = $recipient['phone'];
}

The 'role' value is hardcoded (admin, subscriber, sponsor, applicant) for all groupables except contacts. The contacts 'role' defaults to 'Custom Contact'.

Note: The 'phone' field will be set to null for admins and subscribers.

New feature added 9/9/18

The recipients() method now takes an optional parameter, $removeDuplicates. This defaults to true, in which case duplicate email addresses will automatically be filtered from the returned array. If the calling code sets $removeDuplicates to false, duplicates will not be filtered.

For further assistance, contact Sam J