Parameters"

From Documentation
m ((via JWB))
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
 +
{{Deprecated | url=[http://books.zkoss.org/zk-mvvm-book/8.0/advanced/parameters.html zk-mvvm-book/8.0/data_binding/advanced/parameters]|}}
 +
  
 
= Retrieve Binding Parameter =
 
= Retrieve Binding Parameter =
ZK allows you to '''pass any object or value that can be referenced by EL''' on a ZUL to command method through command binding annotation. Your command method's signature should have a corresponding parameter that is annotated with <tt> @BindingParam </tt> with the same type and key.
+
ZK allows you to '''pass any object or value that can be referenced by EL''' on a ZUL to command method through command binding annotation. Your command method's signature should have a corresponding parameter that is annotated with <code>@BindingParam</code> with the same type and key.
  
 
The syntax is:
 
The syntax is:
Line 22: Line 24:
  
 
'''Example to pass parameters'''
 
'''Example to pass parameters'''
<source lang="xml" high="13,14">
+
<source lang="xml" highlight="13,14">
  
 
<grid id="outergrid" width="700px" model="@bind(vm.items)">
 
<grid id="outergrid" width="700px" model="@bind(vm.items)">
Line 44: Line 46:
  
 
</source>
 
</source>
* We retrieve row index (Integer class) by iteration status variable and pass it with key "index".  
+
* Line 13: We retrieve row index (Integer class) by iteration status variable and pass it with key "index".  
* We retrieve domain object (Item class) by iteration variable and pass it with key "item".
+
* Line 14: We retrieve domain object (Item class) by iteration variable and pass it with key "item".
  
 
'''Command methods in the ViewModel'''
 
'''Command methods in the ViewModel'''
<source lang="java" high="2,7">
+
<source lang="java" highlight="2,7">
  
 
@Command
 
@Command
Line 63: Line 65:
  
 
</source>
 
</source>
* Command method showIndex() should have a Integer in its argument list. We also have to specify the key "index" in <tt> @BindingParam </tt> (line 2)
+
* Line 2: Command method showIndex() should have a Integer in its argument list. We also have to specify the key "index" in <code>@BindingParam</code>.
* The same as delete(), it should have a parameter with Item class in its argument list. We also have to specify the key "item" in <tt> @BindingParam </tt> (line 7)
+
* Line 7: The same as delete(), it should have a parameter with Item class in its argument list. We also have to specify the key "item" in <code>@BindingParam</code>.
  
 
== A Global Command Example ==
 
== A Global Command Example ==
Line 76: Line 78:
 
</source>
 
</source>
  
The global command method receives parameter through <tt> @BindingParam </tt>.
+
The global command method receives parameter through <code>@BindingParam</code>.
  
 
<source lang="java">
 
<source lang="java">
Line 88: Line 90:
  
 
== Parameter Default Value ==
 
== Parameter Default Value ==
You could choose not to pass parameter for a command method that has parameters. The parameter will become null if you don't pass it, but you can choose to give it a default value with <tt> @Default </tt>. This annotation can be used with other parameter related annotations.
+
You could choose not to pass parameter for a command method that has parameters. The parameter will become null if you don't pass it, but you can choose to give it a default value with <code>@Default</code>. This annotation can be used with other parameter related annotations.
  
 
'''Specify parameter's default value '''
 
'''Specify parameter's default value '''
Line 116: Line 118:
  
 
'''Example to pass a UI component'''
 
'''Example to pass a UI component'''
<source lang="xml" high="8">
+
<source lang="xml" highlight="8">
  
 
<listbox model="@load(vm.items)" selectedItem="@bind(vm.selected)" hflex="true" height="300px">
 
<listbox model="@load(vm.items)" selectedItem="@bind(vm.selected)" hflex="true" height="300px">
Line 147: Line 149:
 
= Retrieve Context Object =
 
= Retrieve Context Object =
  
We can retrieve a value or implicit objects from various context scopes in '''initial methods''' (methods with <tt> '''@Init''' </tt>) and '''command methods''' (methods with <tt> '''@Command''' </tt>) by applying parameter related annotation on these method's parameters. We list all available HTTP context objects retrieved by parameters annotations related annotations in sections under [[ZK Developer's Reference/MVVM/Syntax/ViewModel/Parameters | Parameters]]
+
We can retrieve a value or implicit objects from various context scopes in '''initial methods''' (methods with <code>'''@Init'''</code>) and '''command methods''' (methods with <code>'''@Command'''</code>) by applying parameter related annotation on these method's parameters. We list all available HTTP context objects retrieved by parameters annotations related annotations in sections under [[ZK Developer's Reference/MVVM/Syntax/ViewModel/Parameters | Parameters]]
  
 
== Retrieve HTTP Context Object ==
 
