History: Templated Groups

Source of version: 50 (current)

!Templated Groups
Templated Groups is a new feature in ((Tiki21|Tiki 21)) that enables ((Organic Groups)), although strictly speaking not all Templated Groups are Organic in the sense of being created by users since they can be completely admin managed.

It is similar to what ((Workspace UI)) tried to achieve but is in core of Tiki rather than simply a tool to set things up over what Tiki already had. ((Workspace UI)) will need to be upgraded to support Templated Groups natively (TODO, not sure if in time for Tiki 21).

Templated Groups can be used in conjunction with ((Roles)) (in many cases it makes sense to do so) but it is not strictly necessary as they are independant features.

!!What are Templated Groups for?
Templated groups are groups that follow the same pattern as a template, such as one or more of the following:
*They have the same types of members
*Each type of member has the same permissions to access the group's assets
*They have a copy of the same Group Assets (wiki pages, file galleries, tracker items etc) as the template
*They have the same naming pattern as each other based on the template
For example:
*Classes (Templated Group Container)
**Science Class (Templated Group)
***Science Class Teachers (Type of Member - sub-group)
***Science Class Students (Type of Member - sub-group)
***Science Class Handout (Asset - the wiki page Science Class Handout)
***Science Class File Gallery (Asset)
**Math Class (Templated Group)
***Math Class Teachers (Type of Member - sub-group)
***Math Class Students (Type of Member - sub-group)
***Math Class Handout (Asset - the wiki page Math Class Handout)
***Science Class File Gallery (Asset)

!!Benefits of Templated Groups
!!!Easy creation
Using the above example, say you now want to add a Geography class, it is easy to create the following and set the permissions as well.
*Geography Class (Templated Group)
**Geography Class Teachers (Type of Member - sub-group)
**Geography Class Students (Type of Member - sub-group)
**Geography Class Handout (Asset - the wiki page Geography Class nHandout)
**Geography Class File Gallery (Asset)

Until ((Workspace UI)) is upgraded to be able to work with Templated Groups, for now, using ((Profiles)) and ((PluginDataChannel)) is the easiest way to do this. The example below includes this.

!!!Group Assets are robust to renaming of group.
(still work in progress as of November 2019)

For example, if you made a mistake and entered "Geography" instead of "Geology" and want to rename the "Geography Class" to "Geology Class", you can just rename the group and all the assets will be renamed. Say you have 10 different wiki pages, ~np~--groupname--Handout1~/np~ to ~np~--groupname--Handout10~/np~, since ~np~--groupname--~/np~ the system will remember that you saved it like this and handle the batch renaming as needed.

!!!Role sub-categories are automatically managed
((Roles)) provide a way to have sub-categories for each Templated Group to control permissions to access the Group Assets. For example, the following category structure is possible:
*Class Assets (where Role permissions are set)
**Science Class Assets (where you categorize the Science Assets)
**Math Class Assets (where you categorize the Math Assets)
If you want to split up different types of assets into different parent categories, you can set up the following instead: ''(this is still not working as of Nov 2019. If you try to have more than one parent category, the new parent category will "take over" the categories of the old one, which is a bug)''.
*Handouts (where Role permissions are set)
**Science Class Handouts (where you categorize the Science Class Handout wiki page)
**Math Class Handouts (where you categorize the Math Class Handout wiki page)
*Other Class Assets (where Role permissions are set)
**Science Class Other Assets (where you categorize the Science Class File Gallery)
**Math Class Other Assets (where you categorize the Math Class File Gallery)

Once you specify the parent categories "Class Assets" (or "Handouts" and "Other Class Assets") as associated to the "Classes" Templated Group container, the following occurs:
*Whenever you create a new Templated Group (e.g. Geography Class), the system will automatically create the categories "Geography Class Assets" (or "Geography Class Handouts" and "Geography Class Other Assets"), which will automatically inherit the Role Permissions automatically.
*Whenever you rename a Templated Group (e.g. Geography Class -> Geology Class), the system will automatically rename the corresponding categories to "Geology Class Assets" (or "Geology Class Handouts" and "Geology Class Other Assets").
*If you delete a Templated Group (e.g. Geography Class), the system will warn you of the consequences and (1) set the category permissions to be viewable by Admins group only to make sure the contents are now secure. (2) move the category to top level in the category tree and append " (Archive)" to the name so it's no longer part of the managed parent category.

!!!Ability to create Templated Group Menus with smart links

