History: Tutorial: Manually creating a Workspace

            ! Tutorial: Manually creating a Workspace

!! Background
This page contains a detailed ((tutorial)) for how to setup a ((Workspace)) using the manual setup method.

Although Tiki does not have a concept of workspaces per se, it is possible to support most features of a workspace by appropriately configuring lower level components, namely: ((Categories)), ((Perspectives)) and optionally, ((Groups)).

Before we describe the various steps involved, let's first define what we mean by a workspace. In most people's mind, the term workspace evokes the concept of a section of a Tiki site that acts as though it was a completely separate site. 

Tiki workspaces are __almost__ that. See the Caveats section at the bottom of this page for a description of some idiosyncrasies of workspaces in Tiki.

In the following tutorial, we will run you through the steps required to:
* create a workspace called __Hello World Space__
* set its home page to be __Hello World Home__
* limit its access to a group of users called __Hello World Users__ 

!! Steps
!!!# Create a category to bind objects of the workspace together
First, you need a way to tell that certain objects belong together in a workspace. You do this by creating a category for the workspace.
* Enable the Categories feature if not already active
** Admin > Features > Categories
* Create a category
** The name of the category will be the name of your workspace
** Categories > Admin Category
*** Enter the name of the workspace (__Hello World Space__ in our case).
*** Probably best to leave the parent category at __Top__. It could be that you can embed workspaces within other workspaces, but I don't know for sure that this will work.
*** Hit __Save__ button.

!!!# Create a Perspective so you can configure the settings of objects in the workspace
At this point, you have a way of saying that objects belong together in the workspace. But now you need a way to globally change settings for objects in the workspace.

You do this by creating a ((Perspective)). You can think of a perspective as a collection of settings and preferences that can be activated at any point, in order to override the default settings of the host site.

To create a ((Perspective)):
* Go to tiki-edit_perspective.php.
** Note: This script assumes that features __feature_perspective__ and __feature_jquery_ui__ are enabled. If they aren't already, the script will prompt you to activate them. Assuming you have admin privileges, you can just check the two checkboxes and click __set__.
** Click on __Create__ tab.
*** Enter a name for the perspective. For example, in our case you might use __Hello World Perspective__.

!!!# Setup the Perspective as a "jail" for the workspace
Among other things, ((Perspectives)) can be used to contain all tiki actions (ex: searches, creation of pages) within one or more categories. This is called a category jail. In a workspace context, this is useful, because when you are in a workspace, you typically want searches to be limited to that workspace. Similarly, if you create a new page while inside a workspace, you would like that page to be created inside that same workspace by default. Both of these and more can be accomplished using the __Category jail__ preference of the workspace's ((Perspective)) (well, sort of... again, see the Caveats section at the bottom of this page). 

But before you can do this, you must first find out the ID of the workspace's category:
* Admin > Categories > Administer categories
** Click on the Pen icon to the left of the category
** Look at the categID argument in the URL. That's the ID of the category.
** For this example, let's assume that categID=11.

Next, edit the workspaces ((Perspective)):
* tiki-edit_perspectives.php
* Click on __Hello World Perspective__
* In the field to the left of the __Search__button, type the word "jail", and hit __Search__.
* Below the search form, you will see a form that says __Category jail__.
** Drag and drop the form to the __Configurations__ section at the top of the page.
** Enter the workspace's category ID in the __Category jail__ field.
** Hit __Save__

!!!# Set the workspace's home page
At this point, you have created a clear perimeter around your workspace, and you can start configuring it as much as you want.

In particular, you probably want the workspace to have a different home page than the host tiki site.
* tiki-edit_perspective.php
* Click on __Hello World Perspective__
* In the search field, enter "home"
* Drag and drop the __Home page:__ form from the bottom to the __Configurations__ section at the top.
* Set the value of __Home page:__ to __Hello World Home__.
* Hit __Save__

At this point, you are probably keen to start seeing your what your workspace looks like. 
* tiki-edit_perspective.php > List
* Click on the green arrow to the left of __Hello World Perspective__
* This should take you to the workspace's home page, which is __Hello World Home__.
* To see the effect of the "jail", edit that home page, and create a link to a new page called __New page in Hello World workspace__
* Save the home page, and click on the link to the new page, in order to create it.
* Click on the __Categories__ tab and notice that the new page's category has been automatically set to __Hello World Workspace__, in effect, putting it into that workspace.