== Retrieve HTTP Context Object ==
Line 182: Line 184:
  
 
== Retrieve ZK Context Object ==
 
== Retrieve ZK Context Object ==
You can also receive ZK context object by <tt> @ContextObject </tt> with various <tt>org.zkoss.bind.annotation.ContextType </tt> including <javadoc> org.zkoss.zk.ui.Execution</javadoc>, <javadoc> org.zkoss.zk.ui.Desktop</javadoc>, <javadoc> org.zkoss.zk.ui.Session</javadoc>, <javadoc> org.zkoss.bind.BindContext</javadoc>, <javadoc> org.zkoss.bind.Binder</javadoc>, etc. We list all available context objects you can retrieve by <tt> @ContextObject </tt> in [[ZK Developer's Reference/MVVM/Syntax/ViewModel/Parameters/@ContextParam]]
+
You can also receive ZK context object by <code>@ContextObject</code> with various <code>org.zkoss.bind.annotation.ContextType</code> including <javadoc> org.zkoss.zk.ui.Execution</javadoc>, <javadoc> org.zkoss.zk.ui.Desktop</javadoc>, <javadoc> org.zkoss.zk.ui.Session</javadoc>, <javadoc> org.zkoss.bind.BindContext</javadoc>, <javadoc> org.zkoss.bind.Binder</javadoc>, etc. We list all available context objects you can retrieve by <code>@ContextObject</code> in [[ZK Developer's Reference/MVVM/Syntax/ViewModel/Parameters/@ContextParam]]
  
 
We retrieve current binding source component and ViewModel's view component at initial method and command method.
 
We retrieve current binding source component and ViewModel's view component at initial method and command method.
Line 223: Line 225:
  
 
== Retrieve Event Object ==
 
== Retrieve Event Object ==
  Since 6.0.1
+
  Since 6.0.1 and ZK EE
 +
Since 6.5.2, it is supported in CE
  
  
 
There are two ways to retrieve an event object:
 
There are two ways to retrieve an event object:
  
# Use reserved keyword '''event''' in <tt> @command </tt> parameter list in a ZUL.
+
# Use reserved keyword '''event''' in <code>@command</code> parameter list in a ZUL.
# Apply annotation '''<tt> @ContextParam(ContextType.TRIGGER_EVENT) </tt> ''' on a command method's parameter.
+
# Apply annotation '''<code>@ContextParam(ContextType.TRIGGER_EVENT)</code> ''' on a command method's parameter.
  
 
Here we have a ''label'' to show what a user is typing in the ''textbox''. The user's typing content is stored in InputEvent's value property, so we can pass it by '''event.value''' when we bind a command to '''onChanging''' attribute.
 
Here we have a ''label'' to show what a user is typing in the ''textbox''. The user's typing content is stored in InputEvent's value property, so we can pass it by '''event.value''' when we bind a command to '''onChanging''' attribute.
Line 264: Line 267:
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Latest revision as of 07:35, 8 July 2022

Stop.png This article is out of date, please refer to zk-mvvm-book/8.0/data_binding/advanced/parameters for more up to date information.


Retrieve Binding Parameter

ZK allows you to pass any object or value that can be referenced by EL on a ZUL to command method through command binding annotation. Your command method's signature should have a corresponding parameter that is annotated with @BindingParam with the same type and key.

The syntax is:

@command('commandName', [arbitratyKey]=[EL-expression] )

@global-command('commandName', [arbitratyKey]=[EL-expression] )

[arbitratyKey]=[EL-expression]
The expression is optional. It's used only when you want to pass parameters to command method.

A Local Command Example

Assume we have data in grid. It's common to put a button at the end of a row to manipulate it, like delete or update. We usually need index or domain object of a row to perform a action like update.

Mvvm-binding-parameters.png

Here is the zul of above screenshot:

Example to pass parameters

	<grid id="outergrid" width="700px" model="@bind(vm.items)">
		<columns>
			<column label="index"/>
			<column label="name"/>
			<column label="action" width="300px"/>
		</columns>
		
		<template name="model" var="item">
			<row>
				<label value="@bind(itemStatus.index)"/>
				<label value="@bind(item.name)"/>
				<hbox>
					<button label="Index" onClick="@command('showIndex', index=itemStatus.index)"/>
					<button label="Delete" onClick="@command('delete', item=item)"/>
				</hbox>
			</row>
		</template>
	</grid>
  • Line 13: We retrieve row index (Integer class) by iteration status variable and pass it with key "index".
  • Line 14: We retrieve domain object (Item class) by iteration variable and pass it with key "item".

Command methods in the ViewModel

	@Command
	public void showIndex(@BindingParam("index") Integer index) {
		message = "item index: " + index;
	}

	@Command
	public void delete(@BindingParam("item") Item item ) {
		int i = items.indexOf(item);
		items.remove(item);
		message = "remove item index " + i;
	}
  • Line 2: Command method showIndex() should have a Integer in its argument list. We also have to specify the key "index" in @BindingParam.
  • Line 7: The same as delete(), it should have a parameter with Item class in its argument list. We also have to specify the key "item" in @BindingParam.

A Global Command Example

Passing parameter in global command binding can share data among ViewModels.

The following code passes selected item to another ViewModel.

<button label="Submit" onClick="@command('submit') @global-command('detail', name=vm.selectedName)" />

The global command method receives parameter through @BindingParam.

	@GlobalCommand
	public void detail(@BindingParam("name")String name){
		//...
	}

Parameter Default Value

You could choose not to pass parameter for a command method that has parameters. The parameter will become null if you don't pass it, but you can choose to give it a default value with @Default. This annotation can be used with other parameter related annotations.

Specify parameter's default value

	//getter and setter
	@Command
	public void showIndex(@BindingParam("index") @Default("0") Integer index) {
	this.index = index;
	}
  • We set index's default value to 0.

Example to bind above command

		<label value="@bind(vm.index)"/>

		<button label="button01" onClick="@command('showIndex', index=9)"/>
		<button label="button02" onClick="@command('showIndex')"/>
  • Click button01, the label's value is 9.
  • Click button02, the label's value is 0.


You can even pass UI components. This resort can make you manipulate UI components directly but also adds a coupling between ViewModel and View which weaken the strength of MVVM pattern.

Example to pass a UI component

		<listbox model="@load(vm.items)" selectedItem="@bind(vm.selected)" hflex="true" height="300px">
			<listhead>
				<listheader label="Name"/>
				<listheader label="Price" align="center" />
				<listheader label="Quantity" align="center"  />
			</listhead>
			<template name="model" var="item">
				<listitem onMouseOver="@command('popupMessage', target=self, content=item.description)">
					<listcell label="@bind(item.name)"/>
					<listcell label="@bind(item.price)@converter('formatedNumber', format='###,##0.00')"/>
					<listcell label="@bind(item.quantity)" sclass="@bind(item.quantity lt 3 ?'red':'')"/>
				</listitem>
			</template>
		</listbox>
  • We pass listitem by implicit object "self".

Command method to receive UI component

	@Command
	public void popupMessage(@BindingParam("target")Component target, @BindingParam("content")String content){
		//...
	}

Retrieve Context Object

We can retrieve a value or implicit objects from various context scopes in initial methods (methods with @Init) and command methods (methods with @Command) by applying parameter related annotation on these method's parameters. We list all available HTTP context objects retrieved by parameters annotations related annotations in sections under Parameters

Retrieve HTTP Context Object

Example to get browser information

public class HttpParamVM {

	String headerParam;
	
	@Init
	public void init(@HeaderParam("user-agent")String browser){
		headerParam = browser;

	}
}


You can apply multiple parameter-related annotations on one method's parameter, and the binder will retrieve the value among multiple context scopes in specified order. It continues to find in next context scope until it retrieves first non-null object.

Multiple context scope retrieval example

	@Init
	public void init(@CookieParam("nosuch") @HeaderParam("user-agent") String guess){
		cookieParam = guess;
	}
  • In above example, it searches in HTTP request cookie first. If not found a non-null object, it continue to retrieve in HTTP request header.

Retrieve ZK Context Object

You can also receive ZK context object by @ContextObject with various org.zkoss.bind.annotation.ContextType including Execution, Desktop, Session, BindContext, Binder, etc. We list all available context objects you can retrieve by @ContextObject in ZK Developer's Reference/MVVM/Syntax/ViewModel/Parameters/@ContextParam

We retrieve current binding source component and ViewModel's view component at initial method and command method.

Example to retrieve ZK context object

	//getter and setter
	@Init
	public void init(@ContextParam(ContextType.COMPONENT) Component component,
			@ContextParam(ContextType.VIEW) Component view) {
		
		bindComponentId = component.getId();
		bindViewId = view.getId();
	}

	@Command
	public void showId(@ContextParam(ContextType.COMPONENT) Component component,
			@ContextParam(ContextType.VIEW) Component view) {
		
		bindComponentId = component.getId();
		bindViewId = view.getId();
	}

We create 2 labels that bound to current binding component's id and view component's id.

A zul bound to above ViewModel

<vbox id="vbox" apply="org.zkoss.bind.BindComposer" viewModel="@id('vm') @init('eg.ContextParamVM')">

	<label id="componentId" value="@load(vm.bindComponentId)" />
	<label id="viewId" value="@load(vm.bindViewId)" />
	<button id="cmd" label="cmd" onClick="@command('showId')" />
</vbox>
  • When the page is loaded, component's and view's id are both "vbox". For init(), its current binding source component is vbox. As we apply @init on vbox, it's always the ViewModel's view component.
  • After clicking the button, component's id becomes "cmd" because command binding's binding source component is the button and view's id doesn't change.

Retrieve Event Object

Since 6.0.1 and ZK EE
Since 6.5.2, it is supported in CE


There are two ways to retrieve an event object:

  1. Use reserved keyword event in @command parameter list in a ZUL.
  2. Apply annotation @ContextParam(ContextType.TRIGGER_EVENT) on a command method's parameter.

Here we have a label to show what a user is typing in the textbox. The user's typing content is stored in InputEvent's value property, so we can pass it by event.value when we bind a command to onChanging attribute.

			<vbox>
				<label id="msg" value="@load(vm.message)" />
				<textbox onChanging="@command('showTyping',v=event.value)" />
			</vbox>


ViewModel for the zul above

public class EventViewModel {

	//getter for "message"

	@Command
	@NotifyChange("message")
	public void showTyping(@BindingParam("v") String value, @ContextParam(ContextType.TRIGGER_EVENT) InputEvent event) {
		typingMessage = value;
		//typingMessage = event.getValue(); same effect
	}
}
  • The first parameter receives value from the ZUL. The second one is passed by the binder, so we don't need to specify it in the ZUL.

Version History

Version Date Content
6.0.0 February 2012 The MVVM was introduced.
6.0.1 April 2012 Allow to retrieve event object in a ZUL and ViewModel




Last Update : 2022/07/08

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