Help Content

From Apache OpenOffice Wiki
Jump to: navigation, search



Starting with OpenOffice.org 2.4 extensions can contain help content and extend the Apache OpenOffice's installed help content. The feature supports:

  • Adding extension related help pages
  • Extending the help index to refer to these pages
  • Extended tool tips in UNO dialogs and menus
  • Accessing extension help content by pressing  F1  in UNO dialogs and menus.

Extension help format

The help content is located in a folder inside the extension oxt file. Usually the folder will be named “help”, but any other name can be used as long as it's assigned to the media type "application/vnd.sun.star.help" in /META-INF/manifest.xml. In this chapter the help folder name will always be “help” and all descriptions refer to the SDK sample extension DialogWithHelp.oxt developed by the fictional “Foo Corporation”.

Inside the help folder there's one folder for each supported language. The folders are named according to the common language codes en, de, fr etc. as they are also used inside the Apache OpenOffice help folder. Inside each language folder there has to be another folder named like the extension identifier that has to be specified in the /description.xml file for each extension. As the identifier will be encoded to be used as folder name it's recommended to follow the naming scheme described in the Developers Guide Extension Identifiers,

e.g. “com.foocorp.foo-ext” to avoid differences between identifier and encoded identifier.

The identifier is part of the path to access the extension help files. The reason for this rule is to get an unique path to each help file inside the extension: a path that cannot clash with paths to help files in the installed help or in other extensions. Unfortunately – due to the design of the extension manager, the help sub package has no access to its parent package bundle – it's not possible to check at help compile time (see Deployment) if this identifier rule is violated and so no error message will be shown in this case. Nevertheless, help pages inside “illegal” folders will be suppressed at runtime, so the extension author should detect the problem when testing the extension. If a help package is not part of a parent bundle package, the identifier rule does not apply.

The following tree shows the structure of the DialogWithHelp.oxt help folder containing the languages en and de with three help pages each, one of those in a sub folder. The file / folder structure for all languages should be same, e.g. to make bookmarks pointing to extension help pages the same for all languages.

The help content will be compiled for all language when the extension is deployed. At runtime the help system tries to find the same language inside the extensions' help content that is also used to access the installed help. In case the extension's help doesn't support this language, the help system will always try to find English (en) help inside the extension and use this as a fallback.


Example:

DialogWithHelp.oxt
 │
 ├─ DialogWithHelp
 │   │
 │   └─ ... Dialog Library
 │
 ├─ META-INF
 │   │
 │   └─ manifest.xml (assigning “help” folder to media type
 │                    "application/vnd.sun.star.help")
 ├─ help
 │   │
 │   ├─ en
 │   │   │
 │   │   └─ com.foocorp.foo-ext
 │   │       │
 │   │       ├─ page1.xhp  
 │   │       │
 │   │       ├─ page2.xhp  
 │   │       │
 │   │       └─ subfolder  
 │   │           │
 │   │           └─ anotherpage.xhp  
 │   │
 │   └─ de
 │       │
 │       └─ com.foocorp.foo-ext
 │           │
 │           ├─ page1.xhp  
 │           │
 │           ├─ page2.xhp  
 │           │
 │           └─ subfolder  
 │               │
 │               └─ anotherpage.xhp  
 │    
 ├─ Addons.xcu (Menu/Toolbar specification)
 │
 └─ description.xml (contains identifier)

Deployment

Extension help content is deployed like any other extension content using the OpenOffice Extension Manager or the unopkg command line tool, usually as sub package inside a package bundle. All help files are detected automatically during extension deployment, no additional configuration file is needed to list them. The help files are compiled then similar to the installed help content being compiled during the OpenOffice.org build process. The compile process itself doesn't differ from the one in helpcontent2, but instead of referring to the main OpenOffice.org help modules like Writer, Calc etc. each extension is handled as its own small module.

All Help Compiler output is created inside the extension's cache folder. So it's guaranteed that all help content will be removed together with the extension. Help content of disabled extensions is ignored. Due to caching mechanisms used by the HelpProvider implementation changes in the extension state may not be visible before the next start of OpenOffice.

Error handling

During the deployment the extension's help files are compiled. If an error is found during compilation – usually this will be a XML parsing error - a corresponding error message will be displayed. End users shouldn't be affected by these errors as the extension developer should fix all problems before releasing the extension.

Only the first line of the error message is localized. It's followed by details in English directly using the error information provided by the Help Compiler respectively the XML parser. The following lines show an example for a XML parsing error. The first line is a localized string, the following lines are always in English.

The extension will not be installed because an error occurred in the help files:
attributes construct error in file:///D:/OOo24/user_data/uno_packages/cache/uno_packages/15A7.tmp
/DialogWithHelp.oxt/en/com.foocorp.foo-ext/page1.xhp, line 49

Integration into the OpenOffice help system

There are different ways to access extension help content respectively to integrate it into the installed help content.

Help module list box

Extensions don't have its own help module, neither as single extension nor for all extensions together. So the help module list box won't be affected by extension help content.

Help Viewer Contents page

