v1 13. Nalu Processor Plugins

Nalu Processor Plugins

To support Widget-class based libraries (like GWT itself, GXT, etc.) and HTMLElement- based libraries (f.e.: Elemento, Domino-UI, etc.), Nalu has a plugin mechanism. The code, that is platform or widget library specific, is separated into a plugin.

Plugin Interface

To avoid creating a dependency to GWT or Elemento, Nalu outsourced the depending into a plugin. The plugin interface provides a set of methods, that needed to be outsourced.

The plugin interface:

The methods of the ÌsPlugin-interface are:

• alert(String message): display the message text inside a popup

• attach(String selector, Object asElement): this methods add the asElement-object to the DOM using the selector

• confirm(String message): open a popup with the message and requests a yes-no-decision

• getStartRoute(): returns the start route which will be used in cased the application is started without a bookmark

• register(HashHandler handler): register a hash handler. will be called in case the hash changes

• remove(String selector): removes everything located under the DOM element with the id selector

• route(String newRoute, boolean replace): add the new route (as hash) to the url. if replace is false the hash did not get updated

Currently there are two existing plugins:

• a Elemental2 plugin for widgets sets based on HTMLElement
• a GWT plugin for widget sets based on GWT Widget

Elemental2 based Widget Sets

In case your widget set is based on Elemental2, you have to use, the nalu-plugin-elemetal2.

Configure the Application

To use the plugin, you have to add the following lines to your pom:

    <dependency>
      <groupId>com.github.nalukit</groupId>
      <artifactId>nalu-plugin-elemental2</artifactId>
      <version>LATEST</version>
    </dependency>

Using the plugin

To tell Nalu, that the application is using the Elemental2 plugin, you have to create the plugin and and use the instance as a parameter of the run method:

public class Application
  implements EntryPoint {

  public void onModuleLoad() {
    // Create the application.
    // The ApplicationImpl-class will be generated by the framework.
    MyApplication application = new MyApplicationImpl();
    // start the application by calling the run()-method.
    application.run(new NaluPluginElemental2());
  }
}

To define a node of the DOM as extension point where child nodes can be added, by just setting an id using the id-attribute. The selector attribute inside the @Controller-annotation will be used to look for a node inside the DOM with the selector value as id. Once the node is found, all children of the node will be removed and the new child added.

GWT based Widget Sets

In case your widget set is based on the GWT Widget-class, you have to use, the nalu-plugin-gwt.

Configure the Application

To use the plugin, you have to add the following lines to your pom:

    <dependency>
      <groupId>com.github.nalukit</groupId>
      <artifactId>nalu-plugin-gwt</artifactId>
      <version>LATEST</version>
    </dependency>
    <dependency>
      <groupId>com.github.nalukit</groupId>
      <artifactId>nalu-plugin-gwt-processor</artifactId>
      <version>LATEST</version>
    </dependency>

In opposite to the Elemental2 pugin the GWT plugin needs another processor.

Using the plugin

To tell Nalu, that the application is using the GWT plugin, you have to create the plugin and and use the instance as a parameter of the run method:

public class Application
  implements EntryPoint {

  public void onModuleLoad() {
    // Create the application.
    // The ApplicationImpl-class will be generated by the framework.
    MyApplication application = new MyApplicationImpl();
    // start the application by calling the run()-method.
    application.run(new NaluPluginGWT());
  }
}

Because of the different way GWT sinks events, etc. Nalu uses the add-method of the Widget-class to append a child. Using this plugins a little bit more work. The application has to create a method for every extension point and annotate the method with @Selector. A method annotated with @Selector must accept one parameter (type is Widget).

The last thing, the application has to do, is trigger the processor by calling:

   IsSelectorProvider<Shell> provider = new MySelectorProviderImpl();
   provider.initialize(this);

Nalu will use the simple name of the class and add the string 'SelectorProviderImpl'. In case you want to set a provider for a class which is called 'contentCompoent', the genereated provider wil be named: 'ContentComponentSelectorProviderImpl'! In case you are not sure, what's the name of the generated class is, take a look at 'target/generated-sources/annotations'-folder.

A good place to trigger the processor is the component bind-method.

Here is an example of a Shell class using the GWT plugin:

@Shell("applicationShell")
public class ApplicationShell
  extends AbstractCompositeShell<MyApplicationContext> {

  public Shell() {
    super();
  }

  ...

  @Override
  public void bind() {
    IsSelectorProvider<Shell> provider = new ShellSelectorProviderImpl();
    provider.initialize(this);
  }

  @Selector("content")
  public void setContent(Widget widget) {
    // add the widget ...
  }

  @Selector("sideNav")
  public void setNavigation(Widget widget) {
    // add the widget ...
  }
}

Custom Plugin

Creating a new plugin is quite simple. One of Nalus's junit tests needed a plugin that runs in batch mode. A new plugin was created and used by the test. Instead of the Widget- or HTMLElement-class, this plugin handles String.

You will find the test case here:

JUnit test case with a custom plugin

One interesting point of the test case is, that Nalu works outside the GWT eco system. So, it can be expected, that Nalu can be used on server side (with servlets) or with Android, etc.