| Anchor/linkTo fails with custom TocProvider [message #592711] |
Wed, 31 October 2007 00:37 |
Eclipse User |
|
|
|
Originally posted by: bwhite.skywaysoftware.com
I have subclassed AbstractTocProvider and have managed to create a working
TocProvider that converts RoboHelp ToC files "on the fly" and contributes
them to the Help system.
[Definition: Toc = Table of Contents]
There are three ways to contribute a ToC:
1. As a primary (or top-level) topic.
2. By pulling the Toc into another Toc underneath some other primary topic.
This works by embedding a <link> element in the parent Toc to pull the
nested Toc into the tree. The <link> element references the <id> element of
the nested Toc.
3. By pushing the nested Toc into another Toc underneath some other primary
topic. This works by embedding an <anchor> element in the parent Toc. Then
the nested Toc refers to the "id" attribute of that anchor element inside
its "linkTo" attribute.
My project works so long as I use internal eclipse classes:
org.eclipse.help.internal.toc.TocContribution and
org.eclipse.help.internal.toc.Toc.
I tried to eliminate this discouraged access and uncovered a failure. I
rewrote my project using only the public interfaces: specifically
ITocContribution, IToc and ITopic. After doing so, I discovered that the
anchor/linkTo feature no longer worked.
The reason is that the user-contributed ITocContribution objects returned by
the implementation of AbstractTocProvider's getTocContributions() method are
actually discarded by its caller,
org.eclipse.help.internal.TocManager.getTocContributions(). This method
creates a new instance of the internal class TocContribution and copies
almost all of the information from the user-contributed ITocContributions.
If it were to copy all of the information before discarding the
user-contributed ITocContribution object, the anchor/linkTo feature would
continue to work, but alas it does not. For some reason, the getLinkTo()
method of ITocContribution is not called. I presume this is because they
are copying the embedded IToc object and they probably assume that this
embedded IToc object is actually an instance of an internal Toc. If it is
not, they construct a Toc and copy the contents of the IToc into it.
Unfortunately, IToc does not have a getLinkTo() method.
Moreover, the way AbstractTocProvider actually works, it is more likely that
the linkTo path is an attribute of the ITocContribution. At least, that is
how I implemented my project. I implemented an extension point that accepts
all of the attributes that a TocProvider needs to describe an
ITocContribution ("linkTo", "contributorId", "id", "isPrimary", "locale",
etc).
Be that as it may, the way TocManager.getTocContributions() is currently
written and given the absence of a getLinkTo() method on the IToc interface,
the only way to get the anchor feature to work is to actually embed an
org.eclipse.help.internal.toc.Toc object in the ITocContribution and make
sure that its linkTo field gets set properly. This Toc object has to be
returned by the getToc() method of the ITocContribution. If one does this,
then the linkTo path will be preserved by TocManager.getTocContributions().
As I said at the beginning, I have a working version of this project and my
company is preparing to open source it for those who would like to see an
example of a working TocProvider. This would be of special interest to
those who want to use RoboHelp to build their eclipse html Help files, but
do not like manually transforming the toc file each time. BTW, we also have
an XSLT transform that will do this, but clearly the TocProvider is more
convenient.
Contact http://www.skywaysoftware.com for more info.
|
|
|
Powered by
FUDForum. Page generated in 0.03636 seconds
] 
Search
Help
Register
Login
Home