Adding content to the Contents tree is supported from OpenOffice.org version 3.0.0. See specification http://specs.openoffice.org/appwide/help/ExtensibleHelp.odt

Help Viewer Index page

Adding index entries can be done in the same way as it's done in the installed help files (see File format). There's a difference concerning the way the index entries are assigned to the different help modules. In the OpenOffice.org installed help this is handled via the help file path. As extension help shouldn't be forced to use the same file naming scheme, instead a bookmark naming scheme is used here. The following example shows a bookmark defining an index entry (branch=”index”) visible for all modules:

<bookmark xml-lang="en-US" branch="index" id="bm_foo001">
<bookmark_value>foo This is a single level entry</bookmark_value>
<bookmark_value>foo first level;second level</bookmark_value>
</bookmark>

If the index entries should only be visible for (a) special module(s) the module(s) it should be visible in can be added to the bookmark id using _ as separator, examples:

<bookmark xml-lang="en-US" branch="index" id="bm_foo001_swriter">
...

will make all following bookmark_value entries only visible in the Writer index.

<bookmark xml-lang="en-US" branch="index" id="bm_foo001_scalc_sdraw">
...

will make all following bookmark_value entries only visible in Calc and Draw index.

The module names to be used here are the same as in the installed help:

sbasic, scalc. schart, sdatabase, sdraw, simpress, smath, swriter.

Help Viewer Find page

Starting with OpenOffice.org 3.1 full text search is also supported for extension help. The extension developer doesn't have to care about this. During extension installation a help index will be created automatically. Search results found inside the extension help will be shown together with the results found in the Apache OpenOffice help files ordered according to their score.

Help Viewer Bookmarks page

Bookmarks to extension help pages can be added. When the corresponding package is disabled or removed later the bookmark will not automatically be removed.

Context sensitive help and extended tool tips

Context sensitive help is based on Help Ids that are assigned to toolbar items, menu items and UNO Dialogs / Dialog controls. Toolbar and menu items do specify a Command URL to bind the item to an action to be taken when the item is executed. It's important to choose a unique Command URL, e.g. by following a similar scheme like for the extension identifier or to refer to a service implementing the functionality. Example Command URL: com.foocorp.foo:DoTheFooAction

This Command URL is also used as Help Id, both for extended tool tips as for assigning a help page to F1. Defining help Ids in xhp files is also done with the bookmark element (see File Format):

<bookmark xml-lang="en-US" branch="hid/com.foocorp.foo:DoTheFooAction" id="bm_foo02" localize="false"/>
<paragraph role="paragraph" id="hd_id4711" xml-lang="en-US"><ahelp hid="com.foocorp.foo:DoTheFooAction" visibility="hidden">This is the extended tool tip for DoTheFooAction</ahelp></paragraph>
<paragraph role="paragraph" id="hd_id4712" xml-lang="en-US">This is the help Text for DoTheFooAction. … </paragraph>

The Command URL has to be used both for the branch value after hid/ and in the ahelp / hid value.

In the same way bookmarks can be bound to Dialogs / Controls created with the OpenOffice Dialog Editor. The user just has to assign a unique Help Id to a Dialog's or Control's Help URL property and define a corresponding bookmark as shown above. If a control has the focus, its Help URL has priority about the Dialog Help URL.

Links

Links to extension help pages are defined in the same way as in the Apache OpenOffice help, only the path differs. Example:

<link href="com.foocorp.foo-ext/subfolder/anotherpage.xhp">Link to foo</link>

Images

Starting with OOo 3.1 extension help can provide own pictures. In the Apache OpenOffice help image tags always refer to a set of images distributed with the office product in the images.zip file. The following help image tag addresses an icon located there:

<image id="img_id0001" src="res/commandimagelist/sc_paralefttoright.png"
width="0.222inch" height="0.222inch">

The width / height attributes are optional. The width and height attributes are currently (year 2009) ignored by the help system.

Tags like this of course also can be used in extension help files (even before OOo 3.1). To address an image inside the extension's help the src path has to start with the extension's id. So this will show the image located inside the extension's help at foo.oxt/help/en/com.foocorp.foo-ext/foo.png:

<image id="img_id0002" src="com.foocorp.foo-ext/foo.png"></image>

Images can also be placed in subfolders:

<image id="img_id0003" src="com.foocorp.foo-ext/subfolder/foo2.png"></image>

A consequence of this location is that you need to store an image for each language of help.

Images can be placed anywhere inside the extension package, not necessarily inside the extension's help tree. With another location, if the same image is used for different languages the help files will reference the same image file. In this example the image foo3.png is in the folder Images of the extension package.

<image id="img_id0004" src="com.foocorp.foo-ext/../../../Images/foo3.png"></image>

File Format

The extension help content uses the XML based xhp file format that is also used for the Apache OpenOffice installed help. A description can be found here:

http://documentation.openoffice.org/online_help/OOo2HelpAuthoring.pdf

Paths start with the Identifier folder inside the language folder. This is also reflected in the xhp files' <filename> tag, example:

<helpdocument version="1.0">
...
<filename>/com.foocorp.foo-ext/page1.xhp</filename>
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages