Filter

Author
Sam Chuang, Engineer, Potix Corporation

Date
October 30, 2013

Version
ZK 6.5 and later

Introduction

ZK give developer the power of creating advanced component, extending the component set for your application. In this article, I will create a re-usable component: filterpopup. It's designed for working with collection component that needs filter functionality. For instance, the filterpopup component can be used with Grid, user can use it to filter out huge amount of data, search the required information quickly and intuitively.

Besides, it's also designed for highly customizable, able to integrate with different type of constrain, seamlessly works with different type of data type.

How it Works

The Filterpopup component is composed from three regions.

Regions

Top

The top region is responsible for configuration settings. The default implementation includes:

• Textbox: used for input constraint to perform filtering command.
• Checkbox: to perform select all command.

Default implementation:

		<div id="top" vflex="min">
			<vlayout>
				<textbox value="@bind(vm.constraint)" instant="true" 
						onChanging="@command('performFiltering', constraint=event.value)"></textbox>
				<checkbox checked="@load(vm.selectAll)" label="(Select All)" 
						onCheck="@command('selectAll', checked=event.checked)"></checkbox>
			</vlayout>
		</div>

Center

The center region is responsible for showing the filtered result by constraint, by using Listbox component.

• Default implementation:

	<div id="center" vflex="true">
		<custom-attributes org.zkoss.zul.listbox.rod="true"/>
		<listbox model="@bind(vm.filteredByConstraintModel)" 
				checkmark="true" id="listbox" vflex="true">
			<template name="model">
				<listitem>
					<listcell label="@load(each)" />
				</listitem>
			</template>
		</listbox>
	</div>

Bottom

The bottom region is responsible for commands, The default implementation includes:

• OK button: perform ok command to confirm user's selection, and fire a FilterEvent with selection.
• Cancel button: perform cancel command to discard any changes.

	<div id="bottom" vflex="min">
		<hbox pack="end" width="100%" spacing="5px">
			<button onClick="@command('ok')" label="OK" mold="trendy" width="75px"></button>
			<button onClick="@command('cancel')" label="Cancel" mold="trendy" width="75px"></button>
		</hbox>
	</div>

Usage

Event

• FilterEvent: triggered when user click OK button (perform ok command) and the selection is not empty.

View Model

Bindings

• constraint:

Commands

• setFilter
• TODO: setComparator
• selectAll
• performFiltering:
• ok
• cancel

Customization

Settings

Use template with name="top" to customize the top region.

<filterpopup id="filterpopup" width="300px" height="400px">
	<template name="top">
		<vlayout>
			<textbox value="@bind(vm.constraint)" instant="true" 
					onChanging="@command('performFiltering', constraint=event.value)"></textbox>
			<checkbox checked="@load(vm.selectAll)" label="(Select All)" 
					onCheck="@command('selectAll', checked=event.checked)"></checkbox>
		</vlayout>
	</template>
	...
</filterpopup>

Filter

Use setFilter command to set filter

<filterpopup id="filterpopup" width="300px" height="400px">
	<template name="top">
		<vlayout>
			<radiogroup>
				<radio label="Contains..."
					onCheck="@command('setFilter', filter=ContainsStringFilter)" 
					checked="true">
				</radio>
				<radio label="Begins with..."
					onCheck="@command('setFilter', filter=StartWithStringFilter)">
				</radio>
			</radiogroup>
			...
		</vlayout>
	</template>
	...
</filterpopup>

Head

Use template with name="head" to customize the listhead of Listbox in center region.

<filterpopup id="filterpopup" width="300px" height="400px">
	<template name="head">
		 <listhead>
	            <listheader label="Name"/>
	            <listheader label="Birth"/>
	        </listhead>
	</template>
	...
</filterpopup>

Model

Use template with name="model" to customize the Listbox in center region.

<filterpopup id="filterpopup" width="300px" height="400px">
	<template name="model">
		<listitem>
			<listcell label="@load(each.name)" />
			<listcell label="@load(each.birth)" />
		</listitem>
	</template>
	...
</filterpopup>

Summary

With the power of ZK technology (MVVM, template etc...),