# Custom Directives
This page comes from the official Vue.js documentation and has been adapted for Vue GWT.
# Intro
In addition to the default set of directives shipped in core (v-model
and v-show
), Vue also allows you to register your own custom directives.
Note that in Vue 2.0, the primary form of code reuse and abstraction is components - however there may be cases where you just need some low-level DOM access on plain elements, and this is where custom directives would still be useful.
An example would be focusing on an input element, like this one:
When the page loads, that element gains focus (note: autofocus doesn't work on mobile Safari). In fact, if you haven't clicked on anything else since visiting this page, the input above should be focused now. Now let's build the directive that accomplishes this.
Fist we declare a Java class, like for our Components.
Except that we extend VueDirective
and add the @Directive
annotation.
@Directive
public class FocusDirective extends VueDirective {
@Override
public void inserted(Element el, VueDirectiveBinding binding) {
el.focus();
}
}
We can then register our Directive globally:
public class VueGwtExamplesApp implements EntryPoint {
public void onModuleLoad() {
Vue.directive(new FocusDirectiveOptions());
}
}
The name of our directive is determined by the Class name (same as Component).
So in this case the directive will be named v-focus
.
For FocusAndHighlightDirective
the name would have been v-focus-and-highlight
.
If you want to register a directive locally instead, the @Component
also accept a directives
option:
@Component(directives = FocusDirective.class)
public class FocusDirectiveComponent implements IsVueComponent
Then in a template, you can use the new v-focus
attribute on any element, like this:
<input v-focus>
# Hook Functions
A directive definition object can override several hook functions (all optional):
bind
: called only once, when the directive is first bound to the element. This is where you can do one-time setup work.inserted
: called when the bound element has been inserted into its parent node (this only guarantees parent node presence, not necessarily in-document).update
: called after the containing component has updated, but possibly before its children have updated. The directive's value may or may not have changed, but you can skip unnecessary updates by comparing the binding's current and old values (see below on hook arguments).componentUpdated
: called after the containing component and its children have updated.unbind
: called only once, when the directive is unbound from the element.
We'll explore the arguments passed into these hooks (i.e. el
and binding
) in the next section.
# Directive Hook Arguments
Directive hooks are passed these arguments:
- el: The element the directive is bound to. This can be used to directly manipulate the DOM.
- binding: An object containing the following properties.
- name: The name of the directive, without the
v-
prefix. - value: The value passed to the directive. For example in
v-my-directive="1 + 1"
, the value would be2
. - oldValue: The previous value, only available in
update
andcomponentUpdated
. It is available whether or not the value has changed. - expression: The expression of the binding as a string. For example in
v-my-directive="1 + 1"
, the expression would be"1 + 1"
. - arg: The argument passed to the directive, if any. For example in
v-my-directive:foo
, the arg would be"foo"
. - modifiers: An object containing modifiers, if any. For example in
v-my-directive.foo.bar
, the modifiers object would be{ foo: true, bar: true }
.
- name: The name of the directive, without the
- vnode: The virtual node produced by Vue’s compiler. See the VNode API for full details.
- oldVnode: The previous virtual node, only available in the
update
andcomponentUpdated
hooks.
WARNING
Apart from el
, you should treat these arguments as read-only and never modify them.
If you need to share information across hooks, it is recommended to do so through element's dataset.
You can see an example of these arguments values in the official Vue.js doc.
# Object Literals
If your directive needs multiple values, you can also pass in a JSON object literal.
<div v-demo='{ color: "\"white\"", text: "\"hello!\"" }></div>
@Override
public void inserted(Element el, VueDirectiveBinding binding) {
JsObject value = (JsObject) binding.value;
value.get("color") // white
value.get("text") // hello!
}