Dynamic Help-link: One explaining Wiki page per Alfresco ‘page title’

The Alfresco Help-link points statically at the central ‘help‘ pages hosted by Alfresco.

Often, this is fine. There are installations where Share is supporting a very specific business process, and it can make sense to provide help pages focussed on the application of Share in the context of this business process. This blog post is about how the help link is confugured, and what to change if you need it to point to a specific dynamic location. I chose to put the help pages in Alfresco Share’s Wiki. You can just as easily point to any external wiki you like (MediaWiki, Confluence, …) , as long as you can point to a unique page by the title of the Alfresco Share page you’re on.

The dynamic Help-link in action:

The Help-link in Alfresco’s mechanism

The static link itself is defined in alfresco/classes/share-help-config.xml:

<config evaluator="string-compare" condition="HelpPages">
 <help-pages>
 <share-help>http://docs.alfresco.com/3.4/topic/com.alfresco.Enterprise_3_4_0.doc/topics/sh-uh-welcome.html</share-help>
 <share-tutorial>http://docs.alfresco.com/3.4/topic/com.alfresco.Enterprise_3_4_0.doc/concepts/gs-intro.html</share-tutorial>
 </help-pages>
 </config>

This list of help-pages is read in the header, and defined in alfresco/classes/share-config.xml

Defines what is displayed. The help link points to {share-help}:

<item type="external-link" id="help" icon="">{share-help}</item>

You can enhance the static link by using webscripts. If you want to, you can define it in a uri-template:

<uri-template id="myhelppage">/whatever/webscript/uri/{pageid}</uri-template>

But, many pages have no {pageid} (like for example dashboards)

JavaScript to the rescue

Since the href has an id attribute (with the value “global_x002e_header-user_help-button”), lets make JavaScript responsible for generating the link. Create a JavaScript file (I thought of the meaningful name “help.js”) and put it somewhere in tomcat/webapps/share/js. The content of this file should be:

window.onload = function() {
 var a = document.getElementById("global_x002e_header-user_help-button");

a.onclick = function() {
 var title = document.title;
 if (title.length>17){
   title=title.substring(17,title.length);
 }
 title=title.replace(/ /g,"_");
 window.open("/share/page/site/help/wiki-page?title="+title);
 return false;
}
}

The first 17 characters can be stripped. The typical title is “Alfresco Share » User Dashboard”. The interesting part is “User Dashboard”, therefore I remove the Alfresco Share part, it does not add value tot the pages in the Wiki. Also replace all blanks by an underscore, this is the way Wiki deals with blanks itself.

Next, make sure this js file is included somewhere in the header. The alfresco-template.ftl could be a first choice, but I chose to add it to header.get.head.ftl. Since you override a native Share file, store this customized version in tomcat/shared/classes/alfresco/site-webscripts/org/alfresco/components/header

<script type="text/javascript" src="${page.url.context}/js/help.js"></script>

Reload your webscripts, clear the cache of your webbroser, and reload any Alfresco Share page. The help link should point to the Wiki in the site called “help”. If the page does not exist yet, you will be able to create it.

I chose to ‘hard-code’ the site name, and the url.context. Alternative would be to include the javascript in a Freemarker file, where I could dynamically add the url.context, and get the site name from some configuration. However, it will not be client side cached anymore. And tweaking a JavaScript file is not that complex.

Feel free to point to any other wiki. The url is static apart from the title, so it will work on MediaWiki and all others too.

[update 1 march 2012: added replace blanks regexp, swapped from <@script> to <script>]

Advertisements