7. Permissions

The Zikula permissions system can be an important part of any Zikula site, allowing you to customize the experience for each of your visitors. A website’s permissions can be as simple as the default layout, or complex with multiple tiers of user. For a user unused to the Zikula permissions system, it can be confusing and daunting, however it does not take long to become experienced in the use of permissions.

Through permissions, you can customize what your users see of your website. Permissions can be used to completely restrict your gallery for unregistered users, but make it available to registered users. With the core news module in Zikula, you can restrict the ability to submit news for unregistered users, but allow it for registered users. You can also have a group with administration permissions just to the news module to moderate and approve these stories.

Basic Structure:
Group permissions have four different parts; these are Group, Component, Instance and Level. Group is the group (set in administration > groups) that the permission corresponds with; users in this group will all be affected by the permission that you create. The component is the broad area, which the permission will relate to; this is usually a module, however it can also point to blocks, among other things. The instance is the more detailed area of the permission, within the component, for example if the component is set to point to blocks, the instance would point to the specific block. Another example is the Topics module, for this the component would be Topics::Topic however to restrict a specific topic, you need the instance: Topic name::Topic ID.

It is important to note at this point that a list is provided of all the available components and instances. It can be accessed by clicking the Component link in the column header of the permissions table. The window that pops up contains a list of all the available components, and the instances that can be used in conjunction with those components. This is especially useful when working with modules you have not used before, or that have complicated permissions structures.

Here is a copy of the default permissions table as it is after a fresh install of Zikula:

No	Group	Component	Instance	Level
1	Admins	.*	.*	Admin
2	All Groups	Menublock::	Main Menu:Administration:	None
3	Users	.*	.*	Comment
4	Unregistered	Menublock::	Main Menu:(Logout|Submit News|My Account):	None
5	Unregistered	.*	.*	Read

Below the effect of each of the permissions is explained, by number.

1. Members of the Admins group have administration rights over everything.
2. Removes rights to Administration (link only) in block named ‘Main Menu’ for all groups. This does not affect the Admins group, as due to the hierarchical nature of the permissions, the all groups permission below the Admins permission has no effect.
3. Users comment access over all modules.
4. Similar to 2 – restricts access to the stated links for unregistered users. Submit news is restricted because it requires at least comment access to function, and in the default permissions set unregistered only have read access.
5. Read permission over whole site for unregistered users.

Sub Admin Permissions
Permissions to administrate modules are quite simple. To give a certain group administration rights to a module, then just grant them access to

Group	Component	Instance	Level
Sub-Admins	<component>	::	Admin

This means that whenever the users in that group go to /admin.php they will see all the modules you give them access rights to, and not the modules they do not have admin rights to. To find the components for the specific modules you wish to grant admin access to you should click the component link in the column header of the permissions table.

To give your users access to the administration link in the main menu you will need another permission:

Group	Component	Instance	Level
Sub-Admins	Menublock::	Main Menu:Administration:	Comment

Replace "Main Menu" with the name of your menu. This will give all users in the Sub-Admins link access to the Administration link in the main menu. However, this must be placed above the All Groups permission that restricts the link, otherwise it will not take effect. This permission is not necessary as long as the overall permission (for an example of this see below), is placed above the All Groups restrictive permission, as the overall permission takes effect before the restrictive permission below it.

Something that is often overlooked when creating a new group is to give them an overall permission over the whole site, otherwise they will see very little.

Group	Component	Instance	Level
Sub-Admins	.*	.*	Comment

So your final permission set should look something like what follows:

No	Group	Component	Instance	Level
1	Admins	.*	.*	Admin
2	Sub-Admins	(FAQ|Polls)::	.*	Admin
3	Sub-Admins	.*	.*	Comment
4	All Groups	Menublock::	Main Menu:Administration	Comment
5	Users	.*	.*	Comment
6	Unregistered	Menublock::	Main Menu:(Logout|Submit News|My Account):	None
7	Unregistered	.*	.*	Read

Demonstration Permissions Set
The aim of this demonstration is a small example of what can be done with permissions, and an explanation of how each permissions achieves its purpose.

I have a hypothetical site with three menu blocks:

• The Main Menu – Contains links to publicly viewable modules
• Members Only Menu – Contains links to modules viewable only to registered users.
• Sub Admin Menu – Gives the sub-admin group links to the administration area of certain modules

I also have two blocks:

• Gallery Random Picture – Members only
• Members Online - All Users

Public Modules: Members list, Weblinks, Downloads Private Module: Gallery Sub-Admin Modules: Add Story, Downloads

The permissions table to achieve this is below:

No	Group	Component	Instance	Level
1	Admins	.*	.*	Admin
2	Sub-Admins	Downloads::	.*	Admin
3	Sub-Admins	Stories::Story?	.*	Add
4	Sub-Admins	.*	.*	Comment
5	All Groups	Menublock::	Main Menu	None
6	Users	.*	.*	Comment
7	Unregistered	Gallery::	.*	None
8	Unregistered	Galleryblock::	Random Image::	None
9	Unregistered	Menublock::	Members Only::	None
10	Unregistered	.*	.*	Read