As a new user to Tiki, one of the very most crucially important things you can learn, is how to manage permissions.  This is not a step you can skip.  Everything depends on you understanding this part of the process.  I can't stress this enough.  If you fail to understand the permission system, then all of Tiki will give you nothing but headaches.  It starts here!

Why am I writing this? Because I didn't find any documentation anywhere that explained this to me in a nice simple fashion. I beat my head against it for days until I got help in the #tikiwiki irc channel.  Now that they explained it to me, I feel it's my duty to make this tutorial to help all of you out there understand it too.

How am I writing this?  I am going to write this from the perspective of my first time learning it.  I'll walk you through the first steps I took, the headaches I encountered, then the lessons I learned, and how I fixed them.  It's important to note that I'm not writing this as a step by step tutorial.  READ THE WHOLE THING FIRST, then try it on your new Tiki install.  Otherwise you will duplicate my missteps.

My story began with a need.  I needed a chat roleplay website for my friends who were no longer comfortable roleplaying on the site we were all familiar with.  It didn't take long for me to whip up a simple ajax webchat and a PHPBB to get the ball rolling.  As development proceeded I knew the PHPBB would not be sufficient for our needs.  We are a group of authors and as such, we needed collaboration tools.  Forums and chats are nice, but we wanted more such as blogs, file galleries, and a wiki.  My search for simple wiki software we could integrate into the PHPBB led me to discover TikiWiki.  I was intrigued so I looked into it a bit by skimming through 'Tiki for Smarties'.  I chuckled at the idea of 'we eat our own dog food' because I always thought it was stupid when websites advertising certain software were built with something else.  It seemed simple enough that I could straight up replace the PHPBB with the Tiki and so I discussed it with my team.  They were go for the change and so I began my journey.

I downloaded TikiWiki 10 and set it up on my local webserver.  The install went really smoothly and in just a few minutes, I was up and running!  Sweet!  I was very excited.  The next step was to configure the modules and then enable them with permissions.  It was at this point that I decided to just click around a bit and see what I could do with it.  Because I'd looked at "Tiki for Smarties" first, it didn't bother me that when I was logged in as a normal user, I couldn't do squat which was good because I just might have panicked had I not seen that this was normal first.

Here is where I began making mistakes so please do NOT follow these steps.

Having read that there were groups and categories and permissions that needed to be turned on before I could do anything, my first mistake was to go straight into the admin->permissions and try to enable the wiki.

<image>

I could see that there were only three items ont he line for PERMISSION.  Anonymous, Registered, and Admin.  So, after a moments thought, I opened the triangle next to 'wiki' and began ticking checkboxes for the admin to do everything and the registered user to view / edit / see history / view comments, and a few others.

Success!  My registered user could now see and edit the wiki!  I was so excited at this point that I didn't really pay much attention to the fact that the initial wiki page I saw with my admin user was not the same as the one I saw with my registered user.  I opened up the page as my registered user and made my first edit!  Right under the header I added a line of text saying, "This proves I can edit the wiki!".  I saved it and the form submitted correctly.  Sweet!  Then I looked at the page again.  ... The edit wasn't there.  Hmmph. I guess I screwed something up already, I thought to myself as I hit the edit button again.  No, right there under the first heading in the editor, my change was still there.  So I saved again and let the page refresh and again, the change wasn't there.  So I began to reason with myself as to why it wasn't there.  It didn't take long before I decided that there must be some kind of 'approval' system that was holding the change until and admin could look at it.  It was with this in mind that I then popped open my adminstrative user to have a peek around.  I logged in and surfed to the wiki page.  HOLY CRAP, THERE WAS MY CHANGE!  RIGHT WHERE IT WAS SUPPOSED TO BE!  Confused, I logged out and back in as my registered user.  The changes were NOT there.  I stress again that I was too stupid at this point still to realize that the pages had different text on them.  Brain decides that the logical conclusion is that changes are reflected immediately for administrators but have to be approved before they display to the lay user.  So I spent the next few hours surfing around in the admin user interface trying to find how to approve changes only to wind up empty handed.  Frustrated and stupid, I turned for the very first time, to the #tikiwiki IRC channel for help.

