The Help Content Provider
Preface
Currently, the Help Content Provider has the following responsibilities:
It is the interface to a search engine, which allows fulltext search and searching in more specific scopes like 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.
Minor: It gives its clients the modules, for which help is available.
The actual help content has media type "text/html", with some images of type "image/gif" embedded. The content is generated on the fly from packed xml-files, which 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".
Provided content
The above mentioned responsibilities 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, and Picture Contents and XHTML Contents, providing the actual content of the transformed help files and pictures. These contents are more specifically described below.
URL - scheme
The interface of the Help Content Provider is the usual one:
One has to create a (X)ContentIdentifier from an URL in string form, and in turn a (X)Content with the help of the (X)ContentIdentifier. This (X)Content object has various properties and is able to execute a number of named commands, both listings dependent from the URL.
The URL string encodes in a rather obvious way the information about the requested content and should have the following form ( given as a regular expression ):
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 // See below for optional and mandatory keys and values
anchor = "#" anchor-name
Currently, to have a more 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 should/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 parametrizes the xsl-transformation applied to the help-files ( 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 determines directly the directory, where relative to the installation path 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, which contains the actual help-files as a packed jar-file, the index, configuration files and some other stuff not directly used by the help content provider.
Properties and Commands
Every content is able to execute the following commands ( not constrained to a particular URL-scheme )
com::sun::star::ucb::XCommandInfo getCommandInfo( void )
com::sun::star::beans::XPropertySetInfo getPropertySetInfo( void )
com::sun::star::sdbc::XRow getPropertyValues( sequence< com::sun::star::beans::Property > )
void setPropertyValues( sequence< com::sun::star::beans::PropertyValue > )
These commands mainly repeat the information given in the following.
It is most appropriate to explain for the given URL-examples the available properties and commands:
A: Root Content
Sample URL: vnd.sun.star.help://?System=WIN&Language=de
Properties:
Title string "root"
IsFolder boolean true
IsDocument boolean true
ContentType string "application/vnd.sun.star.help"
MediaType string "text/css"
Commands:
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" ). Quite 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 on.
The written XOutputStream, or the set XInputStream ( set at XActiveDataSink ) make the cascading style sheet available, used to format the XHTML-files. Physically, the stream contains the content of the file "custom.css" in the help-directory of the office/portal-installation.
Only the key "Language" is used, any other key may be set, but is ignored.
B: Module Content
Sample URL: vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=Heading
Properties:
Title string determined from configuration file in help-installation-directory
IsFolder boolean true
IsDocument boolean false
ContentType string "application/vnd.sun.star.help"
KeywordList sequence< string >
KeywordRef sequence< sequence< string > >
KeywordAnchorForRef sequence< sequence< string > >
KeywordTitleForRef sequence< sequence< string > >
SearchScopes sequence< string >
The help files contain specially marked key-words. The alphabetically sorted list of key-words is contained in the property "KeywordList".
Suppose now you are looking for key-word "KeywordList[i]", where "i" is an integer. The help-module, in which this key-word 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 key-word: string docid = KeywordRef[i][j]; The place in the XHTML-document, to which this particular key-word refers, is marked by an html-anchor-element: <A name="anchor"/> Here "anchor" is given by string anchor = KeywordAnchorForRef[i][j].
So, for our example, the URL of the j document in the swriter-module containing the key-word Keyword[i] can be determined as vnd.sun.star.help://swriter/docid?System=WIN&Language=de#anchor The value of keys "HitCount", "Query" and key "Scope" are unimportant with regards to the key-words. Finally, the title of the resulting document can be 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. To this end a number of additional keys in the URL are necessary, namely the keys
"HitCount", "Query" and "Scope". The value of "Scope" should be one of the strings given by the property "SearchScopes", currently either "Heading" or "FullText". Leaving the key undefined defaults to fulltext-search, setting it to "Heading" means search in document titles only. There may be any number of "Query"-key definitions in the URL. Many "Query"-keys determine a query searching first for documents containing all values, than searching for those containing only subsets of all 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 XDynamicResultSet, which in turn is return value of
Commands:
XDynamicResultSet open( OpenCommandArgument2 ),
C: XHTML Contents, Picture Contents
Sample URL: vnd.sun.star.help://portal/4711?System=UNIX&Language=en_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal%2F
Properties:
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 an URL, which contains as module part "picture" ( as opposed to "portal" in the example ).
Commands:
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 xhmtl- 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 OneWebtop.
