Upgrade From ZK 6.5

From Documentation


Tip 1: Box Sizing

To improve performance at client side, we use the border-box model for all components in ZK 7 instead of the content-box model. It means a specified CSS property - width/min-width and height/min-height - on the element will consider border width.

Upgrade Sample

In ZK 6.5, the DIV width is 102px if you customize DIV component style as follows:

.z-div {
    border: 1px solid #000000;
    width: 100px;
}

However, after upgrading to ZK 7, the DIV width will become 100px since all CSS class names starting with the prefix "z-" get box-sizing: border-box applied by default. If you want to keep the DIV width equal to 102px in ZK 7, modify the original style as follows:

.z-div {
    border: 1px solid #000000;
    width: 102px;
}

or

.z-div {
    border: 1px solid #000000;
    width: 100px;
    box-sizing: content-box;
}

Tip 2: Component Mold

Since we drop support the browsers that do not support CSS3 in ZK 7, some components' molds are now sharing the same DOM structure with their default mold to improve performance. However, you do not need to change your Component.setMold() code since ZK handles this transparently.

Upgrade sample

In this smalltalk we show how to customize the button component using CSS 3 with the os mold based on ZK 6.5. Originally the style for an os mold button was overridden using the class z-button-os.

.z-button-os {
    color: #FFFFFF;
    font-weight: bold;
    /* omitted */
}

While (in ZK6.5) the button has 2 separate mold implementations (trendy and os), now in ZK7 both molds share the same markup using the same CSS class "z-button" (default mold). Here the new style override:

.z-button {
    color: #FFFFFF;
    font-weight: bold;
    /* omitted */
}

Brief Summary

Based on the above, when upgrading from ZK 6.5 to ZK 7.0 it is required to modify the CSS class names (from z-component-mold to z-component) in most situations. Check Tip 2 Appendix for the complete list of affected CSS classes.

Tip 3: Component Zclass

Some components' zclass-es consist of several parts (separated by dashes "-"), for instance, the zclass of the Window component with embedded mode is "z-window-embedded" and the CSS class of its header part is "z-window-embedded-header". All other modes have corresponding classes following the pattern z-window-mode-header. In order to make it easy to customize, we separate it into two CSS class with "zclass modeclass" pattern.

For example,

<div class="z-window z-window-embedded">
    <div class="z-window-header"></div>
    <div class="z-window-content"></div>
</div>

Then if you want to customize content part of window for all modes, just simply override CSS class z-window-content.

Upgrade sample

In this smalltalk we show how to customize window component's close icon for all modes as follows:

.z-window-embedded-close,
.z-window-overlapped-close,
.z-window-popup-close,
.z-window-highlighted-close,
.z-window-modal-close {
	background: url('../img/wnd-icon.png') no-repeat scroll 0 0;
}
.z-window-embedded-close-over,
.z-window-overlapped-close-over,
.z-window-popup-close-over,
.z-window-highlighted-close-over,
.z-window-modal-close-over {
	background: url('../img/wnd-icon.png') no-repeat scroll 0 -16px;
}

In ZK 7, you can remove -mode part for all modes.

.z-window-close {
	background: url('../img/wnd-icon.png') no-repeat scroll 0 0;
}
.z-window-close:hover {
	background: url('../img/wnd-icon.png') no-repeat scroll 0 -16px;
}

Brief Summary

To adapt this change for ZK 7, check Tip 3 Appendix for the complete list of related changes eliminating CSS classes.

Tip 4: DOM Structure

In ZK 6.5, several components use a 3 x 3 grid structure to achieve rounded corner style. In ZK 7, we applied CSS 3, therefore, the complex 3 x 3 grid structure is no longer needed.

Upgrade Sample

In this smalltalk we show how to customize the window component using CSS 3 based on 3 x 3 grid structure. Originally we had to override several CSS classes (z-component-tl, z-component-tm, z-component-tr, and etc.) to add rounded corners to the window head (line 9).

.z-window-embedded-tl,
.z-window-embedded-tm,
.z-window-embedded-tr {
    /* omitted */
}
.z-window-embedded-hl,
.z-window-embedded-hm,
.z-window-embedded-hr {
    border-radius: 4px 4px 0 0;
    /* omitted */
}
.z-window-embedded-cl,
.z-window-embedded-cm,
.z-window-embedded-cr {
    /* omitted */
}
.z-window-embedded-bl,
.z-window-embedded-bm,
.z-window-embedded-br {
    /* omitted */
}