It took a few minutes to get somebody to answer me but answer me they did and soon we'd begun troubleshooting.  I wanted to screenshot my issues for them so I opened two different browser windows, one to the registered user and one to the admin.  It was then that I finally noticed something odd.  The text on the main page for the registered user was not the same as the text in the editor when I opened it up.  A few screenshots and some facepalming later, I learned about the existence of a module within Tiki called the 'GROUPS' module.  The 'GROUPS' module is a simple way to hide and show text on the wiki page based on the group of the user who is viewing it.  Thus, the changes that I'd made were in the portion of the page that was marked off by the groups module as for the admin group only.  That's why it didnt' show up on the page that the registered user could see after I saved but the admin user could see it.  I appreciate how cool that module is for stuff but I question the sense in putting that in the first page the user sees on a new install.

Moving on!  I'm still in the mistakes portion of this tutorial so please do NOT do what I did.  I'll show you a better way later.

The eyes of my understanding were beginning to open.  In the discussion, I showed off my permissions set and I was told that I had done it completely wrong and that anything that I'd done in the 'Permissions' area of the site would have to be undone later or it would really screw things up.  Frustrated by this revelation but still excited to continue, I went into my admin -> permissions and unchecked EVERYTHING!  Please, if you just installed a new install, do NOT uncheck anything that's checked by default! As soon as I did this, not only could my registered user not make any changes, he couldn't even SEE the wiki or anything at all!  Another few hours or so in the #tikiwiki channel and I had the basic default settings back.

So here I am now, back to square 1!  It's a good feeling!  NOT.  I was starting to get frustrated with it all and not for the first time I considered that this might not be worth the effort to figure out.  But I perservered and began asking the users in the #tikiwiki channel for their aged wisdom in how to get this all set up.  THIS IS WHERE THE REAL TUTORIAL BEGINS!

First let's establish some core concepts about the permissions system that will come into play later.

1: The people who visit your Tiki are called 'Users'.  This includes people who have registered and people who have not.

2: Users are sorted into GROUPS

You've probably read that you do not assign permissions to a user in Tikiwiki.  You assign permissions to groups and then move the user into or out of those groups to change their permissions.  Users can have multiple groups and groups can be nested to inherit permissions from the lower level group.  For example, in the initial setup, you have three groups, Anonymous, Registered, and Admins.  You can see they set it up so that Registered is a sub-group of Anonymous.  Therefore, anything an Anonymous has permission to do, Registered users can do too.  Simple enough?

3: While it's tempting to think of the different features that come bundled with TikiWiki as 'Objects', the truth of it is, it's the actual pages you create with them that are the Objects.  Therefore the wiki itself is NOT an object but each individual page in the wiki IS an Object.  The forum software itself is not an object, but when you create a 'new forum' then that forum is an object.  Objects can nest.  e.g. Wiki page objects have comment feature objects built into them.

4: Objects are sorted into CATEGORIES

