Wednesday, May 24, 2006

Writing Strategies for Online Help Document

XOOPS Cube Legacy 2.1 (XC 2.1) has implemented the help viewer in the control panel. $modversion['help'] had been reserved in XOOPS2. But, it isn't used anywhere. In XC 2.1, developers can attach the help document to their module, and users can read those documents on the control panel directly.

How to attach documents

Let's attach the help document to your module. At first, write index file name to $modversion['help']. This file is showed up first, when users click 'help' on the side menu of the control panel. I name it "help.html" this time.

Next, create real "help.html" in language/english. Yes, the help viewer accepts multilingual document. If you want to have French, Spanish and more, create the same file in each languages' directory.

Lastly, let's write documents!

How to link other pages

Help documents are displayed by PHP. It's difficult to link to other pages in help documents by relative address because URL of the help is the address of PHP application page. But, help documents are loaded and displayed by pure Smarty. And, special plugins of Smarty solve some problems about URL. Helpurl is the Smarty modifier that is used in the help viewer only.

To link other pages, write URL as like the following in help documents.


<img src="<{'screenshot01.jpg'|helpimage}>" alt="..." />

How to use image in the document

You can't use images in help documents by the same cause. You should use helpimage that is modifier of Smarty, to solve this problem.

Put image files to language/****/images. The help viewer accepts multilingual image files as well as documents because the capture image includes a character of each languages. Then, write img tag as like the following:

<a href="<{'page2.html'|helpurl}>">The detail of functions</a>

If the image file doesn't exist in the language directory that user specified, the modifier tries to get the default image file from english directory. So, you don't need to create a lot of image files to all languages.


We plan to prepare special CSS for help. Developers should follow that CSS. The look of current help viewer hasn't adjusted. Designers will adjust CSS to be cool, and publish the rule in XC 2.1 Alpha 4.

No comments: