Home › Support › Knowledge Base ›

How does Sakai determine which tools to place on worksite "Home" pages? Can this be influenced by worksite type?

Knowledge Base: Sakai
Updated: April 17, 2008

Site Type and Tool/Page Order Configuration

First, some background, which is taken almost entirely from the canonical source: John Leasia's semi-annual "Configuring Sakai" presentations

The selectable site types displayed during the worksite creation process in Worksite Setup are defined by the sakai.sitesetup tool definition. For example:

<registration>

	<tool id="sakai.sitesetup" title="Worksite Setup" 
		description="Modify your sites and create new ones.">

		<!-- types are seperated by , -->
		<!-- Steps for adding new site type: -->
		<!-- 1. add the site type into the following siteTypes value -->
		<!-- 2. add the site type as category into related tool reg files-->
		<!-- 3. if the site title is editable, add the site type into 
			titleEditableSiteType in sakai.properties file -->
		<!-- 4. if specific tool order for the site type is needed, 
			specify it inside toolOrder.xml file -->
		<configuration name="siteTypes" value="course,project,portfolio" />
		
		<!-- default site type -->
		<configuration name="defaultSiteType" value="project" />
		<!-- types of sites that can either be public or private -->
		<configuration name="publicChangeableSiteTypes" value="project" />
		<!-- types of sites that are always public -->
		<configuration name="publicSiteTypes" value="course" />
		<!-- types of sites that are always private -->
		<configuration name="privateSiteTypes" value="" />

		<configuration name="site_mode" value="sitesetup" type="final" />

		<category name="myworkspace" />
		
	</tool>

</registration>

The set of site types defined in sakai.sitesetup is distinct from the set of site types displayed in the gateway Sites tool. Whereas sakai.sitesetup defines the set of site types that may exist (with some exceptions), the types displayed by the gateway Sites tool are the unique set of types associated with sites which actually exist.

Each occurrence of /registration/tool/category@name in a given tool's metadata file defines a site type on which that tool can be placed by an end user of the Worksite Setup and Site Info tools. This configuration can be suppressed by "stealthing" tools in sakai.properties. For example: stealthTools@org.sakaiproject.api.kernel.tool.ActiveToolManager=tool.x, tool.y, tool.z would cause tool.x, tool.y, and tool.z to never appear in Worksite Setup/Site Info tool selection UIs. Alternatively, visibleTools@org.sakaiproject.tool.api.ActiveToolManager can be used to remove tool IDs from the stealthed set. hiddenTools@org.sakaiproject.tool.api.ActiveToolManager can be used to extend the stealthed set.

The set of pre-selected tools displayed in Worksite Setup is determined by toolOrder.xml. The default version of that file is deployed in $CATALINA_HOME/shared/lib/sakai-component-*.jar and can be overridden by ${sakai.home}/toolOrder.xml. For example:

<toolOrder>

	<category name="myworkspace">
		<tool id = "home" selected = "true" />
		<tool id = "sakai.sitesetup" required = "true" />
		<tool id = "sakai.membership" required="true" />
		<tool id = "sakai.preferences" required="true" />
	</category>

	<!-- snip -->
</toolOrder>

This file determines site type-scoped page (tool, actually) ordering, default selection status, and related rules. It does not determine which tools actually appear either in Worksite Setup or on any given worksite.

Setting "required="true"" implies "selected="true"".

Worksite "Home" Page Configuration

If you browse through the default toolOrder.xml, you'll notice /toolOrder/category/tool@id="home" appears in in several categories. You might also notice that there is no such tool ID defined in any tool registration file. So how is it that the "Home" tool appears in the Worksite Setup/Site Info tool list? And how is it that toolOrder.xml can influence the ordering of a non-existent tool ID?

It turns out that rendering the "Home" tool option is hard-coded into the chef_site-newSiteFeatures.vm Velocity template. The "backing bean" for that template, SiteAction, implements special handling for SiteAction.HOME_TOOL_ID, which happens to correspond with the tool ID rendered by the Velocity template ("home"). The portion of the special handling of interest to us is in addFeatures(), which executes a series of hard-coded tests to determine which tools to place on the page, with special attention given to synoptic tooling (from 2-5-x):

      
	if (hasHome) {
		// Home is a special case, with several tools on the page.
		// "home" is hard coded in chef_site-addRemoveFeatures.vm.
		try {
			SitePage page = site.addPage();
			page.setTitle(rb.getString("java.home")); // the visible
			// label on the
			// tool menu
			if (hasAnnouncement || hasDiscussion || hasChat
					|| hasSchedule) {
				page.setLayout(SitePage.LAYOUT_DOUBLE_COL);
			} else {
				page.setLayout(SitePage.LAYOUT_SINGLE_COL);
			}
		
			// Add worksite information tool
			ToolConfiguration tool = page.addTool();
			Tool wsInfoTool = ToolManager.getTool("sakai.iframe.site");
			tool.setTool("sakai.iframe.site", wsInfoTool);
			tool.setTitle(wsInfoTool != null?wsInfoTool.getTitle():"");
			tool.setLayoutHints("0,0");

			if (hasAnnouncement) {
				// Add synoptic announcements tool
				tool = page.addTool();
				tool.setTool("sakai.synoptic.announcement", ToolManager
						.getTool("sakai.synoptic.announcement"));
				tool.setTitle(rb.getString("java.recann"));
				tool.setLayoutHints("0,1");
			}

			if (hasDiscussion) {
				// Add synoptic announcements tool
				tool = page.addTool();
				tool.setTool("sakai.synoptic.discussion", ToolManager
						.getTool("sakai.synoptic.discussion"));
				tool.setTitle("Recent Discussion Items");
				tool.setLayoutHints("1,1");
			}

			if (hasChat) {
				// Add synoptic chat tool
				tool = page.addTool();
				tool.setTool("sakai.synoptic.chat", ToolManager
						.getTool("sakai.synoptic.chat"));
				tool.setTitle("Recent Chat Messages");
				tool.setLayoutHints("2,1");
			}

			if (hasSchedule && notStealthOrHiddenTool(TOOL_ID_SUMMARY_CALENDAR)) {
				// Add synoptic schedule tool
				tool = page.addTool();
				tool.setTool(TOOL_ID_SUMMARY_CALENDAR, ToolManager
						.getTool(TOOL_ID_SUMMARY_CALENDAR));
				tool.setTitle(rb.getString("java.reccal"));
				tool.setLayoutHints("3,1");
			}

			if (hasMessageCenter) {
				// Add synoptic Message Center tool
				tool = page.addTool();
				tool.setTool("sakai.synoptic.messagecenter", ToolManager
						.getTool("sakai.synoptic.messagecenter"));
				tool.setTitle(rb.getString("java.recmsg"));
				tool.setLayoutHints("4,1");
			}

		} catch (Exception e) {
			M_log.warn("SiteAction addFeatures Exception:" + e.getMessage());
		}

		state.setAttribute(STATE_TOOL_HOME_SELECTED, Boolean.TRUE);

		// Order tools - move Home to the top
		pageList = site.getPages();
		if (pageList != null && pageList.size() != 0) {
			for (ListIterator i = pageList.listIterator(); i.hasNext();) {
				SitePage page = (SitePage) i.next();
				if ((page.getTitle()).equals(rb.getString("java.home"))) {
					moves = pageList.indexOf(page);
					for (int n = 0; n < moves; n++) {
						page.moveUp();
					}
				}
			}
		}
	} // Home feature