Whenever you create a new wiki page or forum, you have the choice SOMEWHERE (I say that because it's not in the same place from one feature to the next) to assign a category or categories to that object.  Nested objects inherit the category of the parent.

Now, let's open our Tiki and look at these.  Go to admin -> groups.

You should have a simple list including the default three groups: Anonymous, Registered, and Admins.  On the right hand side, you will see a yellow key icon you can use to change the permissions for that group.  DO NOT!  Then there is a paper with pencil icon that will let you change details of the group.  Don't do that yet either.  We'll keep this really simple to start out with.  You can create additional groups here and alter the group structure.  You probably have a good idea how to do this already but there are important things I want to cover before you do so please finish reading this part before you start setting yours up.

Next we need to check out the categories.  Go to admin home (just click on the word 'admin' in the menu).  Let the page load completely and look around for Categories.  It's not there.  For some reason this critical permissions organization feature is not enabled by default.  So, in the 'preference filters' check the [X] Advanced to show the features that are available but disabled.  Find Categories (the icon is a clipboard with a flow diagram) and click on that. Check the box to activate the feature and then click 'Change Preferences' to save that.  Now 'Categories' will appear in your left hand menu.  Go ahead and click on that.  This will show you the basic categories admin tool.  It's empty.

Go ahead and click on 'Admin Category'. This page will show you your categories and let you manage them.  At the bottom is a tool to let you 'Create/Edit category'.  Use that now to create your first category.  Set the Parent to 'Top', set the name to 'Permissions', and the description to 'This is a container for my permission categories.'  Then save.

You should now see Permissions appear as a category you can click on.  It has an edit icon, a delete icon, and the yellow permission key.  DON'T CHANGE IT.  Not here.  The generic Permissions container I had you make will apply generic permissions across the whole site which you very likely do not want.

OK.  Now that we have everything turned on and ready, let's analyze our needs.  For this I used a very powerful tool.  Pencil and paper.  Go find some.  Ready? OK!  Let's continue.

First I drew a line down the middle of the page.  the left I marked 'Groups' and the right I marked 'Categories'.  Beneath groups I drew two circles side by side.  One I labeled 'Anonymous', the other 'Admins'.  Within the Anonymous circle, I drew a smaller circle and labeled it 'Registered'.  This represents our current groups.  Registered users get all the permissions of the Anonymous group.  On the 'Categories' side, I drew a huge circle and labeled it 'Permissions'.

Now comes the thinking.  Groups first.  Now, I want to have a moderation staff called 'Guides'.  They were Registered users with more permissions so within the Registered circle, I made a new circle called 'Guide Staff'.  The guide staff would have specialized roles so within guide staff I created circles for 'Wiki Admin', 'Forum Admin', and 'File Gallery Admin'.  Next, I want to have groups of users who are not guides but have permission to see pages that the others can't.  So I drew a circle next to 'Guide Staff' and labeled it 'Canon Players'.  Then on advice of the guys in the forums, I created another circle alongside that for 'Wiki Editors'.  My result looked like this:

<image>

If you've gotten this far without erasing and starting over, then you're better at this than I am but get ready to make a big change.  You see, in a moderated forum, it will become necessary at some point to remove permissions from a user.  If you don't plan for this at the start, then you give too many permissions to the 'Registered' group and the only way to take those away, is to take them away from everyone.  My solution to this was to create another circle just inside 'Registered' called 'Registered + Voice'.  The concept here is that when a person registers, they will become 'Registered' but 'Registered' by itself can't do any more than an Anonymous user could.  'Registered + Voice' would be the group that had permission to do fun stuff in my site.  That way if a 'Registered + Voice' user misbehaves, I can remove their 'Voice' for a while.  You're probably going to whine about the overhead of setting all the users who sign up to have 'Voice' but I'll show you when we actually start implementing these, that there is a slick way to avoid that.  My final image looks like this:

<image>

Now for categories, I only want a few different kids of pages.  I want some the Anonymous users can see, Some the Registered users only can see, some that only the guide staff can see, some that only the Canon Players can see.  So inside of the 'Permissions' circle, I drew four circles next to each other: 'Public', 'Registered', 'Guide Staff', and 'Canon Players'.  Later I would realize the need of having pages that were visible to all but only the guides could edit so I added a fifth: 'Guide Protected'.  My needs for Categories were pretty basic.

Alright!  Now look over your plan.  Do a few thought experiments to make sure if you have nested groups or categories, that you understand the implications of assigning the same user to multiple groups.  Such as making sure I understood what might happen if a 'guide' was also a 'wiki editor' and a 'canon player' and if I would ever need to make a 'forum admin' who was not a 'guide staff'.

Done? Then we're ready to implement our plan!

First let's head to admin -> groups and add our groups, making sure to set up the parents correctly by choosing which group the new group inherits permissions from.  We should end up with a tree structure but instead the groups page sorts them alphabetically.  Now, when you are setting up your groups, one of the options is 'Users are automatically assigned at registration in the group if their emails match the pattern'.  And it gives some example regular expressions.  If you aren't familiar with Regular expressions, then this is intimidating but most people won't need to really switch based on which emails come in so I'll teach you a very simple one: '/.*/' . That regular expression means accept ANYTHING!  We'll use this on the 'Registered + Voice' category so that all users that come in will gain the 'Registered + Voice' Group by default; all the others we'll leave blank so they can only be assigned by Admin.  Very nice!

All set up? Then we'll head over to Categories and do the same.  Create them underneath Permissions.  This page puts them in a nice tree structure so you can tell what you've done which is nice.

Once you have your categories set up, now FINALLY, we are ready to start setting up our permissions.  Choose one of your new categories.  Let's start with 'Public' and click on the yellow key.  This takes us to a page that looks like the Global permissions page where I made my mistakes earlier, but it's not. This is the Category permissions page.  Since I chose the public category, I'm going to be affecting all pages on my forum that are tagged with the 'public' category.  My purpose for this category was content that is publically viewable and that wiki editors or guide staff can edit.  For simplicity, I'll only cover setting up wiki permissions so first thing I'll do is go to the grey bar near the top and click on the tab 'Select Groups'.  This page lets you checkbox which groups you are setting permissions for.  I don't want to mess with admins right now so I'll uncheck that but I do want anonymous, registered, registered + voice, guide staff, and wiki admin.  Click 'Select' to confirm your choices.  (note the nice tree diagram here that would be NICE on the group admin page)  Then head back to the 'Assign Permissions' tab and open the triangle next to 'Wiki'.

You now see a grid of checkboxes.  The columns are your groups, the rows are your permissions and the page you are on determines the category.  We should still be in 'Public'.  The thought here is, 'On a wiki page that is Public, who should be able to do what with it?'.  First thing I do is use the checkbox at the top on the permissions line to check all the boxes for the 'Wiki Admin'.  They can do everything.  Then I start assigning the individual permissions.
View Pages: Everyone.  Checkbox 'Anonymous'.  Notice amazingly that any groups that inherit permissions from Anonymous automatically get checked.
Edit Pages: I only want wiki editors and guide staff to be able to edit these pages.  So I check those boxes.
Wiki History: User can see the history of how the page has changed.  Not a critical feature but it does add page clutter so only the guide staff and wiki editors get it.
Admin the Wiki: Only the Wiki Admin.
Assign Perms to Wiki pages: Wiki Admin
Remove Pages: Only Wiki Admin
Rename / rollback Pages: Guide staff, Wiki Editors, Wiki admin
Upload Pictures: Guide staff, Wiki Editors, Wiki admin
Can view in module and feed the wiki pages: I have no idea what this is so wiki admin only.
View wiki comments: Everyone!  Note* Comments is a feature with it's own permissions set that must be configured independently.  If it's on a page that is 'Public' then the comments are considered to be 'public' category too because nested objects inherit the parent category.
View source of Wiki Pages: I don't see the need for anyone to do this but the wiki admin.

And there we have it!  For the public type of pages, we now have configured how we want the permissions to work!  Click 'Assign' to save your work and then at the top, press 'Back' to return to the categories page.  You will notice something odd.  The yellow key has turned green.  This is just a shortcut to remind you that you did actually go in and configure the permisssions for that group.  This is useful because.... now we get to go through every single other category we created and do the same thing again!

This time I'll choose my 'registered' category.  The purpose of this category is to hold content that the registered users can see and anonymous visitors cannot.  Remember the mantra: 'On a wiki page that is Registered, who should be able to do what with it?'. We click on the yellow key and then open the triangle next to 'Wiki' again.  First thing I do is use the checkbox at the top on the permissions line to check all the boxes for the 'Wiki Admin'.  They can do everything.  Then I start assigning the individual permissions.
View Pages: Registered and Registered + Voice plus any other groups I want to see these pages.
Edit Pages: I only want wiki editors and guide staff to be able to edit these pages.  So I check those boxes.
Wiki History: User can see the history of how the page has changed.  Not a critical feature but it does add page clutter so only the guide staff and wiki editors get it.
Admin the Wiki: Only the Wiki Admin.
Assign Perms to Wiki pages: Wiki Admin
Remove Pages: Only Wiki Admin
Rename / rollback Pages: Guide staff, Wiki Editors, Wiki admin
Upload Pictures: Guide staff, Wiki Editors, Wiki admin
Can view in module and feed the wiki pages: I have no idea what this is so wiki admin only.
View wiki comments: Registered and Registered + Voice and any above that that aren't already clicked
View source of Wiki Pages: I don't see the need for anyone to do this but the wiki admin.

Since I did not give anonymous any permission to see a 'Registered' page, then any page I want to hide from random visitors I just set into the 'Registered' Category.

See how this works?  It takes some work and some thought but it shouldn't take you too long to get your site all set up and online with a clever and well-thought out permissions system that will prevent many future headaches.