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

1.1.1. 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.

1.1.2. 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.

1.1.3. 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 Searchbutton, 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

1.1.4. 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.

1.1.5. 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.

1.1.6. 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: 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

Workspace howto | WS howto | WShowto| WS tutorial | Workspace Tutorial | Workspaces Tutorial | Workspaces howto