Package org.zkoss.zkmax.zul

Class Fragment

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, Component, DynamicPropertied, Scope, ComponentCtrl
    public class Fragment
extends AbstractComponent
implements DynamicPropertied
    A component that let developers combine native HTML elements with ZK data binding syntax to make the static page to be dynamic.
    • @save
    • @load
    • @bind
    • @command
    • @global-command

    Usage First, put the HTML source inside the tag and surround them with <![CDATA[ ]]>. Or you can set the src property to load an existed file. Then define data as the properties of <fragment> by using @bind only to map some properties of the view model. In HTML simply bind these data with @save, @load or @bind annotations same as ZK. Notice you cannot bind data with properties of the view model directly, because only these defined at the <fragment> can be accessed in the scope of HTML elements. For example: 

    
 <fragment viewModel="@id('vm') @init('foo.BarVM')" mydata="@bind(vm.data)"><![CDATA[
   <!-- mydata, not vm.data -->
   <div textContent="@load(mydata)" />
 ]]></fragment>

    textContent attribute for HTML elements This component provides a virtual textContent attribute for HTML elements to insert data into the tag. <span textContent="@load(foo)"></span> and <span>[foo content]</span> have the same meaning.

    Shadow Elements This component also provides shadow elements for condition and collection rendering. The usage is nearly the same as ZK Shadow Elements.

    • <forEach items="" var="" begin="" end="" step="" varStatus=""></forEach>
    • <if test=""></if>

    Server-side Property/Form Validation You can use @validator to validate user input. Remember to initialize validationMessages first same as ZK. Simply add them with the property binding of <fragment>. Because of the limitation that HTML elements cannot access server side variable vmsgs, you should map the invalid messages too. This component also supports form binding/validation (form="@id('fx') ... @validator"). In this case, you should change the binding prefix from vm (view model) to fx (middle object). For example: 

    
 <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>

    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. It can be used inside the HTML source code only and cannot be used separately without data binding. Just like ZK, it provides a validation message holder (vmsgs) implicitly for displaying error. The differences are you don't need to initialize validationMessages and you are responsible for cleaning the invalid message if it is valid. For example: 

    
 <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">
   // @param val The value of user input
   // @param vmsgs A object of validation message holder
   // @return boolean true if it is valid
   function validateExample(val, vmsgs) {
     var isValid = someValidationProcess(val);
     vmsgs['foo'] = isValid ? '' : 'Invalid value';
     return isValid;
   }
   </script>
 ]]></fragment>

    Note: This component can only support those browsers which support ECMAScript 5. Like IE9+, Firefox, Safari, Opera, and Chrome.

    Since:
    8.5.0
    Author:
    wenninghsu, rudyhuang
    See Also:
    Serialized Form