Fragment

From Documentation

WarningTriangle-32x32.png This page is under construction, so we cannot guarantee the accuracy of the content!


Fragment

  • Demonstration: N/A
  • Java API: Fragment
  • JavaScript API: Fragment
  • Style Guide: N/A
    • Available for ZK:
    • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

    Employment/Purpose

    Fragment is a ZK component that let developers combine native HTML elements with ZK data binding syntax to make the static page to be dynamic.

    Example

    ZKComRef Fragment Example.png

    <zk>
        <fragment viewModel="@id('vm') @init('org.zkoss.fragment.demo.VM2')" 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>
    </zk>
    

    Data Binding

    By binding the properties of ViewModel you need to a Fragment component, you can use the ZK MVVM data binding syntax to access the ViewModel indirectly on the native HTML elements.

    These are the supported annotations for now:

    • @save
     syntax: @save([EL-expression])
    
    • @load
     syntax: @load([EL-expression])
    
    • @bind
     syntax: @bind([EL-expression])
    
    • @command
     syntax: @command([EL-expression], [arbitraryKey]=[EL-expression])
    
    • @global-command
     syntax: @global-command([EL-expression], [arbitraryKey]=[EL-expression])
    

    This component also provides a virtual textContent attribute for HTML elements to insert data into the tag.

    <zk>
        <fragment viewModel="@id('vm') @init('org.zkoss.zktest.test2.F85_ZK_3681_Command_VM')"
                  status="@bind(vm.status)"><![CDATA[
            <div>
                <input type="checkbox" onchange="@command('onCheck', checked=event.checked)" />
                Check this checkbox: <span textContent="@load(status)"/>
            </div>
    
            <div>
                <button onclick="@global-command('callGlobal', text='Hello', num=1)">Call global (1)</button>
                <button onclick="@global-command('callGlobal', text='World', num=2)">Call global (2)</button>
            </div>
        ]]></fragment>
    </zk>
    

    Shadow Elements

    In this example, we use if and forEach tags together for condition and collection rendering.

    <zk>
        <fragment viewModel="@id('vm') @init('org.zkoss.zktest.test2.F85_ZK_3681_Shadow_VM')"
            issues="@bind(vm.issues)"><![CDATA[
            <section>
                <h1>My Issue List</h1>
                <ul>
                    <forEach items="@load(issues)">
                        <!-- There's a pre-defined variable "each" for convenience. -->
                        <li>
                            <!-- @bind(each) is wrong because each is just a temp variable in loops. -->
                            <input type="checkbox" checked="@load(each.isDone)" />
                            <if test="@load(each.isDone)">
                                <strike>[<span textContent="@load(each.id)"/>]
                                <span textContent="@load(each.description)"/></strike>
                            </if>
                            <!-- No else for now. -->
                            <if test="@load(!each.isDone)">
                                [<span textContent="@load(each.id)"/>]
                                <span textContent="@load(each.description)"/>
                            </if>
                        </li>
                    </forEach>
                </ul>
            <section>
        ]]></fragment>
    </zk>
    

    Data Validation

    Server-side Property/Form Validation

    To ensure data is correct and useful, we can leverage ZK's validators.

    <zk>
        <fragment viewModel="@id('vm') @init('org.zkoss.fragment.demo.VM1')" 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>
    </zk>
    

    In order to access invalidate messages by HTML elements, simply bind the messages onto Fragment properties.

    Here we can use form-binding and form validators to validate all the fields.

    <zk>
        <fragment viewModel="@id('vm') @init('foo.BarVM')" validationMessages="@id('vmsgs')"
         form="@id('fx') @load(vm.currentUser) @save(vm.currentUser, before='submit') @validator('formBeanValidator', prefix='p_')"
         name="@bind(fx.name)" nameerror="@bind(vmsgs['p_name'])"><![CDATA[
         <input type="text" value="@bind(name)"/><span textContent="@load(nameerror)"/>
         <button onclick="@command('submit')">Submit</button>
        ]]></fragment>
    </zk>
    

    Client-side Property Validation

    This component also provides a new @jsvalidator(validation_function_name) syntax to validate at client-side by evaluating your custom JavaScript function. You can use this annotation on HTML elements.

    ValidationFunction(val, vmsgs)
    * val: The user input data.
    * vmsgs: The validation message holder object. 
    * Returns: Boolean. True if the data is valid.
    

    You can use an implicit object (vmsgs) to get the client-side invalid messages. The @jsvalidator has its own validation message holder not shared with server-side.

    <zk>
        <fragment viewModel="@id('vm') @init('foo.BarVM')" someprop="@bind(vm.prop1)"><![CDATA[
            <input type="text" value="@bind(someprop) @jsvalidator('validateExample')"/>
            <span textContent="@load(vmsgs['foo'])"/>
            <script type="text/javascript">
            function validateExample(val, vmsgs) {
                var isValid = someValidationProcess(val);
                vmsgs['foo'] = isValid ? '' : 'Invalid value';
                return isValid;
            }
            </script>
        ]]></fragment>
    </zk>
    

    For security concerns, we recommend you to use server-side @validator in most cases and choose client-side @jsvalidator if the validation needs an instant feedback such as password strength, number range, and so on.

    Event Handling

    The command of ViewModel can be invoked by attaching DOM events with @command or @global-command on HTML elements. Once the DOM event is triggered (i.g. clicked or changed), the command of ViewModel will be executed and receive the corresponding event object.

    You can get more details from the event object such as mouse cursor position, pressed keys, entered text, and selected text.

    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

    Properties

    • content: specify the content of this component.
    • src: specify the URI of an external content file. The file encoding is assumed to be UTF-8.

    Supported Events

    Name
    Event Type
    onRecover
    Event: Event

    Represents an event sent back to the server caused by an offline recovery.

    Supported Children

    None
    

    Use Cases

    Version Description Example Location
    8.5+ Data binding, Shadow elements Client Binding with ZK MVVM for your eyes only
    8.5+ Data validation, Event handling  

    Version History

    Last Update : 2017/06/22


    Version Date Content
    8.5 2017/09/21 Add the new Fragment component
         



    Last Update : 2017/06/22

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