forked from sakaiproject/sakai
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
188 lines (139 loc) · 7.57 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
==Help Configuration==
Sakai 10 Help Rewrite: https://jira.sakaiproject.org/browse/SAK-26062
Sakai 10 Help Process: https://confluence.sakaiproject.org/display/ESUP/Help+Files+and+Documentation+Process+Redesign
How were help files generated for Sakai 10?
--------------------------------------------
1) Articles were authoried in an online system called Screensteps
2) HTML + Images were exported from Screensteps as a ZIP
3) Files were converted using a PHP file written by Longsight (https://github.com/LongsightGroup/sakai-help-conversion)
# Unzip the Screensteps export
mkdir /tmp/help
cd /tmp/help
unzip export.zip
# Git the code
cd ~/
git clone https://github.com/LongsightGroup/sakai-help-conversion.git
cd sakai-help-conversion
php -q sakai-help-parse.php
# Optimize the PNG images from the export
find /tmp/help/images/ -iname '*.png' -exec optipng -o7 {} \;
find /tmp/help/images/ -name '*.png' -print0 | xargs -0 -P8 pngquant --ext .png --force 64
# Remove empty image directories
find /tmp/help/images/ -empty -type d -delete
# Copy the images into the sourcecode
rsync --delete -vzra /tmp/help/images/ /path/to/source/reference/library/images/help/en/
----------------------------------------------------------------------------------------------------------------------------
Overview:
The Help Tool can have multiple configurations based on institutional requirements.
Some would like to have the generic Sakai help out-of-the-box while others want to provide custom documentation.
Access to help documentation can also be provided from a web service such as REST which uses basic web authentication.
Configuration: Help - Out of the Box
From the Sakai distribution, the help tool will:
1. Deploy all help documents into shared/lib from the /help subdirectory of the help tool.
2. On first access the help tool will enumerate the list of well-known tool id's
a) For each tool id found using the tool manager , replace "." with "-".
b) For each id found, search the classpath for a tool_id/help.xml file
c) Perform a full-text index and register the tool's documents from help.xml
4. The structure of the help.xml is identical to that of Sakai 1.5. The following is an example of
a specific tool's help configuration file:
<?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="adminToolOverview" class="org.sakaiproject.component.app.help.model.ResourceBean">
<property name="docId"><value>arct</value></property>
<property name="name"><value>Admin Tool Overview</value></property>
<property name="location"><value>/sakai_admin_tool/arct.html</value></property>
<property name="defaultForTool"><value>sakai.admin.tool</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="adminToolCategory" class="org.sakaiproject.component.app.help.model.CategoryBean">
<property name="name"><value>Admin Tools</value></property>
<property name="resources">
<list>
<ref bean="adminToolOverview"/>
</list>
</property>
</bean>
</list>
</property>
</bean>
</beans>
Configuration: Help - External Registration
Several institutions requested a feature for external help registration. We have implemented this using a
custom help registration xml file which is required to be accessible on the network from where Sakai runs.
For a simple example, I have created a webapp which has the following structure:
¦ announcementOverview.html
¦ announcementPost.html
¦ help.xml
¦ help.xsd
¦
+---META-INF
¦ MANIFEST.MF
¦
+---sakai_announcements
¦ announcementOverview.html
¦ announcementPost.html
¦
+---WEB-INF
web.xml
The web.xml is simple:
<?xml version="1.0"?>
<web-app id="WebApp_9" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>sakai-help</display-name>
<description>Sakai Help Tool</description>
</web-app>
The help.xml file contains categories and resources organized in a hierarchy which will be reflected in
help tool's table of contents. The following is a simple help.xml configuration file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Help External Configuration -->
<help-reg>
<!-- Announcements -->
<category name="Announcements">
<resource name="Announcements Overview" location="/announcementOverview.html" defaultForTool="sakai.announcements"/>
<resource name="Post Announcement" location="/announcementPost.html"/>
</category>
.
.
.
</help-reg>
The order of the categories in the table of contents will match the order of the categories in the help.xml file.
The resource element requires a name and location for the external help configuration. The 'defaultForTool' attribute
is optional. In this example, the 'Announcements Overview' document will appear when the help icon is clicked in the
announcements tool.
Note: set the help.location property to the web space where the external help configuration file exists.
(In this example help.location=http://localhost:8080/sakai_help)
One advantage to using the external registration is that this implementation supports nested categories in the table
of contents.
Configuration: Help - External Registration using REST
At IU, the REST protocol has been utilized to access the Knowledge Base web service. Similar to the External Registration
configuration of the help tool, the REST configuration uses an external configuration file. Instead of using the optional
location attribute for a resource element, we use the docId attribute to reference a Knowledge Base document:
<help-reg>
<!-- Announcements -->
<category name="Announcements">
<resource name="Announcements Overview" docId="apkh" defaultForTool="sakai.announcements"/>
<resource name="Post Announcement" docId="arbw"/>
</category>
.
.
.
</help-reg>
The document contents will be refreshed if a new request arrives and the document has not been refreshed in the past two
hours. Otherwise, the cached, transformed document will be delivered to the client.
To configure the Help tool using REST, reference the help.xml external configuration file (see External Configuration).
In addition, add the following REST properties to sakai.properties:
#### Rest Configuration ####
[email protected]=REST
[email protected]=user:pass
[email protected]=http://remote.kb.iu.edu/REST/v0.2
[email protected]=sakai21
A username and password can be obtained from the Knowledge base. (Email [email protected])
Configuration: Help - Window Title
The Help tool's window title will be retrieved from the property ui.service in sakai.properties:
ui.service=CTools