| Warning | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
The information below is for very old versions of Sakai (Sakai 2.4 or older). See:
The Sakai Documentation Working Group manages the help in Sakai 10+. They edit it on screenstepslive.com and then code converts the screensteps export HTML ZIP into a Sakai compatible structure. The base help files are at: http://sakai.screenstepslive.com/s/5276 |
Adding Help to Your Tool
This document describes the process of adding help documentation to your tool. The help created using this process will show up when users click the help icon within a tool frame. Help is context sensitive (somewhat), and will open to the default help page for your tool when help is opened from within your tool itself.
...
The project.xml file controls how maven will build and deploy this portion of the tool. The ultimate goal is to create a jar that will deployed into TOMCAT_HOME/shared/lib/. This can be accomplished using a project.xml file whose contents are along these lines:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?>
<project>
<pomVersion>3</pomVersion>
<extend>../../master/project.xml</extend>
<name>Tool Name Help</name>
<id>sakai-toolid-help</id>
<currentVersion>${sakai.version}</currentVersion>
<properties>
<deploy.type>jar</deploy.type>
<deploy.target>shared</deploy.target>
</properties>
<build>
<sourceDirectory>src</sourceDirectory>
<resources>
<resource>
<directory>src</directory>
</resource>
</resources>
</build>
</project>
|
...
The file help.xml is a kind of packing list for all the html files that are displayed by the help tool. It controls which page is the default and lists all subordinate pages in the table of contents in the display order desired.
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
<beans>
<bean id="toolidDefault" class="org.sakaiproject.component.app.help.model.ResourceBean">
<property name="docId"><value>tooliddefault</value></property>
<property name="name"><value>Tool Name Default Help Page</value></property>
<property name="location"><value>/sakai_configviewer/tooliddefault.html</value></property>
<property name="defaultForTool"><value>tool.id</value></property>
</bean>
<bean id="toolidSubordinate" class="org.sakaiproject.component.app.help.model.ResourceBean">
<property name="docId"><value>toolidsub</value></property>
<property name="name"><value>Tool Name Subordinate Help Page</value></property>
<property name="location"><value>/sakai_configviewer/toolidsub.html</value></property>
</bean>
<bean id="org.sakaiproject.api.app.help.TableOfContents"
class="org.sakaiproject.component.app.help.model.TableOfContentsBean">
<property name="name"><value>root</value></property>
<property name="categories">
<list>
<bean id="announcementCategory" class="org.sakaiproject.component.app.help.model.CategoryBean">
<property name="name"><value>Tool Name</value></property>
<property name="resources">
<list>
<ref bean="toolidDefault"/>
<ref bean="toolidSubordinate"/>
</list>
</property>
</bean>
</list>
</property>
</bean>
</beans>
|
...
As with the subordinate page described below, this file must be a valid and well-formed HTML file, along these lines:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head>
<title>Tool Name: Overview</title>
<style type="text/css">
/* Style for specific inline images */
/* Style for specific ordered lists */
/* Style for specific table cells */
</style>
<link type="text/css" href="/library/skin/tool_base.css" media="all" rel="stylesheet" />
<link type="text/css" href="/library/skin/default/tool.css" media="all" rel="stylesheet" />
</head>
<body>
<div class="helpBody">
<h2>Tool Name: Default Page</h2>
<h3>Introduction</h3>
<p>This is the default page users will see when they launch the help tool by clicking the help icon
(<img src="sample.gif"/>) from within your tool.</p>
</div>
</body>
</html>
|
...
For the purposes of demonstration, here is a sample version of toolidsub.html:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head>
<title>Tool Name: Subordinate Page</title>
<style type="text/css">
/* Style for specific inline images */
/* Style for specific ordered lists */
/* Style for specific table cells */
</style>
<link type="text/css" href="/library/skin/tool_base.css" media="all" rel="stylesheet" />
<link type="text/css" href="/library/skin/default/tool.css" media="all" rel="stylesheet" />
</head>
<body>
<div class="helpBody">
<h2>Tool Name: Subordinate Page</h2>
<h3>Introduction</h3>
<p>This is a subordinate page.</p>
</div>
</body>
</html>
|