Freitag, 27. April 2012

Eclipse User Help in your Xtext Hover

If you implemented your own language using Xtext and even documented all of its features in the eclipse user help you might want to show part of these information in your Xtext Hovers, too. This is more convenient to the users, since they don't have to search the whole user guide for the piece of information they are interesed in. 

Note:  This is not a post about how to implement Xtext hovers, Christian Dietrich wrote an excellent blog post on this topic called hover support in xtext 2.0.

The first thing you have to do is to register a context in your contexts.xml of your help plugin:

<context id="GeneratorContext" title="Code Generator Help">
     <topic href="help/user/CodeGenerators/generators.html" 
       label="Code Generator Help" />

In your MyDslEObjectDocumentationProvider, you can access the Eclipse Help Context using some classes of the plugin, which are unfortunately not public API. It makes sense to add some kind of caching, because this method is called every time a hover gets visible.

public class MyDslDocumentationProvider { 
 public String getDocumentation(EObject o) {
    //Parse the help topic
    ContextFileProvider provider = new ContextFileProvider();
    IContext context = provider.getContext("GeneratorContext",
    IHelpResource[] relatedTopics = context.getRelatedTopics();
    // We assume that there is only one topic registered
    IHelpResource helpResource = relatedTopics[0];
    String href = helpResource.getHref().substring(1);
    URL url = new URL("platform:/plugin/" + href);
    return toString(url.openConnection().getInputStream());

If you do not have a seperate html file for each proposal option,  you have to cut the relevant part out if it. I did this by placing html comments in my user guide, like <!-- Start  feature_outlet--> and <!-- End  feature_outlet-->. The identifier can be derived by the name of the context EObject.