In ZK 7, the DOM structure of the window component is simplified.

<div class="z-window">
    <div class="z-window-header"></div>
    <div class="z-window-content"></div>
</div>

Therefore, it is sufficient to just override the z-window class, to add rounded corners:

.z-window {
    border-radius: 4px 4px 0 0;
    /* omitted */
}

Brief Summary

To check the style after we removed 3 x 3 grid structure in ZK 7, we recommended using developer tool provided by browser such as Firebug for FireFox, Developer Tools for Chrome to check new DOM structure first, then move your existing customization style into new CSS class. Check Tip 4 Appendix for the complete list that remove 3 x 3 (or 3x1) grid structure..

Tip 5: CSS Class Naming

In ZK 6.5, the CSS class names use abbreviation which sometimes hard to understand what it represents. Hence, to make it more semantic in ZK 7, we use full-naming pattern on CSS class names. For example,

z-component-ver become z-component-vertical,
z-component-cnt become z-component-content,
z-component-seld become z-component-selected,
z-component-over become z-component:hover, or
z-component-disd become z-component[disabled]

Here we can see not only change abbreviation to full name, but also use CSS selector like :hover and attribute selector like [disabled] to make it more intuitive.

Upgrade Sample

In this smalltalk we demonstrate how to customize comboitem style when it is selected by override CSS class z-comboitem-seld in ZK 6.5 as follows:

.z-combobox-pp .z-comboitem-over,
.z-combobox-pp .z-comboitem-seld {
    color: #2BCCDA;
    background-color: #000000;
}

In ZK 7, the CSS class name is change to full name z-comboitem-selected, therefore, you have to modify it as follows:

.z-combobox-popup .z-comboitem:hover,
.z-combobox-popup .z-comboitem-selected {
    color: #2BCCDA;
    background-color: #000000;
}

Brief Summary

In most situation, upgrade to ZK 7.0 from ZK 6.5 based on this change is to modify CSS class name with full naming pattern (from z-component-shortname to z-component-fullname). Check Tip 5 Appendix for the complete list of ZK 7 CSS class naming rule.

Tip 6: Image Icons and Font Icons

In order to reduce page loading time, we use font icons in ZK 7 to replace original image icons. There are a lot of web icon fonts, in ZK 7 we integrate Font Awesome 4.0.1 together. Thus, it is easy to use font icons in ZK application by simply replace prefix fa to z-icon, for example, z-icon-caret-up represents a triangle arrow up font icon.

Upgrade Sample

In this smalltalk, we customize combobox button with custom image as follows:

.z-combobox-btn {
    background: url('../img/combo-btn.png') no-repeat;
}

However, after upgrade to ZK 7, you can see not only the image showed but also the font icon that ZK 7 used by default. To disable the font icon you can override font icon CSS class as follows:

.z-combobox-button {
    background: url('../img/combo-btn.png') no-repeat;
}
.z-combobox-icon {
	display: none;
}

or

.z-combobox-button {
    background: url('../img/combo-btn.png') no-repeat;
}
.z-combobox-icon.z-icon-caret-down:before {
	content: '';
}

Tip 7: Scrollbar

Since ZK 7, we provide custom scrollbar for Grid, Listbox and Tree component by default. Which means you can also customize scrollbar style. Here we will demonstrate how to style it. Or if you do not like custom scrollbar, we will also demonstrate how to disable it and using browser default scrollbar instead.

Customize Scrollbar Style

The custom scrollbar is consists of two buttons to click for scrolling left/right, an indicator to represent current scroll position and a rail to slide indicator. Therefore, we need to override CSS class as follows:

/* Two buttons to click for scrolling left/right */
.z-scrollbar-left, .z-scrollbar-right {
    background: #FFFFFF;
    color: #3AA4C3;
}
.z-scrollbar-left:hover, .z-scrollbar-right:hover {
	background: #3AA4C3;
	color: #FFFFFF;
}
/* An indicator to represent current scroll position */
.z-scrollbar-horizontal .z-scrollbar-indicator {
    background: #3AA4C3;
    border: none;
    top: 2px;
}
/* A rail to slide indicator */
.z-scrollbar-horizontal .z-scrollbar-rail {
    background: #FFFFFF;
}
/* remove font icon */
.z-scrollbar-horizontal .z-scrollbar-icon {
    display: none;
}

Then you can check the customization result.

Use Browser Default scrollbar

To disable custom scrollbar provided by ZK 7. Add the library property called org.zkoss.zul.nativebar in zk.xml and set it to true.

<library-property>
    <name>org.zkoss.zul.nativebar</name>
    <value>true</value>
</library-property>

Tip 2 Appendix

Component ZK 6.5 mold ZK 7 mold
Button os
trendy
default

Textbox
Intbox
Decimalbox
Longbox
Doublebox
Combobox
Bandbox
Datebox
Timebox
Spinner
Doublespinner

default
rounded
default
Splitter default
os
default
Tabbox accordion
accordion-lite
accordion

Tip 3 Appendix

Component ZK 6.5 sample ZK 7 sample
Splitter

z-splitter-hor
z-splitter-ver

z-splitter z-splitter-horizontal
z-splitter z-splitter-vertical

Slider

z-slider-hor
z-slider-ver

z-slider z-slider-horizontal
z-slider z-slider-vertical

Menubar

z-menubar-hor
z-menubar-ver

z-menubar z-menubar-horizontal
z-menubar z-menubar-vertical

Toolbar z-toolbar-tabs z-toolbar z-toolbar-tabs
Combobutton z-combobutton-toolbar z-combobutton z-combobutton-toolbar
Separator

z-separator-horizontal
z-separator-vertical

z-separator z-separator-horizontal
z-separator z-separator-vertical

Groupbox

z-groupbox-3d

z-groupbox z-groupbox-3d

Tabbox

z-tabbox

z-tabbox-ver

z-tabbox-accordion

z-tabbox z-tabbox-horizontal
z-tabbox z-tabbox-horizontal-bottom
z-tabbox z-tabbox-vertical
z-tabbox z-tabbox-vertical-right
z-tabbox z-tabbox-accordion

Window

z-window-embedded
z-window-modal
z-window-highlighted
z-window-overlapped
z-window-popup

z-window z-window-embedded
z-window z-window-modal
z-window z-window-highlighted
z-window z-window-overlapped
z-window z-window-popup

Tip 4 Appendix

Component ZK 6.5 DOM structure ZK 7 DOM structure

Button

Trendy mold
<span class="z-button">
    <table>
        <tr>
            <td class="z-button-tl">
                <button class="z-button" />
            <td class="z-button-tm"></td>
            <td class="z-button-tr"></td>
        </tr>
        <tr>
            <td class="z-button-cl"></td>
            <td class="z-button-cm"></td>
            <td class="z-button-cr"></td>
        </tr>
        <tr>
            <td class="z-button-bl"></td>
            <td class="z-button-bm"></td>
            <td class="z-button-br"></td>
        </tr>
    </table>
</span>
<button class="z-button" />

Caption

<table class="z-caption">
    <tr>
        <td class="z-caption-l"></td>
        <td class="z-caption-r"></td>
    </tr>
</table>
<div class="z-caption">
    <div class="z-caption-content"></div>
</div>

Combobutton

<span class="z-combobutton">
    <table>
        <tr>
            <td class="z-combobutton-tl">
                <button class="z-combobutton" />
            <td class="z-combobutton-tm"></td>
            <td class="z-combobutton-tr"></td>
        </tr>
        <tr>
            <td class="z-combobutton-cl"></td>
            <td class="z-combobutton-cm"></td>
            <td class="z-combobutton-cr">
              <div>
                <div class="z-combobutton-btn-img" />
              </div>
            </td>
        </tr>
        <tr>
            <td class="z-combobutton-bl"></td>
            <td class="z-combobutton-bm"></td>
            <td class="z-combobutton-br"></td>
        </tr>
    </table>
</span>
<span class="z-combobutton">
    <span class="z-combobutton-content">
        <span class="z-combobutton-text" />
        <span class="z-combobutton-button">
            <i class="z-combobutton-icon" />
        </span>
    </span>
