Community
Participate
Working Groups
It will be nice to be able to change the TOC image that gets displayed. It could be implemented something like: <topic label="My Topic" href="someFolder/mytoc.html" image="icon/newTOC_Image.gif"/> of course they will have to be some kind of restriction in terms of how big the image can be. This is how the dtd would look like: <!ELEMENT toc (topic | anchor | link)* > <!ATTLIST toc link_to CDATA #IMPLIED > <!ATTLIST toc label CDATA #REQUIRED > <!ELEMENT topic (topic | anchor | link )* > <!ATTLIST topic label CDATA #REQUIRED > <!ATTLIST topic href CDATA #IMPLIED > <!ATTLIST topic image CDATA #IMPLIED> <------ this would be *NEW* <!ELEMENT anchor EMPTY > <!ATTLIST anchor id ID #REQUIRED > <!ELEMENT link EMPTY > <!ATTLIST link toc CDATA #REQUIRED >
Keep in mind that TOC's can be assembled under other TOC's, so their icon won't be visible anymore. You're right about specifying certain characteristics for images (size, etc.) If any plugin defines different images for their TOC's, the help presentation may look less integrated (too many image styles), but if that's desireable, the requirement is valid.
There is a slightly conflicting requirement to support different icons for different topic types (different icon for a different mime type). We will look at a solution in a future release.
I (FAQplugin) am intersted in this feature.
*** Bug 45498 has been marked as a duplicate of this bug. ***
Marking as P4 - unlikely to be looked at for 3.1.
The Rational products are moving the samples and tutorials into the online help. We would like to differentiate these from all the other online content using icons. We would like to add an icon="image.gif" attribute to our TOC elements.
This enhancement has been open for a long time. Can we have a plan as to when will this be considered..?
I think that this is a good idea, the only thing holding us back from implementing it is limited engineering resources. If anyone is interested in working on contributing this I can give some guidance on how the javascript in the Webapp sets the icons. Because the image is displayed in the help view, the webapp and search results there's a fair amount of work required to implement this.
Targeting Eclipse 3.5 Here are my thoughts on the design of this feature. In addition to defining an icon the user will want the ability to also specify a tooltip for that icon. He may also want to have different icons for open and closed books. There are two possible ways that we could extend the syntax of the toc to allow for images. One is to add an attribute such as icon="/plugin_name/path/MyImage.gif" and tooltip="Tooltip image text" to each topic with a nonstandard image. Another way is to add an extension point which declares an icon and having done that use the id of the extension point in the toc entry, such as icon="org.eclipse.someproject.myicon.gif". I feel that the extension point will work better in practice because it allows the tooltip to be defined in one easy to localize place. The extension point would define an icon id, the path of the image, optionally the path of the "closed book" version of the image and a tooltip. The tooltip would be localized the same way as any other property in plugin.xml. The icons can appear in the help view and in the webapp. The help view should not be too difficult to handle, we just need to make sure that we put the images in the image registry so they are shared. The webapp is a little tricker - the image management takes place in tocTree.js, setImage(). The webapp recieves toc data from the help system in the form of xml. We can add more attributes to the xml for the tooltip and image and then modify the javascript accordingly. One decision to make is whether we need to support a second image for nodes so that open and closed books or topics look different. This does not seem to be too difficult to do and I would suggest that while we are implementing this feature we go ahead and do this. For remote help I would suggest that the only custom images supported are those which are installed locally. If an icon attribute in a topic refers to an unregistered icon extension we just use the default icons.
Thanks for the update. I like the extension point id, I feel it is a little loose which I am not too keen on.. but I like the possibility of adding a close and open images. Not something that I was looking for, but I think is better for usability :)
Can you explain what you mean by "a little loose"?
1. Is it possible to set this up so that you could define your icons/tooltip in one plug-in and use the associated ID on TOCs in other plug-ins? This is probably how we'd like to use it: set up a set of icons in the same place we set up our common CSS and scripts, and then have writers of the various doc plug-ins point to those centrally defined icons. in com.myco.all.doc/plugin.xml define 6 icons for product doc plug-ins to use: iconA (open/closed/tooltip) through iconF in com.myco.productA.doc/toc.xml ...<topic icon="com.myco.all.doc.iconA" href="topic.html" label="My A topic" /> 2. These icons should appear in search results lists, too, beside the corresponging hit link.
The extension point mechanism would allow you to specify the icon and tooltip in one plugin then reference those from any other plugin. Adding the icon to the search results seems like a nice idea but would add more work because the search index does not contain a link back to the topic, so you would haev to search the tocs for the URL.
By "little loose", I mean that anyone who wants to add the image would have to extend the new extension point aside from the topic and this allows for exactly that Kary described in comment #12 point 1, but if that is a requirement for other adopters then what you described makes sense. And my comments below are useless :). But for the purpose of completeness, I will enhance the description of "a little loose" In my case I am a java developer and extension developer and adopter, so I don't have a lot of problems debugging extension points as I can read them and step through the java code if need be. But is often the case that people who write the help documentation are more very skilled in writting good, and readable technical documents and not necessarily in debugging java code or extensions or plugin loading issues to find where the problem originates. Think of the scenario when an image doesn't show in the tree because the id of an "icon=" is misspelled with "com.myco.al1.doc.iconA" (notice the '1' instead of a 'l' or something similar like letter that are close together in the keyboard 'l' and 'i'). To you and I, it might sound like something obvious to debug but with a loose scenario where there is an extension point that is referenced by the toc, it gives for more points of failure more complicated logic to find the source of an image not showing in the tree. Some of the question that originate from such a loose config can be: 1. which topoic id is failing? 2. is the toc declaration correct? 3. is the extension point id correct in the toc? 4. where is the extension point of the icon? 6. is the 'topic icon=' matching the extension point id? (in a case "com.myco.al1.doc.iconA" it would be some what difficult to find) 7. is the path correct in the icon extension point? 8. is my image file there? 9. is the plugin of my icon extension loaded? In a scenario where the image is referenced right at the topic (like the one I described at the begging of this bug) there is only a few questions to ask: 1. which toc id is failing? 2. is the toc declaration correct? 3. is the path correct? 4. is my image file there?
Angel, I think you're underestimating the skill of the average UA person. :) We work with these kind of things all the time in Eclipse and the other tools we use. And some of us (I can't speak for every Eclipse-targeting tech writer out there) also have highly technical infrastructure teams full of "real" programmers backing us up. Oversimplifying the enhancement to the point that it's not useful to enterprise level user assistance is not the answer. In fact, implementing it with a central icon-declaration point will mean that a TOC-generating tool or XSL can apply the correct IDs (reducing errors further) and the centralized declaration can be managed by someone with higher levels of Eclipse skill. Your "average" writer might not be affected at all.
Kari, Thanks for the clarification. The point was more of a concern on a trend that I have been seeing to often, now. I as a plugin developer sometimes wonder if we are creating too many extension points? when at times we can add to the current extension point or think of different ways of implementing the same function in other ways. The point is more of a general concern that I am trying to get people to start thinking on. We as eclipse developers, are just madly creating extension points because is so easy and we know how to load them and use them, without perhaps thinking twice about them. My intention was that of giving it a second thought if we really needed to create an extension point for this function. Perhaps the function can be implemented in a different way. But that might not apply in here because the requirements that you stated in comment #12.
I'm not sure that I can address the broader question of whether there are too many extension points in Eclipse but in this case there are two major benefits which come from using extension points which we would not get from using attributes. One is the ability to specifiy the tooltip for an icon in exactly one place where we already have a well defined mechanism for localization. The other is for remote help - it is not practical for the icons to come from the remote server and extension points provide a good mechanism which allows the host installation to install the icon providing plug-ins so that remote content can still use those icons.
Chris, Agreed.
Created attachment 111532 [details] org.eclipse.help plug-in extension point addition
Created attachment 111534 [details] org.eclipse.help.ui plug-in dynamic help view patch
Created attachment 111535 [details] Usage example
Per Chris' suggestion, I implemented the extension point approach and applied it to the Eclipse client dynamic help view. Below are details of the implementation and proposed patches: How to declare an icon using the extension point "org.eclipse.help.toc": (1) Create a plug-in that declares a contribution to the extension point "org.eclipse.help.toc" (2) Add the configuration element "tocIcon" to the extension point and define its attributes: id, openIcon, closedIcon, and leafIcon. Note: id and openIcon are required attributes, the rest are optional. Usage example: <extension point="org.eclipse.help.toc"> <tocIcon id=some_id openIcon=path/to/open/icon closedIcon=path/to/closed/icon leafIcon=path/to/leaf/icon /> </extension> How to define icons in a document : You can use icons defined with the extension point above in the table of contents and topics of documents. To use a custom icon, add the "iconId" attribute to the <toc> or <topic> element of the document. For example: <toc label="Toc label" topic="some/topic.html" iconId="some_id"> <topic label="Topic label" iconId="some_id"> The icon will be displayed in the Eclipse client Dynamic help view with the following rules: - If iconId, openIcon and closedId are defined, their icons will be shown in the table of content tree according to the state of the tree: expanded or closed. - If only iconId and openIcon are defined, the same icon will be displayed in the tree table of content indenpendent of the state of the tree. - If leafIcon is defined, the desired icon will be shown only if a Topic does not contain any children. - If no icon is defined or found, the default Eclipse icons for Toc and Topics are used. Attached are patches to org.eclipse.help, and org.eclipse.help.ui as well as two project plug-ins used for usage example: org.eclipse.toc.icon.contributor and org.eclipse.toc.icon.test.doc. The first is a plug-in that declares the <tocIcon> element, and the second is a test doc that uses the declared icons. Patches: https://bugs.eclipse.org/bugs/attachment.cgi?id=111532 https://bugs.eclipse.org/bugs/attachment.cgi?id=111534 Example: https://bugs.eclipse.org/bugs/attachment.cgi?id=111535
Created attachment 111744 [details] Updated Patch I have made some changes including: The extension point has the icons defined as resources, not strings I moved the icon lookup code to HelpUIResource I added some tests I have commited this patch + one new icon in the org.eclipse.ua.tests
Created attachment 114802 [details] Icon contribution to help webapp This patch contributes changes to the org.eclipse.help.webapp for the use of contributed toc icons. The patch also adds the attribute "tooltip" to the configuration element tocIcon in the org.eclipse.help.toc extension point.
Comment on attachment 111534 [details] org.eclipse.help.ui plug-in dynamic help view patch Setting iplog flag for Attachment 111534 [details], which after I made some modifications was committed,
Comment on attachment 114802 [details] Icon contribution to help webapp Attachment 114802 [details] committed with minor modifications
I just added a few JUnit tests and revised the code for the alt text a little. This is now complete, marking as FIXED.
