com.asayama.gwt.angular.site.examples.client.CustomDirectiveExampleDocumentation.html Maven / Gradle / Ivy
GWT Angular wraps AngularJS's mechanism for defining directives, so that the
directives can be defined in Java language. We demonstrate this feature
with a simple "hello" directive, which prints out a text "Hello, World!" to
the screen.
View
In order to print the above code, here is the HTML mark-up that was used.
The important bit, of course, is the inner <DIV> with
the directive data-my-hello. If you are familiar with
AngularJS, or you have been following the other examples for GWT Angular,
you must be familiar by now that all AngularJS directives start with
data-ng-*. The directive shown here, however, has the prefix
of data-ng-my-*.
Directive
Let's take a look at the Java code that was written to support this
directive.
In order to define a custom directive, you must implement GWT Angular's
Directive interface, for which there is a convenient abstract
class AbstractDirective that you can extend if you do not wish
to configure every aspect of your directive and only focus on the bits that
you care about. In this example, we will only implement the method
getTemplate() which returns an HTML fragment of type
TextResource that is automatically inserted into the view when the
directive is evaluated.
Instead of hard-coding the HTML mark-up into the Java code,
ClientBundle allows us to separate the mark-up language into its
own file, outside of Java code. This will make much cleaner and maintainable
code if and when the complexity of the template used for the directive
increases.
Template
The template HTML for this example is shown above. This is the content of
MyHello.html that was bound to the Java code via
MyHelloResource interface's template() method.
There is one variable that is being evaluated in this template,
myHello. This variable is automatically configured by the
GWT Angular. GWT Angular (unlike AngularJS) automatically assigns the value
of the directive, in this example, the returned value from the
getName() method of CustomDirectiveExampleController,
to a variable of the same name as the directive.
Controller
Module
Of course, both the directive and controller code must be registered with an
Angular module, e.g.
We need to clarify what we mean by the "name of the directive." In the view
code, we used the directive data-my-hello, but inside the
template, we used the Angular variable myHello, which we said,
was the same name as the directive. Further more, the name of the Java
class implementing the directive is named MyHello.java.
This all derives from the AngularJS's directive naming practice. AngularJS
dictates that the "name" of a directive should be camelCase, such that
every word-break is capitalized and the first letter must be lower case.
So, GWT Angular takes the simple name of the Java class, e.g.
MyHello, which almost fits this rule, and converts the first letter
to the lower case to derive the name, myHello automatically.
The user can use the directive in the HTML with dash-delimited version of
the same name. In this case, my-hello. The reason we use
data-my-hello is so that the HTML editors do not flag them as invalid
attributes. The expressions my-hello and data-my-hello
are equivalent at runtime.
Of course, if we did not like the name GWT Angular assigns you directive,
you can override it by explicitly passing the name of the directive at the
time you register the component to your module.
Configuration
The following modules are required in the gwt.xml.
The following Maven dependencies are required in the pom.xml.
<dependency>
<groupId>com.asayama.gwt</groupId>
<artifactId>gwt-angular-ng</artifactId>
<version>{{ GWT_ANGULAR_VERSION }}</version>
</dependency>
You can also browse the full source code on Github.
{{ GITHUB_GWT_ANGULAR_EXAMPLES_URL }}/blob/master/gwt-angular-examples/CustomDirective