</span>

Textbox
Intbox
Decimalbox
Longbox
Doublebox

rounded mold
<i class="z-component-rounded">
    <input class="z-component-rounded-inp" />
    <i class="z-component-rounded-right-edge" />
</i>
<input class="z-component" />

Groupbox

<div class="z-groupbox">
    <div class="z-groupbox-tl">
        <div class="z-groupbox-tr"></div>
    </div>
    <div class="z-groupbox-hl">
        <div class="z-groupbox-hr">
            <div class="z-groupbox-hm">
                <div class="z-groupbox-header"></div>
            </div>
        </div>
    </div>
    <div class="z-groupbox-cnt"></div>
</div>
<div class="z-groupbox">
    <div class="z-groupbox-header"></div>
    <div class="z-groupbox-content"></div>
</div>

Panel

<div class="z-panel">
    <div class="z-panel-tl">
        <div class="z-panel-tr"></div>
    </div>
    <div class="z-panel-hl">
        <div class="z-panel-hr">
            <div class="z-panel-hm">
                <div class="z-panel-header"></div>
            </div>
        </div>
    </div>
    <div class="z-panel-body">
        <div class="z-panel-cl">
            <div class="z-panel-cr">
                <div class="z-panel-cm">
                    <div class="z-panelchildren"></div>
                </div>
            </div>
        </div>
        <div class="z-panel-fl">
            <div class="z-panel-fr">
                <div class="z-panel-fm"></div>
            </div>
        </div>
        <div class="z-panel-bl">
            <div class="z-panel-br"></div>
        </div>
    </div>
</div>
<div class="z-panel">
    <div class="z-panel-head">
        <div class="z-panel-header"></div>
    </div>
    <div class="z-panel-body">
        <div class="z-panelchildren"></div>
    </div>
</div>

Window

<div class="z-window">
    <div class="z-window-tl">
        <div class="z-window-tr"></div>
    </div>
    <div class="z-window-hl">
        <div class="z-window-hr">
            <div class="z-window-hm">
                <div class="z-window-header"></div>
            </div>
        </div>
    </div>
    <div class="z-window-cl">
        <div class="z-window-cr">
            <div class="z-window-cm">
                <div class="z-window-cnt"></div>
            </div>
        </div>
    </div>
    <div class="z-window-bl">
        <div class="z-window-br"></div>
    </div>
</div>
<div class="z-window">
    <div class="z-window-header"></div>
    <div class="z-window-content"></div>
</div>

Tab

horizontal / vertical orient
<li class="z-tab">
    <a class="z-tab-close"></a>
    <div class="z-tab-hl">
        <div class="z-tab-hr">
            <div class="z-tab-hm"></div>
        </div>
    </div>
</li>
<li class="z-tab">
    <a class="z-tab-content">
        <div class="z-tab-button"></div>
        <span class="z-tab-text"></span>
    </a>
</li>

Tip 5 Appendix

Category ZK 6.5 class name ZK 7 class name
Layout Elements -outer -outer
-body -body
-header -header
-inner -inner
-cnt -content
-footer -footer
-noheader -noheader
-noborder -noborder
-nofooter deprecated*
Other Elements -faker -faker
-text -text
-inp -input
-sep -separator
-img -image (for comoponent's API, such as Button.setImage())
-icon (for comopnent's interaction, such as drop-down button on combobox)
-pp -popup
-btn -button
Switch Icons -close -close
-colps -collapse
-colpsd -collapsed
-exp -expand
-expd -expanded
Resize Icons -max -maximize
-maxd -maximized
-min -minimize
-mind deprecated*
Split Icons -splt -splitter
-ns -nosplitter
Orient and Position -ver -vertical
-hor -horizontal
-start -start
-center -center
-end -end
Event Effect -clk :active or -click
-focus :focus or -focus
-over :hover or -hover
-drag -drag
-drop deprecated*
-seld -selected
-ck -checked
-unck -unchecked
-disd [disabled] or -disabled
-visi :visited or -visited
-hide deprecated*
-invalid -invalid
-readonly [readonly] or -readonly
  • deprecated means it is never used

Version History

Last Update : 2013/11/25


Version Date Content
     



Last Update : 2013/11/25

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