As shown here, SiteAction.addFeatures() forces the "Home" page to the top of the worksite's default page ordering, but now that we know there is in fact no code which synthesizes the "home" tool ID, how exactly does toolOrder.xml influences the relative ordering of the "Home" page?. Or, what exactly is the effect of the <tool id = "home" selected = "true" /> element that appears several times in the default toolOrder.xml? The answer is: "no effect."

Assuming one hasn't explicitly reordered pages for a particular site, page ordering is actually determined by tool IDs rather than page IDs or names. Thus, ignoring the attempt at default ordering in SiteAction.addFeatures(), the fact that "Home" typically sorts to the top of a worksite's page navigation is actually a side-effect of the tools placed on that page. For example, in the default page ordering for project worksites, the special "site" Web Content tool and synoptic tooling are the first tools listed:

<category name="project">
	<tool id = "sakai.iframe.site" />
	<tool id = "sakai.synoptic.chat" />
	<tool id = "sakai.synoptic.discussion" />
	<tool id = "sakai.synoptic.announcement" />
	<tool id = "home" selected = "true" />
	<tool id = "sakai.syllabus" />
	<tool id = "sakai.schedule" />
	<tool id = "sakai.announcements" />
	<tool id = "sakai.resources" />
	<!-- snip -->
</category>

Thus, so long as those tools are placed on "Home" and no other custom ordering is specified, e.g. via the Page Order Helper, "Home" will always sort to the top of the page navigation panel.

To prove this to yourself, create a worksite consisting of the "Home" page and another page having the Resources tool. Observe that the "Home" page sorts to the top. Then, using the Admin Sites tool, remove all tools from the "Home" page and place the Gradebook instead. Navigate back to the worksite and notice that the "Home" and "Resources" ordering has been reversed.

Customizing "Home" Page Tool Placements

Since tool placements on "Home" pages are hard-coded in SiteAction.addFeatures(), there is no purely configurational mechanism for specifying institutionally- or site type-specific "Home" page layouts.

Adding such a feature could take several forms:

  1. Define special template worksites similar to !worksite, one for each worksite type, each having a custom "Home" page layout. Modify SiteAction.addFeatures() to consider the placements defined by the appropriate template.
  2. Modify SiteAction.addFeatures() similarly to what was described above, but read "Home" layouts from XML configuration stored on the file system, possibly in additional configuration elements in sakai.sitesetup.xml
  3. Modify SiteAction.addFeatures() similarly to what was described above, but read "Home" layouts from configuration settable from sakai.properties
  4. Modify the Worksite Setup/Site Info workflow/UI to allow end-users to configure multi-tool pages manually. This would work best in coordination with one of the three options described above.
  5. Implement a custom SiteAdvisor to selectively rearrange "Home" layouts prior to creation

Option #2 is most consistent with existing Worksite Setup configuration mechanisms, but is somewhat cumbersome because it forces institutions to fork source code modules and/or maintain scripts for publishing a locally customized tool registration file. Option #3 is more appealing in that it cleanly separates default and local configurations, but Option #1 is even more appealing in that it allows for global configuration via the standard UI, i.e. it does not require per-node edits to properties/XML files. The primary drawback to #1 is its obscurity. No administrator would ever guess that "Home" layouts would be managed by magical site templates without first reading documentation to that effect.

Option #4 might be convenient, but is effectively "UI sugar" and does not address the issues described above with setting institutional default "Home" layouts. Hence the statement that Option #4 works best in coordination with one of the three other options. Other first-class feature adds to the Worksite Setup UI to allow super-users to refine default "Home" layouts without resorting to (direct) configuration of magical templates might also be appealing if development resources are not an issue.

Option #5 may be appealing in that it could be implemented completely orthogonally w/r/t the larger Sakai codebase, but should be viewed as a last-resort workaround on the grounds that it is even more obscure than any of the other options and ignores the fact that configurable "Home" layout should be a core feature of the worksite setup process.