Wiki Wiki

Štítky: zk zk-dl lovbox dllovbox


List of value box shorten to Lovbox is a component higly similar to Combobox in the usage but the real implementation ancestors are Bandbox and the DLListbox. The main use case, which made the greatest impuls to design such component, was the combobox freezing in the web browser when to model consisted of couple thousands of instances. The new component solves this issue by the inner listbox with sorting and paging which works with the only part of the model and the rest can by dynamically loaded from the database, for example. More about the listbox is in the article DLListbox.

To be honest not everything are just pros, there is also one big con. That is the autocompletion which doesn't work in the Lovbox due to the possibly huge data model. That missing functionality is deputized by the quick filter which is brought by the listbox. That allows the users to quickly find the desired value and select it.

The Lovbox usage is similar to the Combobox usage. Both components implements the Cascadable interface so that the both components can be connected to their parent (master) components and be refreshed on their change. More about that usage in the article DLCombobox.

Component definition#

Lovbox can be defined in two ways. The first one is the shorten notation as a self-closing tag. Such single line definition automatically creates the inner popup window with listbox, but the component definition requires the *labelProperty* which defines the title attribute in the entity. The optional parameter *descriptionProperty* allows to define the second column to be shown. Besides that it also requires the *apply* parameter with the lovbox's controller.

 <!-- standard single-line definition -->
<lovbox apply="${ctl.lovboxCtl}" selectedItem="@{ctl.selected}" labelProperty="departmentCode,departmentName" listWidth="400px"/>

<!-- usage of searchProperty -->
<lovbox apply="${ctl.lovboxCtl}" selectedItem="@{ctl.selected}"  listWidth="500px" labelProperty="fullName" searchProperty="surname"/>

Another way is descriptive definition with the full popup definition. That means that besides the lovbox it self it also specifies the popup and inner listbox including its template (renderer) and binding. The listcontrol and paging can be added automatically if it is not said different.

 <!-- standard multiline definition -->
<lovbox apply="${ctl.lovboxCtl}" selectedItem="@{ctl.selected}" listWidth="500px"  rows="12" pageSize="50">
            <listheader label="Title" sort="db()"/>
            <listheader label="Description" sort="db()"/>
        <listitem self="@{each=project}">
            <listcell label="@{project.title}"/>
            <listcell label="@{project.description}"/>


As a part of changes in version 1.3.10 the Lovbox was a bit updated in its display rendering. Some inner configuration was changed and also some paramaters are now deprecated or superfluous. There is the list of current parameters: (bold stays for required)

  • standard ZKOSS parameters - standard set of parameters in ZK components. The outer component is Bandbox so it can be configured in a common way
  • apply - the Lovbox controller to be used
  • listWidth - the width of listbox. ZKOSS still doesn't compute right the list width to properly show the data. It is highly recommended to define the width, default value is 400px.
  • popupHeight - deprecated is 1.3.10 - it used to define the height of the popup, but since last version is it calculated properly in an automatic way.
  • pageSize - number instances on the page. The default value is 10. The default value can be changed by the library property zk-dl.lovbox.pageSize
  • rows - number of *visible* rows in the listbox. It defines the height of the listbox and the popup. It works for values lesser or equal to 15. For higher values the appearance is bugged. Default value is set to 10 but it can be changed by library property zk-dl.lovbox.rows
  • clearButton - allows to completely remove the selected value by setting the null. Default is true
  • createPaging - default is true, it allows to create the paging to reduce the current model size
  • labelProperty - single label property to be shown as a single column or list of multiple properties to define more columns
  • labelFormat - java.text.MessageFormat pattern to split the properties names
  • descriptionProperty - deprecated, use the labelProperty in the multiple mode instead
  • multiple - allow to select multiple values
  • parentCascadeColumn - Cascading parent property name. This property got from selectedItem in parentCascadeId component and used as a filter for this component
  • parentCascadeId - Cascading parent component. ZUL component ID indicating the acestor in the cascade
  • quickFilterAll - allow to filter by all
  • readonly - do not allow to change the value
  • searchProperty - defines the special column to be used as a filter column for the database. In the common use-case it is not required to change it
  • selectedItems - databinding mapping for a multiple selected values
  • selectedItem - databinding mapping for a single selected value

Library properties #

As it is mentioned above there are two library properties affecting the DLLovbox. On defines default pageSize, the another one specifies default rows.
     <!-- for correct appearance should be lesser or equal to 15 -->
0 Přílohy
8597 Zobrazení
Průměr (0 Hlasů)