samedi 12 janvier 2013

Leveraging NetBeans completion for XHTML


The Story

This, started in december 2012 when Geertjan blogged about an article of mine.

This article, written in French, explained how one can build a completion on lang attribute in XHTML files for NetBeans 7.2.1.

As I stated in my article, some principles and code I used were quite generic enough to be used in other completion use cases.

Geertjan took my code and add a very important thing : annotations on top of it.

I pushed my code and Geertjan's idea to a higher level and here we are !


The Proof Of Concept

This new NetBeans POC API  is about using annotations to register completions on XHTML content.

A developer only need to focus on his completion need and has little to know about NetBeans APIs he should deal with if this new API did not exist.

The API code and some samples are on github.

It's only a proof of concept : I don't really know if this work should or should not be integrated in THE NetBeans official API.

All I can tell is this is far much easy to build an XHTML completion module with it than without it.

Plus, some principles could be used to leverage other NetBeans API like Hyperlink API.

First Sample

Here is a sample of a very simple completion use case.

NetBeans Platform is used as business application in a newspaper's redaction team. Journalists need to write XHTML page in 4 languages: French, Spanish, Italian, English.

Now, the NetBeans developer can do this with a very small effort.

He has to create a package info file in a NetBeans project module.

Then, let's annotate it :

Loading ....


Mastering content


One of the key concept of this API is CompletionItemData class.

This simple class provides you with common properties and behavior you need to implement more advanced completions.

Here is a class implementing CompletionItemDataProvider :

Loading ....


Now you have to declare its use in content attribute :


Loading ....

A la Camel URI

As you've probably noticed, the content attribute in AttributeCompletionRegistration annotation uses an  URI form.

It's most alike Camel uses it to configure endpoints. This pattern allows rich configuration in a compact form.

Some sample of content URI use :


Loading ....


In our newspaper application, the scheme part (here raw or bean) tells which CompletionService to use (a subinterface of CompletionItemDataProvider).

In our case bean scheme is selecting BeanCompletionService. This service delegates the CompletionItemData delivery to a class specified in URI specific part.

Here it is : mynewspaper.netbeans.completion.lang.LangCompletionItemDataProvider


Build your own completion service

The API provides you with the interface CompletionService.


Loading ....

You have to implement a class with this interface.

Your completion service should a have strong URI scheme to be clearly distinguished.

We choose lang here.


Loading ....

Java SPI is used to discover completion service at runtime.

So, you have to create a META-INF/services/org.netbeans.spi.editor.completion.xhtml.api.CompletionItemService file and in your NetBeans module project add the following line :


mynewspaper.netbeans.completion.lang.LangCompletionItemService


Define a complete action


As you can see in API source code, there is a CompleteAction interface.

A complete action is an action to execute when user select an item in the completion box.

Any CompletionItemData object can have its own.

There is one by default, which is assigned by implementation : when user select item, the value is inserted in current attribute.

But some CompleteItemData instance are not designed to update current document.

Just imagine, you want to add a new language code if a user types a code you don't have in your completion box.

You just add a CompletionItemData with a "Creates missing language" and a custom CompleteAction.

Loading ....


Conclusion

We have seen how it is easy to create XHTML completion for attribute.

You can use many concepts to achieve your goals :

- built in completion services : raw, csv, rest
- build a CompletionItemData provider and use bean completion service
- build a full completion service from scratch
- usage of CompleteAction for specific behaviors at selection





Contrat Creative Commons
the jee architect cookbook by Olivier SCHMITT est mis à disposition selon les termes de la licence Creative Commons Paternité - Pas d'Utilisation Commerciale - Pas de Modification 3.0 Unported.


Aucun commentaire:

Enregistrer un commentaire