((Menus)) are very flexible in Tiki. A Templated Group Menu is a menu with a special option to link it to a Templated Group Container, e.g. you can set it to "Classes". Then what does is whenever the user is viewing a group asset, (in the above example) whether it is Math Handout or Science Handout, that menu will appear. (You can easily put that menu in a ((Module))). These menus will have "smart links" so that when you are viewing say the "Math Class Handout" the link to "Math Class Assignment" will point to the "Math Class Assignment" wii page, but if you are viewing the "Science Class Handout" the links are to "Science Class Assignment" instead. 

If you need to link to other things like File Galleries, then you will need a wiki page to ((PluginRedirect)) there, or embed a plugin like ((PluginList)) to show the contents of whatever is within. For example, you can create a wiki page called "Science Class File Gallery" for that purpose.

!!Example Demo
!!!1. Create a Templated Group Container
Following the example above, first let's create the "Classes" group and make sure to set it as a Templated Group Container by checking the checkbox.
{img src="display1626" link="display1626" width="400" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}

!!!2. Create the Templated Groups
Add a "Science Class" group and "Math Class" group and make sure that you include for both of them the "Classes" Templated Group container.
{img src="display1627" link="display1627" width="400" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}

Additionally, if you want your Templated Group to be an ((Organic Group)) or you want users to be able to join them on their own, make sure to select the "User Choice" checkbox as well (the tiki_p_group_join permission is needed for this in addition to doing this - under Group management permissions).
{img src="display1628" link="display1628" width="400" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}
{img src="display1667" link="display1667" width="400" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}



!!!3. Set up Groups and Roles
If your use case is really simple and you are not using ((Roles)), then it is fine to add users directly to your Templated Group, e.g. Math Class. But as Templated Groups are quite limited without ((Roles)) it would be expected that you would want to setup some ((Roles)). In that case, you would NOT want to add any users directly into the Templated Group, e.g. they are either Science Class Teachers or Science Class Students (or if both they are in both of these), which are sub-groups.

Follow the example on the page ((Roles)) to set up the groups, categories and roles for Science/Math Teachers/Students.

Additionally, edit all of these 4 groups to make sure they include the corresponding Templated Group:
{img src="display1629" link="display1629" width="400" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}

!!!4. Link Roles Category Parents to Templated Groups
Now go to Admin Categories and edit the settings for the Handouts category created in the ((Roles)) example. Turn on "Automatically manage sub-categories for Templated Groups Container" and set it to "Classes". The default name pattern should be changed to what you want the sub-category names to be, for example "~np~--groupname-- Handouts~/np~" will give you something like "Science Class Handouts". Sub-categories for existing groups will automatically be created once this is turned on. In the case where you already created "Science Class Handouts" and you specify "~np~--groupname-- Handouts"~/np~, automatic management will take over the existing category.
{img src="display1630" link="display1630" width="400" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}

!!!! Test Automatic Category and Roles setup
To test this, you can manually create a Geography Class by creating the Geography Class Teachers and Geography Class Students groups and then the Geography Class group. However, the order of group creation needs to be precise for the Roles to be mapped automatically to the sub-category being automatically created. Otherwise, you will have to manually set the Roles settings on the new sub-category.

^The correct procedure to ensure that the Roles are set automatically for the new sub-category being created is (1) First create the "Geography Class" group but do NOT include it in "Classes" yet. (2) Then create "Geography Teachers" and "Geography Students", including them in "Geography Class" as well as "Teachers"/"Students" respectively. (3) Then edit the "Geography Class" group and include it in "Classes" to trigger the sub-category creation.^

!!!! Test Automatic Category Renaming
Another test you can do is to edit the Math Class group and rename it "Maths Class". Go back to categories and you will see that the category name of "Math Class Handouts" has automatically changed to "Maths Class Handouts".

!!!! Test Group deletion
Now delete the Geography Class group. Go back to categories and you will see that the "Geography Class Handouts" have been moved out of the "Handouts" folder, renamed to "Geography Class Handouts (Archived)" and the permissions of the category has been set to be accessible only by Admins. This is for security of whatever content was in the category before.
!!!6. Set up a profiles template for automatic creation of group and assets

The first step is to setup 2 profiles as wiki pages. Make these wiki pages only visible by Admins if you wish to secure them.

It needs to be done in two sepearate profiles because of the way you need to setup the groups first and then trigger the inclusion in Classes as a separate step (as was done manually above). Data channels actually support running multiple profiles via tiki-channel.php but ((PluginDataChannel)) needs to be enhanced to do this, to simplify it to one step.

