Small Talks/2017/July/Advanced Usage of Fragment Component

This page is under construction, so we cannot guarantee the accuracy of the content!

Author
Rudy Huang, Engineer, Potix Corporation

Date
June 12, 2017

Version
ZK 8.5

Introduction

The previous blog post "Client Binding with ZK MVVM for your eyes only" gives you a brief introduction on Fragment component in the upcoming ZK 8.5. This article will further explain advanced usage of this component, especially about data validation and event handling.

Data Validation

To ensure data is correct and useful, we can leverage validators. Fragment component supports property binding validation, form binding validation and client-side property validation. Client-side property validation is only available in this component. This section will explain them one by one.

Property Binding and Validation

You can append @validator annotation when you map view model properties onto Fragment properties. It helps you to validate data before saving to the view model. If validation fails, the save process will be aborted and the data will stay unchanged.

<fragment viewModel="..."
    prop1="@bind(vm.prop1) @validator(vm.validator1)">
    // omitted
</fragment>

• Line 2: Append a @validator after @bind annotation to apply a validator.

You can retrieve validation messages and display them. All you need to do is define a new property of a Fragment using @bind to map the invalid message, so it can be bound by HTML elements.

<fragment viewModel="..." validationMessages="@id('vmsgs')"
          prop1="@bind(vm.prop1) @validator(vm.validator1)"
          prop1err="@bind(vmsgs['prop1'])"><![CDATA[
    <input type="text" value="@bind(prop1)"/>
    <span textContent="@load(prop1err)"/>
]]></fragment>

• Line 1: Don't forget to initialize a validation message holder.
• Line 3: Bind an invalid message to prop1err.
• Line 5: Use @load to get the invalid message.

Self-Defined Message Keys

You can get the invalid message by assigning a self-defined key as an alias. The following is an example code showing how to add an invalid message with a self-defined key in a validator.

public class RegExValidator extends AbstractValidator {
    public void validate(ValidationContext ctx) {
        String regex = (String) ctx.getValidatorArg("regex");
        String key = (String) ctx.getValidatorArg("key");
        Object value = ctx.getProperty().getValue();
        if (value == null || !value.toString().matches(regex)) {
            addInvalidMessage(ctx, key, "Invalid: " + value);
        }
    }
}

• Line 4: Get a key from the arguments of a validator.
• Line 7: Use addInvalidMessage(ValidationContext ctx, String key, String message) to add a message with a key.

Then we can use it just like this following example.

<fragment viewModel="..." validationMessages="@id('vmsgs')"
            prop1="@bind(vm.prop1) @validator(vm.regExValidator, key='prop1', regex='^\\d+$')"
            prop1err="@bind(vmsgs['prop1'])">
    <input type="text" value="@bind(prop1)"/>
    <span textContent="@load(prop1err)"/>
</fragment>

• Line 2: Pass arguments (key, regex) to the validator.

Form Binding and Validation

You can use Form Binding and form validators to validate all fields once and for all. In the following example code, a form validator is added and the Fragment component will show the invalid messages if any.

<fragment viewModel="..." validationMessages="@id('vmsgs')"
            form="@id('fx') @load(vm) @save(vm, before='submit') @validator(vm.formValidator)"
            prop1="@bind(fx.prop1)" prop1err="@bind(vmsgs['fkey1'])"
            prop2="@bind(fx.prop2)" prop2err="@bind(vmsgs['fkey2'])"><![CDATA[
    <p><input type="text" value="@bind(prop1)"/><span textContent="@load(prop1err)"/></p>
    <p><input type="text" value="@bind(prop2)"/><span textContent="@load(prop2err)"/></p>
    <button onclick="@command('submit')">Submit</button>
]]></fragment>

• Line 2: Apply form binding by assigning form property to a component.
• Line 3: Use the form middle object fx instead of ViewModel.

JSR 303 Bean Validation

ZK provides built-in validators. Both BeanValidator and FormBeanValidator integrate the Bean Validation 1.0 (JSR 303). For the introduction and environment setup please find the ZK MVVM Book: Using a Built-in Validator. The following example code uses beanValidator and formBeanValidator to validate a JavaBean that is annotated with some constraints.

ViewModel

public class DemoVM {
    private SomeBean someBean = new SomeBean();
    // getter and setter are omitted
}

JavaBean

public class SomeBean {
    private String prop1;

    @Size(min = 3, message = "The prop1 is too short (minimum is 3 characters)")
    public String getProp1() {
        return this.prop1;
    }
    public void setProp1(String prop1) {
        this.prop1 = prop1;
    }
}

• Line 4: Use annotations that JSR 303 provided to define a constraint.

ZUML

<!-- property binding validation -->
<fragment viewModel="..." validationMessages="@id('vmsgs')"
            prop1="@bind(vm.someBean.prop1) @validator('beanValidator', key='fkey1')"
            prop1err="@bind(vmsgs['fkey1'])"><![CDATA[
    <input type="text" value="@bind(prop1)"/>
    <span textContent="@load(prop1err)"/>
]]></fragment>

• Line 3: Use the predefined beanValidator to validate property prop1. We can assign a custom message key by using key argument.

