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 | open1 | OpenCommandArgument2 |
1 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" |
MediaType1 | string | "text/html" or "image/gif" |
1 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"1 | OpenCommandArgument2 |
1 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). |