Page name: createclassprofile
{CODE()}
{CODE(caption=>YAML)}
permissions:
  $profilerequest:subject$Default$ Class:
    include: [ ]
  $profilerequest:subject$Default$ Teachers:
    include: [ Teachers, $profilerequest:subject$Default$ Class ]
  $profilerequest:subject$Default$ Students:
    include: [ Students, $profilerequest:subject$Default$ Class ]
{CODE}
{CODE}

Page name: setupclassprofile
{CODE()}
{CODE(caption=>YAML)}
permissions:
  $profilerequest:subject$Default$ Class:
    include: [ Classes ]
objects:
  -
    type: wiki_page
    ref: class_handout
    data:
      name: $profilerequest:subject$Default$ Class Handout
  -
    type: wiki_page
    ref: class_assignment
    data:
      name: $profilerequest:subject$Default$ Class Assignment
  -
    type: category
    data:
      name: $profilerequest:subject$Default$ Class Handouts
      # Replace the parent ID below with the ID of the Handouts category.
      parent: 1
      items:
        - [ wiki_page, $class_handout ]
        - [ wiki_page, $class_assignment ]
{CODE}
{CODE}

Now, go to tiki-admin.php?page=profiles and configure the following Data Channels in the Advanced tab, referring to the page names where the profiles above are, and also setting that only Admins can execute these data channels.
{CODE()}
createclass, tiki://local, createclassprofile, Admins
setupclass, tiki://local, setupclassprofile, Admins
{CODE}

Then, we create wiki pages for the interface. Make these wiki pages only visible by Admins if you wish to secure them.

Page name: Create Class
{CODE()}
{DATACHANNEL(channel="createclass" returnURI="tiki-index.php?page=Setup%20Class")}
subject,Subject Name
{DATACHANNEL}
{CODE}

Page name: Setup Class
{CODE()}
You've completed the 1st step. Re-enter the subject name and setup the class below.
{DATACHANNEL(channel="setupclass" returnURI="tiki-index.php?page=Class%20Created")}
subject,Subject Name
{DATACHANNEL}
{CODE}

Page name: Class Created
{CODE()}
Congratulations. Your new class has been created.
{CODE}

Finally, go to "Create Class" and fill in "Biology" as the subject name and submit the form. The profile runs and then you will be redirected to Setup Class. Fill in "Biology" again and submit the form. You will be redirected to the "Class Created" page with the congratulatory message.

Now check the groups as well as categories in the admin panels and see that they are exactly like when you did it manually, and that the Roles permissions are automatically set. Additionally, each class has 2 wiki pages created by the profile and placed in the categories already: "Biology Class Handout" and "Biology Class Assignment".
!!!7. Set up a listing of group assets

This can be done through the LIST plugin. Create a page called "Biology Class Objects" (the name does not matter) with the following ((PluginList)) in it.

NOTE: Replace the 51 below with whatever the group ID of your group is.
{CODE()}
{LIST()}
{filter templatedgroup="51"}
{LIST}
{CODE}

!!!8. Set up a group menu

Go to tiki-admin_menus.php and create a ((Menu)). You can then place it anywhere via the smarty {menu} or in a module. For this demo, we will just put it in a module on the left column to keep things simple.

When creating a menu option, you select the Templated Group Container under "This is a dynamic menu option for a Templated Group in:". In our example, it would be "Classes".

{img type="fileId" fileId="1668" thumb="box"}

Create 2 menu items:
~np~--groupname-- Handout  linking to  ((--groupname-- Handout))~/np~
~np~--groupname-- Assignment  linking to  ((--groupname-- Assignment))~/np~

Then create a module and put the menu on the left column. So what does "dynamic menu option" mean? It means:

*The link will only appear if you are viewing an item that is categorized in the Managed Category of that templated group,
*The group name placeholder will be automatically be replaced with the name of the group.
*If you rename the group, the link will automatically change.

For example, If you go to the wiki page "Biology Class Handout", the links will appear and you can navigate from/to the handout and assignment. If you are on other pages then the links won't appear. If you go to another class, e.g. "Geology Class Handout", then the links will show the ones for Geology instead.

To hide the module completely when you are not viewing any asset of the Templated Group, you can set the module settings to show only in the categories that are in the subtree of the Handouts category like this:

{img type="fileId" fileId="1669" thumb="box"}




!!Organic Group Example

For a more extensive Organic Group (i.e. groups that are created and led by users) example, see ((Organic Group Example))