<!-- form binding validation -->
<fragment viewModel="..." validationMessages="@id('vmsgs')"
        form="@id('fx') @load(vm.someBean) @save(vm.someBean, before='submit') @validator('formBeanValidator', prefix='p_')"
        prop1="@bind(fx.prop1)"
        prop1err="@bind(vmsgs['p_prop1'])"><![CDATA[
    <input type="text" value="@bind(prop1)"/>
    <span textContent="@load(prop1err)"/>
    <button onclick="@command('submit')">Submit</button>
]]></fragment>

• Line 3: Use the predefined formBeanValidator to validate a form.

Client-Side Property Validation

The Fragment component provides a novel validator called @jsvalidator running at client side, accepting custom JavaScript functions for validation. The benefit is that there is no need to send requests to the server for each validation. However, since the validation logic will be exposed at client side, some simple check, such as empty checking or range checking, is recommended. The usage is like @validator but it is effective only on applying to HTML elements. The text inside the parentheses is the name of the mentioned validation function. Two parameters are passed to the validation function. One is the user input, and the other is a validation message holder object. The validation function is expected to return a Boolean value to tell the component if the data is valid. Only the valid data will be sent to the server for further operations.

<fragment viewModel="..." prop1="@bind(vm.prop1)"><![CDATA[
    <input type="text" value="@bind(prop1) @jsvalidator('validation')"/>
    <span textContent="@load(vmsgs['prop1'])"/>
    <script type="text/javascript">
    function validation(val, vmsgs) {
        var valid = doValidation(val);
        vmsgs['prop1'] = valid ? '' : 'prop1 error';
        return valid;
    }

    function doValidation(val) {
        // omitted
    }
    </script>
]]></fragment>

• Line 2: Apply @jsvalidator directly to HTML elements. And use the declared validation function as a validation function.
• Line 5-9: The validation function is declared here. The logic is very simple.

The Differences Between @validator and @jsvalidator

Catalogue	@validator	@jsvalidator
Validate at	Server side	Client side
ZK form validation	Supported	Not supported
Validation message holder	Initialized in validationMessages	An implicit vmsgs object

1. @validator relies on the server, while @jsvalidator relies on the browser.
2. @jsvalidator does not support form validation.
3. The validation message holders are not the same. See the following section to know more.

For security concerns, we recommend you to use @validator in most cases and choose @jsvalidator if the validation needs an instant feedback such as password strength.

Validation Message Holder on Client-Side

The @jsvalidator also supports validation messages. There is a predefined message holder object named vmsgs in each Fragment component. This object accepts self-defined keys to get messages. You can retrieve the object from the second argument of a validation function; depending on the validation result you can fill out or clear messages.

You can use an implicit object (vmsgs) to get the client-side invalid message; so you do not need to initialize a validationMessages holder object at the Fragment tag nor bind the invalid messages beforehand. Please note that the holder object is not shared with server side.

<fragment viewModel="..." prop1="@bind(vm.prop1)"><![CDATA[
    // omitted
    <span textContent="@load(vmsgs['prop1'])"/>
    // omitted
]]></fragment>

• Line 3: Use the vmsgs directly.

Event Handling

You can attach DOM events on HTML elements to trigger commands of view models. The command of ViewModel will be executed and receive the corresponding event object.

Following is a quick lookup table of the relation between supported DOM events and ZK Event objects.

ZK Event object	DOM event
MouseEvent	onclick
	oncontextmenu
	ondblclick
	onmousedown
	onmouseenter
	onmouseleave
	onmouseover
	onmouseout
	onmouseup
	ondrag
KeyEvent	onkeydown
	onkeypress
	onkeyup
InputEvent	onchange
	oninput
CheckEvent	onchange (checkbox)
	oninput (checkbox)
SelectionEvent	onselect
DropEvent	ondrop
Event	onblur
	onfocus
	onfocusin
	onfocusout

To retrieve an event object, use a reserved keyword "event" in arguments of @command or apply annotation @ContextParam(ContextType.TRIGGER_EVENT) on a parameter of the command method. For further information, check Retrieve Event Object. For properties of each event object, find out at: org.zkoss.zk.ui.event Javadoc.

<fragment viewModel="..."><![CDATA[
    <button onclick="@command('cmd1', e=event)">Hit me!</button>
    <input type="checkbox" onchange="@command('cmd2')"/>
]]></fragment>

• Line 2: Use a reserved keyword "event" in arguments.

public class EventVM {
    // Method 1
    @Command
    public void cmd1(@BindingParam("e") MouseEvent e) {
        // do something with event
        // omitted
    }

    // Method 2
    @Command
    public void cmd2(@ContextParam(ContextType.TRIGGER_EVENT) CheckEvent e) {
        // do something with event
        // omitted
    }
}

• Line 4: Retrieve the binding parameter e as an event object.
• Line 11: Apply a @ContextParam annotation to retrieve the triggering event object.

Summary

In this article, we show the interaction between Fragment component and ZK MVVM mechanism. You can validate native HTML elements by using @validator, applying form binding, using built-in JSR 303 bean validators or trying a client-side @jsvalidator. You can display the invalid messages after each validation.

In the second part we describe the event object of the relative DOM events. You can get more details from the event object such as mouse cursor position, pressed keys, entered text, and selected text.

The complete demo source code is available on GitHub.

References

• Client Binding with ZK MVVM for your eyes only
• ZK MVVM Reference - Validator
• org.zkoss.zk.ui.event Javadoc

Comments

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.