Filter

From Documentation
amchuang

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.

File:ZK Filter Firstlook Default.jpg

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

File:ZK Filter Firstlook Custom.jpg

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

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...),

Resource