!!!# Change any other settings you want
By editing the workspace's ((Perspective)) as above, you can impose most kinds of Tiki settings and preferences on the pages of the workspace. In particular, you can decide to apply a different theme than the theme of the host tiki site. 

However, you cannot use the ((Perspective)) to set special permissions on objects of the workspace. For that, you need to set category-level permissions, as described in the next section.

!!!# Set custom permissions on the workspace
Setting permissions on a workspace is essentially the same as setting permissions on a category. 

Typically, you will start by creating one or more groups specifically for the workspace
** Admin > Groups 
*** Add a new group
**** in __Groups__ field, type the name of the users group (__Hello World Users__ in our case).

To set category level permissions for the groups:
* Admin > Categories > Amin Categories
** Click on the key icon to the left of the workspace name (__Hello World Space__ in our case).
** Set permissions to the workspace. For example, in our case, we want to limit read and write access to the wiki pages to the newly created group __Hello World Users__. To do this:
*** Click on the __Select Groups__ tab.
**** Check the __Hello World Users__ group. This will make it possible for you to grant members of this group specific permissions for the __Hello World Workspace__. If you don't do this step first, the __Hello World Users__ group will not appear in the list of groups that can be assigned to the workspace.
*** Click on the __Assign Permissions__ tab
**** Set permissions as you wish. In our case, we would go into the __wiki__ section, and check a bunch of permissions there, for the column that corresponds to __Hello World Users__ group. 
^''__Note__''  Permissions are not always checked at the category level, it may be necessary to apply the permissions to a group at the global level. Because of this it may be useful to create group(s) that correspond to a category and categories that correspond to a perspective.   Then if you have to assign a global permission it will affect only your Perspective.^
!! Caveat: workspaces, their split personalities, and how to prevent that
Well, that's pretty much it. You now have a way to collect objects together, and impose a perspective on top of them, that will make them look and behave in ways that are different from objects that reside in the host tiki site.

But actually, it's not quite that simple. The problem is that although the workspace's perspective is set up to act as a "jail" for the workspace's category, the objects in the category are not in fact forced to behave in the way specified by the perspective. In a way, the "Category jail" property of a ((Perspective)) is a bit of a misnomer, because it implies that it's the ((Perspective)) that's restricting the category. But in fact, it's more like the other way around: it's the list of categories specified in the "category jail" field that are restricting where the ((Perspective)) is allowed to search and create pages. 

As a matter of fact, objects in a category can be subjected to any number of ((Perspectives)), even ones for which the category is not listed in the ((Perspective))'s category jail attribute. It's a little bit as though workspaces have split personalities, and can change their appearance and settings in unpredictable ways, which can have somewhat counterintuitive and undesirable side effects.

For example, if you go to a page in workspace A of a tiki site, then that workspace's ((Perspective)) will be activated. If that page contains a link to a page in a different workspace B of the same tiki site, then that page will be displayed, but using the ((Perspective)) of workspace A! This is usually not what you would want.

One way to deal with this issue is to make the tiki site be multi-domain. This assumes that you have more than one internet domains at your disposal. You do this as follows:
* Set the tiki site as being multi-domain
** Admin > general > general settings
*** Check __Multi domain__ box
*** The __Multi-domain Configuration__ box appears. In it, specify each of the domain names for the site, followed by a comma and the ID of the perspective that will correspond to that domain. Put one domain per line.
*** Hit __Change Preferences__

Note that this solution is not completely clean either. Indeed, eventhough end users now see the two workspaces as separate sites, they in fact share the same namespace. In other words, you cannot have two objects of the same name in those two "sites".

* Workaround:
** use the "display name stripper" for wiki pages (e.g. ":WS") under the "Admin home > Wiki" admin panel
++ In this approach, you need to append something like ":WS01" to the page "Introduction" (thus, the real page name would be "Introduction:WS1", or "Introduction:WS2" for the second workspace, etc), but users would only see "Introduction" as the page name in the page. 
++ Listing pages, though, should show that appended text... so that, is not a real solution to this issue stated above, but just a partial workaround for page names. 

Related: ((dev:lookup perspective according to category IDs))
!! Open questions
Q: When new users register, can they tell the admin which workspace they are asking to be registered for?
A: You can try using the registration tracker and having a tracker field for the parent category of the workspace categories.


-=aliases=-
(alias(Workspace howto)) | (alias(WS howto)) | (alias(WShowto))| (alias(WS tutorial)) | (alias(Workspace Tutorial)) | (alias(Workspaces Tutorial)) | (alias(Workspaces howto))