The Help Content Provider

Currently, the Help Content Provider has the following responsibilities:

It is the interface to a search engine that allows a full-text search, including searching specific scopes, such as headers. The range of accessible scopes depends on the indexing process and is currently not changeable after setup.
It delivers a keyword index to its clients.
The actual helpcontent has media type "text/html," with some images of type "image/gif" embedded. The content is generated from packed xml files that have to be transformed according to a xsl-transformation to produce the resulting XHTML. There is a cascading style sheet used for formatting the XHTML files of media type "text/css".
It provides its clients the modules for which help is available.

Help Content Provider Contents

The responsibilities mentioned above are fulfilled by providing different kinds of content objects to the client, namely:

a root content giving general information about the installed help files
a module content serving as the interface to all search functionality
picture and XHTML Contents providing the actual content of the transformed help files and pictures

These contents are described below.

URL Scheme for Help Contents

Each Help content has an identifier corresponding to the following scheme:

 URL ::=          scheme delimiter path? query? anchor?
 scheme ::=       "vnd.sun.star.help"
 delimiter ::=    "://" | ":/"
 path ::=         module ( "/" id )?
 query ::=        "?" key-value-list?
 keyvaluelist ::= keyvalue ( "&" keyvalue )?
 keyvalue ::=     key "=" value
 anchor ::=       "#" anchor-name

Currently, to have a fault-tolerant system, some enveloping set of this is allowed, but without carrying more information.

Examples:

vnd.sun.star.help://?System=WIN&Language=de

vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=Heading

vnd.sun.star.help://portal/4711?System=UNIX&Language=en^_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal

Some information must be given in every URL, namely the value of the keys "System"/"Language."

"System" may be one of "UNIX," "WIN," "OS2" and "MAC". This key parameterizes the XSL transformation applied to the help filesand their content changes according to this parameter, and is mandatory only for helpcontents delivering XHTML-files. This may change in the future.

"Language" is coded as ISO639 language code, optionally followed by "-" and ISO3166 country code. Only the language code part of "Language" is used and directly determines the directory, which is relative to the installation path where the help files are found.

In the following, the term "help-directory" is used to determine the directory named "help" in the office/portal installation. The term "help-installation-directory" is used to denote the particular language-dependent subdirectory of the help-directory that contains the actual help files as a packed jar file, the index, the config files and some other items not directly used by the help content provider.

Properties and Commands

Every creatable content can execute the following commands. It is not constrained to a particular URL-scheme:

 com::sun::star::ucb::XCommandInfo getCommandInfo()
 com::sun::star::beans::XPropertySetInfo getPropertySetInfo()
 com::sun::star::sdbc::XRow getPropertyValues([in] sequence< com::sun::star::beans::Property > )
 void setPropertyValues([in] sequence< com::sun::star::beans::PropertyValue > )

These commands repeat the information given in the following. The available properties and commands are explained by the following URL examples:

Root Content

vnd.sun.star.help://?System=WIN&Language=de

Properties:

Name	Type	value
'Title'	string	"root"
'IsFolder'	boolean	true
'IsDocument'	boolean	true
'ContentType'	string	"application/vnd.sun.star.help"
'MediaType'	string	"text/css"

Commands:

Return Type	Name	Argument Type
XDynamicResultSet	open¹	OpenCommandArgument2

¹ Return value of this command contains the modules available in the particular installation for the requested language. The modules are currently determined by looking for the files in the help-installation-directory matching "*.db", with the exception of the file "picture.db".

Generally, a module corresponds to a particular application, namely, if the writer application is installed, there should be a module "vnd.sun.star.help://swriter" and so forth.

The written XOutputStream or the set XInputStream (set at XActiveDataSink) makes the cascading style sheet available, which is used to format the XHTML files. Physically, the stream contains the content of the file custom.css in the help-directory of the office or portal installation.

Only the key "Language" is used. Any other key may be set, but is ignored.

Module Content

vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=Heading

Properties:

Name	Type	value
Title	string	determined from config file in help-installation-directory
IsFolder	boolean	true
IsDocument	boolean	false
ContentType	string	"application/vnd.sun.star.help"
KeyWordList	sequence< string >	(See below)
KeyWordRef	sequence< sequence < string > >	(See below)
KeyWordAnchorForRef	sequence< sequence < string > >	(See below)
KeyWordTitleForRef	sequence< sequence < string > >	(See below)
SearchScopes	sequence< string >	(See below)

The help files contain specially marked keywords. The alphabetically sorted list of keywords is contained in the property KeywordList.

For example, you are looking for keyword KeywordList[i], where i is an integer. The help module in which this keyword should be found is determined by the module part of the content URL, "swriter" in our example. Now KeywordRef[i] contains a list of document ids, where the document belonging to that id contains the keyword string "docid = KeywordRef[i][j]".

The location in the XHTML document where this particular keyword refers to is marked by an HTML anchor element:

 <A name="anchor"/>

Here the anchor is given by the string "anchor = KeywordAnchorForRef[i][j]".

For our example, the URL of the j document in the swriter module containing the keyword Keyword[i] is determined as vnd.sun.star.help://swriter/docid?System=WIN&Language=de#anchor.

The keys "HitCount", "Query" and "Scope" have no value with regards to the keywords.

The title of the resulting document is determined directly without having to instantiate the content by the value of "KeywordTitleForRef[i][j]".

The module contents are also the interface to the search engine. A number of additional keys in the URL are necessary, namely the keys:

HitCount
Query
Scope

The value of Scope should be one of the strings given by the property SearchScopes, currently "Heading" or "FullText". Leaving the key undefined defaults to a full-text search, Setting it to "Heading" means to search in only the document titles.

There may be any number of Query key definitions in the URL. Many Query keys determine a query search, first for documents containing all the values, then searching for those containing only subsets of all the values. The requested number of results is determined by the value of the key HitCount. The actual returned number may be smaller. The interface to the results returned by the search engine is given by an com.sun.star.ucb.XDynamicResultSet, which is the return value of the command "open":

Return Type	Name	Argument Type
XDynamicResultSet	open	OpenCommandArgument2

XHTML Content or Picture Content

vnd.sun.star.help://portal/4711?System=UNIX&Language=en^_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal%2F

Properties:

Name	Type	value
Title	string	determined from database
IsFolder	boolean	false
IsDocument	boolean	true
ContentType	string	"application/vnd.sun.star.help"
MediaType¹	string	"text/html" or "image/gif"

¹ The MediaType "image/gif" corresponds to a URL which contains a module part "picture", as opposed to "portal" in the example.

Commands:

Return Type	Name	Argument Type
void	"open"¹	OpenCommandArgument2

¹ Returns the transformed XHTML-content, or the gif-content of a PictureContent.

There is one special document for every module, namely those named start (replace 4711 by start in our example). It identifies the main help page for every module.

There is an additional key named HelpPrefix. If set, every link in a generated document pointing to another help-document, either XHTML or image document, is first encoded and then prefixed by the URL-decoded form of the value of this key. This key is only used by Sun One Webtop.

Content on this page is licensed under the Public Documentation License (PDL).

The Help Content Provider

Help Content Provider Contents

URL Scheme for Help Contents

Properties and Commands

Root Content

Module Content

XHTML Content or Picture Content

Views

Personal tools

Navigation

Search

Tools

In other languages