ZK Style Customization

Guide
For ZK 8.5.1

PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information.
PDF generated at: Tue, 06 Mar 2018 15:33:17 CST
Contents
Articles
ZK Style Customization Guide 1
Introduction 1
ZK CSS Class Design 1
Sclass 2
Zclass 3
ZK Class Naming Rule 4
By DOM Structure 4
By Event Effect 6
Integrate with LESS 8
Introduction to LESS 8
How ZK works with LESS 9
ZK LESS Variables 10
ZK LESS Functions 16
ZK LESS Syntax Notes 23
Compile LESS 24
Look and Feel Customization 29
Partial customize with Sclass and Zclass 29
Customize Component 31
Button 33
Borderlayout 37
Tabbox 44
Window 52
Navbar 57
Create New Look and Feel 62
Upgrade Customized Style From other ZK Version 65
Upgrade From ZK 6.5 65

References
Article Sources and Contributors 78
Image Sources, Licenses and Contributors 79
ZK Style Customization Guide 1

ZK Style Customization Guide

Documentation:Books/ZK_Style_Customization_Guide

If you have any feedback regarding this book, please leave it here.
<comment>http://books.zkoss.org/wiki/ZK_Style_Customization_Guide</comment>

Introduction
Welcome to ZK, the easiest way to build modern Java web applications.
ZK Style Customization Guide describes the styling concept and design of ZK components. For installation, please
refer to ZK Installation Guide, for concepts, please refer to ZK Essentials. For a full description of component
properties and methods please visit ZK Developer's Reference.
ZK Themes [1] is an open source project that has a collection of various themes, including breeze, silvertail and
sapphire. You could derive your own theme from any of them and it is also a good source to know how a custom
theme works.
For more details about customize theme and how to apply customize CSS, please refer to Theming and Styling.

References
[1] http:/ / code. google. com/ p/ zkthemes/

ZK CSS Class Design

This section describes how ZK design CSS class with Sclass, Zclass and the naming rules.
Sclass 2

Sclass
Styling Class (aka. sclass) is a way to add extra CSS Class to a component. By default, nothing is assigned to sclass
(i.e. empty). Once it is assigned with a non-empty value (HtmlBasedComponent.setSclass(java.lang.String) [1]), it
will be added to the root element as an additional CSS class.
For example, assign sclass foo-pretty to a button component in zul page like this

<!-- index.zul -->

<button sclass="foo-pretty"/>

will generate the following output

<!-- HTML output -->

<button class="z-button foo-pretty" />

Sclass won't change the naming of the default CSS classes, so all the default CSS rules will be applied and inherited.
It is useful to fine-tune a particular component.

Version History
Version Date Content

References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ HtmlBasedComponent. html#setSclass(java. lang. String)
Zclass 3

Zclass
ZK Class (aka., zclass) is a naming pattern. The name assigned to zclass
[1]
(HtmlBaseComponent.setZclass(java.lang.String) ) will be used to name the CSS classes associated with the DOM
structure of a component, including the root and the children. In addition, each kind of components is assigned with
a unique zclass and shipped with all the required CSS rules.
Since zclass is used to name the CSS classes associated DOM elements, all the default CSS rules won't be applied if
zclass is assigned with a different value. Thus, it is used to custom a component with a totally different look.
For example, assign zclass btn to a button component in zul page like this

<!-- index.zul -->

<button zclass="btn"/>

will generate the following output

<!-- HTML output -->

<button class="btn" />

As you can see the default z-button class is missing, which means all CSS rules is removed.

Version History
Version Date Content

References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ HtmlBaseComponent. html#setZclass(java. lang. String)
ZK Class Naming Rule 4

ZK Class Naming Rule

The basic zclass naming pattern of ZK component is "z-component", for example, the zclass of button component is
"z-button". However, each component may consist of many DOM elements and have different interactions.
Therefore, this section will describe details about ZK's class naming rule by DOM elements and interaction effects.

By DOM Structure
The naming pattern of the DOM structure is used to describe components which are composed of more than one
part. The following recommended naming patterns are to clarify the DOM structure of ZK components, not a
limitation.

Layout Elements
The following naming patterns are based on component layout. For example, "z-window-header" means header part
of window component.

-outer:
the exterior of the specified component like splitter in vbox and hbox
-header:
the header content, like grid, tree, listbox, and so on.
-body:
the body content, like grid, tree, listbox, and so on.
-inner:
the interior of the specified component, like slider and tab.
-content:
like window's contentSclass or groupbox's contentSclass
-footer:
describes the footer content, like grid, tree, listbox, and so on.
-noheader:
no header element.
-noborder:
no border element.

Orient and Position Elements

The following naming patterns are based on component orientation and positions. For example,
"z-menubar-horizontal" means the menubar component is in horizontal orientation.
-vertical:
vertical aspect, like menubar.
-horizontal:
horizontal aspect, like menubar.
-start:
beginning aspect, like toolbar.
By DOM Structure 5

-center:
center aspect, like toolbar.
-end:
ending aspect, like toolbar.

Other Elements
The following naming patterns are based on component look and feel and some interaction. For example,
"z-combobox-button" is the drop-down button of combobox component.
-faker:
faker element to mark a reference point at browser side, like grid, listbox, and tree.
-text:
text area.
-input:
input element.
-separator:
separator element.
-image:
image area specified by comoponent's API.
-icon
for component interaction
-popup:
pop-up element, like datebox, combobox, and so on.
-button:
a button.

Tool Icons
The following naming patterns are based on component interactions. For example, "z-panel-close" is a closed icon of
panel component.

Switch Resize Split

By DOM Structure 6

-close: -maximize: -splitter:

describes an icon which is closed, like describes a maximizable icon. describes a splittable
tree, group, an so on. -maximized: icon.
-collapse: describes a maximizable icon -nosplitter:
describes a collapsible icon, like panel. which is maximized. describes a
-collapsed: -minimize: non-splittable icon.

describes a collapsible icon which is describes a minimizable icon.

collapsed, like panel.
-expand:
describes an expandable icon, like
panel.
-expanded:
describes an expandable icon which is
expanded, like panel.

Version History
Version Date Content

By Event Effect
The naming pattern of Event Effect is used to describe the component interactions by input devices such as mouse
and keyboard. Some of the naming patterns uses CSS 3 attribute selector directly.

Mouse Operation
The following naming patterns are based on mouse operation.
:active
mouse clicked event.
:focus or -focus
focused event.
:hover or -hover
mouse over event.
-drag
dragged event.
By Event Effect 7

Component State
The following naming patterns are based on component states.
-selected
selected state.
-checked
checked state.
-checkable
can be checked state.
[disabled] or -disabled
disabled state.
:visited
visited state.
-invalid
invalid state.
[readonly] or -readonly
readonly state.

Version History
Version Date Content
Integrate with LESS 8

Integrate with LESS

This section describes how ZK works with LESS. If you are not familiar with LESS, please visit LESS official site
[1]
to check its usage.

References
[1] http:/ / lesscss. org/

Introduction to LESS
Introduction
LESS is the dynamic stylesheet language. LESS extends CSS with dynamic behavior such as variables, mixins,
operations and functions.[1]
[2] [2]
LESS was developed by Alexis Sellier , more commonly known as cloudhead . It is now maintained and
extended by the LESS core team. [3]

Basic Usage
[4]
The following content demonstrates simple usages of LESS, please refer to LESS official site for more details.
You can also try it online from http://less2css.org/

Variables
Define variables with "@" sign and use it as follows:

@green: #46A546;

.greendiv {
background: @green;
}

will output

.greendiv {
background: #46A546;
}

Mixins
Define a mixins as follows:

.top-border-radius(@size) {
-webkit-border-radius: @size @size 0 0;
-moz-border-radius: @size @size 0 0;
border-radius: @size @size 0 0;
}
Introduction to LESS 9

.topRoundedDiv {
.top-border-radius(5px);
}

will output

.topRoundedDiv {
-webkit-border-radius: 5px 5px 0 0;
-moz-border-radius: 5px 5px 0 0;
border-radius: 5px 5px 0 0;
}

References
[1] http:/ / lesscss. org/
[2] http:/ / cloudhead. io/
[3] http:/ / lesscss. org/ #about
[4] http:/ / lesscss. org

Version History
Version Date Content

How ZK works with LESS

This section will introduce how ZK integrate with LESS and compile LESS to *.css.dsp files (Think of them as
normal CSS files that could utilize JSP taglib functionality).
ZK LESS Variables 10

ZK LESS Variables
LESS variables defined here are for ZK's default theme - Breeze. You can change these variables when customizing
a theme with a new look and feel.

Typography
Define base font styles including font family, font size and line-height.

// Font Family
@baseTitleFontFamily: "Helvetica Neue", Helvetica, Arial,
sans-serif;
@baseContentFontFamily: Arial, Sans-serif;

// Font Size
@baseFontSize: 14px;
@fontSizeLarge: floor(@baseFontSize * 1.15); // 16px
@fontSizeMedium: ceil(@baseFontSize * 0.85); // 12px
@fontSizeSmall: floor(@baseFontSize * 0.8); // 11px

// Line Height
@baseLineHeight: 14px;

Component sizing
Define base width and height.

// Component Height
@baseHeight: 8px;
@baseIconHeight: @baseHeight * 2; // 16px
@baseButtonHeight: @baseHeight * 3; // 24px
@baseBarHeight: @baseHeight * 4; // 32px
@baseTitleHeight: @baseHeight * 5; // 40px

// Component Width
@baseWidth: 8px;
@baseIconWidth: @baseWidth * 2; // 16px
@baseButtonWidth: @baseWidth * 3; // 24px
@baseBarWidth: @baseWidth * 4; // 32px

// Border Radius
@baseBorderRadius: 4px;
@borderRadiusLarge: 6px;
@borderRadiusSmall: 3px;
ZK LESS Variables 11

Component Basic Coloring

Define text color, border color, background color and gradient colors.

// Text color
@baseTextColor: #000000;
@textColorGray: #555555;
@textColorGrayDark: #363636;
@textColorGrayLight: #636363;

// Border color
@baseBorderColor: #CFCFCF;
@headerBorderColor: #9C9C9C;

// Background color
@baseBackgroundColor: #FFFFFF;
@headerBackgroundColor: @baseBackgroundColor;

// Gradient background
@baseGradientStart: #FEFEFE;
@baseGradientEnd: #EEEEEE;

Icon Font
Define icon's font color (all icon font used in ZK comes from font-awesome [1]).

// Icon Font
@iconColor: #636363;
@iconHoverColor: #636363;
@iconDisabledColor: #AAAAAA;

Component State
Define style for component states: active, focus, hover, disabled, invalid, read-only, selected, selectedhover,
checked, and collapsed.

// Active
@activeColor: @baseTextColor;
@activeBorderColor: #499EB3;
@activeBackgroundColor: #86E2F9;

// Focus
@focusColor: @baseTextColor;
@focusBorderColor: #00B9FF;
@focusBackgroundColor: @baseGradientEnd;

// Hover
@hoverColor: @textColorGrayLight;
@hoverBorderColor: #8FB9D0;
@hoverBackgroundColor: #D6F0FD;
ZK LESS Variables 12

// Disabled
@disabledColor: #AAAAAA;
@disabledBackgroundColor: #F0F0F0;

// Invalid
@invalidBorderColor: #DD7777;

// Read-only
@readonlyBorderColor: #E6E6E6;
@readonlyBackgroundColor: #FAFAFA;

// Selected
@selectedColor: @textColorGrayLight;
@selectedBorderColor: @baseBorderColor;
@selectedBackgroundColor: #BEE7FC;

// Selected Hover
@selectedHoverColor: @textColorGrayLight;
@selectedHoverBorderColor: @baseBorderColor;
@selectedHoverBackgroundColor: #C5E7F8;

// Checked
@checkedColor: #2184BA;
@checkedBorderColor: #8E8F8F;
@checkedBackgroundColor: #F8F8F8;

// Collapsed
@collapsedBorderColor: @baseBorderColor;
@collapsedBackgroundColor: #FCFCFC;

Component Independent Variables

Above described are common variables that are shared among every component. Below we will define independent
variables that uniquely belongs to each individual component.

Button, Input, Table

Define global border and background style for specific DOM element buttons, inputs, and tables.

// Button
@buttonBorderColor: #A9A9A9;
@buttonGradientStart: #FEFEFE;
@buttonGradientEnd: #EEEEEE;
// Input
@inputBorderColor: @baseBorderColor;
@inputBackgroundColor: @baseBackgroundColor;
// Table
ZK LESS Variables 13

@meshTitleBorderColor: @baseBorderColor;
@meshContentBorderColor: #FFFFFF;
@meshBackgroundColor: #FFFFFF;
@meshStripeBackgroundColor: #F7F7F7;
@meshFootBackgroundColor: #FAFAFA;
@meshTitleHoverStart: #F2F9FE;
@meshTitleHoverEnd: #D6F0FD;
@meshContentHoverStart: #F2F9FE;
@meshContentHoverEnd: #D6F0FD;

Container Components
// window
@windowBorderColor: #9C9C9C;
@windowBackgroundColor: #D9E5EF;
@windowFramePadding: 4px;

// tabbox
@tabSelectedBackgroundColor: #FFFFFF;

// panel
@panelBorderColor: #9C9C9C;
@panelBackgroundColor: #E1EDF4;
@panelBodyBackground: #F0F6F9;

Data Components
// group (group, listgroup)
@groupGradientStart: #FFFFFF;
@groupGradientEnd: #E9F2FB;

// paging
@pagingColor: @textColorBlue;
@pagingSelectedColor: @textColorGrayDark;
@pagingBorderColor: @baseBorderColor;
@pagingActiveBorderColor: #A9A9A9;
@pagingBackgroundColor: #FAFAFA;
@pagingSelectedBackgroundColor:#E6E6E6;

// biglistbox
@biglistboxBackgroundColor: #F0F0F0;
@biglistboxFrozenBackground: #E0E0E0;

// mesh for ie8

@meshBackgroundColorIE8: #F5F5F5;
@meshHoverBackgroundColorIE8: #E5F7FF;
@meshSelectedBackgroundColorIE8: #E5F7FF;
@meshSelectedHoverBackgroundColorIE8: #D9F2FF;
ZK LESS Variables 14

@meshGroupBackgroundColorIE8: #EDF6FF;
@meshGroupFooterBackgroundColorIE8: #F2F9FF;

Essential Components
// popup
@popupBorderColor: @baseBorderColor;
@popupBackgroundColor: @baseBackgroundColor;
@popupGradientStart: @baseBackgroundColor;
@popupGradientEnd: #F5F5F5;

// notification
@notificationInfoColor: rgba(33, 155, 166, 0.88);
@notificationWarningColor: rgba(234, 67, 23, 0.88);
@notificationErrorColor: rgba(190, 0, 5, 0.88);
@notificationArrowColor: rgba(51, 51, 51, 0.9);
@notificationInfoColorIE8: rgb(33, 155, 166);
@notificationWarningColorIE8: rgb(234, 67, 23);
@notificationErrorColorIE8: rgb(190, 0, 5);
@notificationArrowColorIE8: rgb(51, 51, 51);

// menu
@menuImageSize: 16px;
@menuActiveBorderColorTR: #838383;
@menuActiveBorderColorBL: #B6B6B6;
@menuPopupBackground: #FAFAFA;
@menuSeparatorBorderColor: #838383;
@menuSeparatorBackgroundColor: #B8B8B8;
@menuPopupSeparatorBorder: #FFFFFF;
@menuPopupSeparatorBackground: #E0E0E0;

// navbar
@navImageSize: 16px;
@navColor: #333333;
@navBorderColor: #F4F4F3;
@navBackgroundColor: #FFFFFF; //first level, each level is 3%
darker (darken(@navBackgroundColor, 3 * level));
@navHoverBackgroundColor: #E8E8E8;
@navSelectedColor: #FFFFFF;
@navSelectedBackgroundColor: #372F2B;
@navSeparatorColor: #838383;
@navCollapsedWidth: 32px;
ZK LESS Variables 15

Input Components
// calendar
@calendarTitleColor: @textColorGrayLight;
@calendarTitleHoverColor: @textColorGrayLight;
@calendarCellColor: @textColorGrayLight;
@calendarSelectedColor: #008BB6;
@calendarSelectedHoverColor: #008BB6;
@weekendColor: @textColorOrange;
@weekendBackgroundColor: #F2F2F2;
@weekColor: @textColorGrayLight;
@weekofyearColor: #FFFFFF;
@weekofyearBackgroundColor: #636363;

// slider
@sliderBorderColor: @baseBorderColor;
@sliderActiveBorderColor: #838383;

// errorbox (input constraint)

@errorboxColor: #990000;
@errorboxBorderColor: #990000;
@errorboxBackgroundColor: #FFEEEE;

// progressmeter
@progressmeterGradientStart: #E8F6FD;
@progressmeterGradientEnd: #C6E9FA;

// colorbox
@colorboxBorderColor: #9C9C9C;

// chosenbox
@chosenboxItemBorderColor: #B3B3B3;
@chosenboxCreateIconColor: @textColorGreen;

Layout Components
// splitter (hbox, vbox, borderlayout)
@splitterSize: 8px;
@splitterGradientStart: #FDFDFD;
@splitterGradientEnd: #F1F1F1;

Misc Components
// mask and loading
@maskBackgroundColor: #E0E1E3;
@loadingBackgroundColor: #E3E3E3;

// scrollbar
@scrollbarWidth: 16px;
ZK LESS Variables 16

@scrollbarHeight: 16px;
@scrollbarBorderColor: #838383;
@scrollbarBackgroundColor: #DDDDDD;
@scrollbarGradientStart: #FFFFFF;
@scrollbarGradientEnd: #CFCFCF;

// drag and drop

@dragColor: #FFFFFF;
@dragBackgroundColor: #E0EAF0;
@dragHoverBackgroundColor: #ADD2FF;
@dragAllowBorderColor: #11AA33;
@dragAllowBackgroundColor: #11AA33;
@dragDisAllowBorderColor: #C13634;
@dragDisAllowBackgroundColor: #C13634;

Version History
Version Date Content

References
[1] http:/ / fortawesome. github. io/ Font-Awesome/

ZK LESS Functions
ZK DSP Functions
ZK provides many useful theme functions that can be used in DSP files. Here we will introduce these functions that
are used for CSS style.

Core Functions
Core functions are defined in core.dsp.tld [1]. Here we will only introduce functions that are related to CSS style. To
use these functions in a DSP page, declare tag library with it's prefix as follows:

<%-- *.css.dsp file --%>

<%@ taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c" %>
ZK LESS Functions 17

Function Usage

encodeURL <%-- Background image from ZK JAR file --%>

.myDiv {
background: ${c:encodeURL('~./path/to/image.png')};
}
encodeThemeURL <%-- Background image from Theme JAR file --%>
.myDiv {
background: ${c:encodeThemeURL('~./path/to/image.png')};
}
if <%-- If Statement for Specific Browser --%>
.myDiv {
background: rgba(200, 200, 200, 0.8);
<c:if test="${zk.ie <= 8}">
<%-- ie8 doesn't support rgba --%>
background: rgb(200, 200, 200);
</c:if>
}

Theme Functions
Theme functions are defined in theme.dsp.tld [2].These functions are focused on CSS 3 supported styles. To use
these functions in a DSP page, declare tag library with it's prefix as follows:

<%-- *.css.dsp file --%>

<%@ taglib uri="http://www.zkoss.org/dsp/web/theme" prefix="t" %>

Function Usage

gradient <%-- Gradient Background --%>

.myDiv {
${t:gradient('ver', '#FFFFFF 0%; #EEEEEE 100%')};
}
box <%-- Flexible Box Layout Module --%>
box2 .myDiv1 {
box3 ${t:box('box-flex', '1')};
}
.myDiv2 {
${t:box2('box-flex', '1', 'box-orient', 'horizontal')};
}
.myDiv3 {
${t:box3('box-flex', '1', 'box-orient', 'horizontal', 'box-pack',
'center')};
}
boxShadow <%-- Box Shadows --%>
.myDiv {
${t:boxShadow('1px 1px 0 rgba(0, 0, 0, 0.2)')};
}
borderRadius <%-- Rounded Corners --%>
.myDiv {
${t:borderRadius('5px')};
}
ZK LESS Functions 18

transform <%-- Transform --%>

.myDiv {
${t:transform('translate3d(0, 0, 0)')};
}
applyCSS3 <%-- Apply all the other CSS 3 styles --%>
.myDiv {
${t:applyCSS3('transition-property', 'opacity')};
${t:applyCSS3('transition-duration', '350ms')}
}

ZK LESS Function
Since ZK LESS engine compile LESS files into DSP pages, you can use the DSP functions mentioned above inside a
LESS file. These functions are already defined to ZK LESS mixins. To use ZK LESS mixins, simply import
_zkmixins.less in your *.less file.
For example,

@import "~./zul/less/_zkmixins.less";

/* omitted */

Here we define mixins according to Core Functions and Theme Functions and extra useful mixins:

Core Functions in Mixins

Function Usage and Output

Background Usage
Image
.z-component1 {
.encodeURL(background-image, '~./path/to/image1.png');
}
.z-component2 {
.encodeThemeURL(background-image, '~./path/to/image2.png');
}
.z-component3 {
.encodeThemeURL(background, '~./path/to/image3.png', center center);
}

Output

.z-component1 {
background-image: url(${c:encodeURL('~./path/to/image.png')});
}
.z-component2 {
background-image: url(${c:encodeThemeURL('~./path/to/image.png')});
}
.z-component3 {
background: url(${c:encodeThemeURL('~./path/to/image.png')}) center
center;
}
ZK LESS Functions 19

Theme Functions in Mixins

Function Usage and Output

Gradient Usage
Background
.z-component1 {
.gradient('ver', '#333333 0%; #555555 50%; #666666 100%');
}
.z-component2 {
.horGradient(#333333, #666666);
}
.z-component3 {
.verGradient(#333333, #666666);
}
.ie8 .z-component4 {
.gradientFallback(#333333, #666666);
}
.z-component1:hover {
.resetGradient();
background: #777777;
}

Output

.z-component1 {
${t:gradient('ver', '#333333 0%; #555555 50%; #666666 100%')};
}
.z-component2 {
${t:gradient('hor', '#333333 0% #666666 100%')};
}
.z-component3 {
${t:gradient('ver', '#333333 0% #666666 100%')};
}
.ie8 .z-component4 {
/* average of #333333 and #666666 */
background: #4d4d4d;
}
.z-component1:hover {
background: none;
filter: progid:DXImageTransform.Microsoft.gradient(enabled=false);
background: #777777;
}
ZK LESS Functions 20

Rounded Usage
Corner
.z-component1 {
.borderRadius(3px);
}
.z-component2 {
.topBorderRadius(3px);
}
.z-component3 {
.rightBorderRadius(3px);
}
.z-component4 {
.bottomBorderRadius(3px);
}
.z-component5 {
.leftBorderRadius(3px);
}

Output

.z-component1 {
${t:borderRadius('3px 3px 3px 3px')};
}
.z-component2 {
${t:borderRadius('3px 3px 0 0')};
}
.z-component3 {
${t:borderRadius('0 3px 3px 0')};
}
.z-component4 {
${t:borderRadius('0 0 3px 3px')};
}
.z-component5 {
${t:borderRadius('3px 0 0 3px')};
}
Box Shadow Usage

.z-component {
.boxShadow(inset 1px 1px 0 #222222);
}

Output

.z-component {
${t:boxShadow('inset 1px 1px 0 #222222')};
}

Other Useful Mixins

ZK LESS Functions 21

Function Usage and Output

Element Size Usage

.z-component1 {
.size(16px, 16px);
}
.z-component2 {
.displaySize(inline-block, 16px, 16px);
}

Output

.z-component1 {
width:16px;
height: 16px;
}
.z-component2 {
display: inline-block;
width:16px;
height: 16px;
}
Font Style Usage

@fontFamily: Arial, Sans-serif;

.z-component-text {
.fontStyle(@fontFamily, 14px, 600, #555555);
font-style: italic;
}
.z-component-iconfont {
.iconFontStyle(12px, #ACACAC);
}

Output

.z-component-text {
font-family: Arial, Sans-serif;
font-size: 14px;
font-weight: 600;
font-style: normal;
color: #555555;
font-style: italic; /* override */
}
.z-component-iconfont {
font-size: 12px;
color: #ACACAC;
}
ZK LESS Functions 22

Opacity Usage

.z-component1 {
.opacity(1);
}
.z-component2 {
.opacity(0.6);
}

Output

.z-component1 {
opacity: 1;
filter: alpha(opacity=100);
}
.z-component2 {
opacity: 0.6;
filter: alpha(opacity=60);
}

Version History
Version Date Content

References
[1] http:/ / github. com/ zkoss/ zk/ blob/ master/ zweb/ src/ archive/ web/ WEB-INF/ tld/ web/ core. dsp. tld
[2] http:/ / github. com/ zkoss/ zk/ blob/ master/ zweb/ src/ archive/ web/ WEB-INF/ tld/ web/ theme. dsp. tld
ZK LESS Syntax Notes 23

ZK LESS Syntax Notes

Be aware of using control-flow tags like <c:if>
If you are using control-flow tags like <c:if> in your ZK-Less files, you have to be really care with the situations like
below:

.z-selector {
border-left-color: @border;
<c:if test="${zk.ie == 8}">
border-left-color: @border4IE8;
</c:if>
}

If @border and @border4IE8 happens to be the same, Less will optimize them and only keep the last expression
while compiling. Therefore, the above Less expression is equivalent to the following:

.z-selector {
// removed by less
<c:if test="${zk.ie == 8}">
border-left-color: red;
</c:if>
}

So, to be safe, please change the order of your Less expressions like this:

.z-selector {
<c:if test="${zk.ie == 8}">
border-left-color: @border4IE8;
</c:if>
border-left-color: @border;
}

Here, when @border and @border4IE8 are the same, the compiled CSS looks like:

.z-selector {
<c:if test="${zk.ie == 8}">
</c:if>
border-left-color: red;
}

and if they are different, the result is:

.z-selector {
<c:if test="${zk.ie == 8}">
border-left-color: red;
</c:if>
border-left-color: rgba(rr,gg,bb,aa); // IE8 will ignore this
}

Remember to always place your control-flow tags first to avoid any possible errors like the example showed.
ZK LESS Syntax Notes 24

Version History
Version Date Content

Compile LESS
Install Node.js
Node.js is now required for our ZK-Less Engine since ZK 7.0.3.
If you don't have Node.js installed yet, please follow the steps given by the official-website [1] to install Node.js.
Node version 0.10.30 or above is required. To check your Node.js version, simply run:

node --version

Compile LESS to DSP

Here we introduce two ways to compile LESS files to DSP files. One is by Ant and the other is by Maven.
You could choose either one of them depends on your preferences.

Compile LESS by Ant

• Have Node.js installed in your environment.
• Follow the online document [2] to install Apache Ant.
• Download the following necessary jars into your project/lib folder from zk repository [3] (right click -> save as).
• yuicompressor.jar
• zkjszips.jar
• commons-io.jar
• CssCompressor.jar
• zul.jar (extract zk-bin-7.0.X.zip file from sourceforge [4])
• Execute the following command under your project folder to install ZK-Less' node package.

cd project_folder
npm install zkless-engine

• Write an ant script build.xml file like the following sample under project folder, and change the input folder and
output folder as needed.

<?xml version="1.0"?>
<project name="less.compile" default="lessc" basedir=".">
<target name="lessc">
<exec executable="node">
<!-- location of the engine's core file -->
<arg value="${basedir}/node_modules/zkless-engine/lib/CpLess.js"/>
<!-- input folder that contains less files-->
<arg value="${basedir}/src/main/webapp"/>
<!-- output folder -->
Compile LESS 25

<arg value="${basedir}/src/main/webapp"/>
<!-- path of zul.jar -->
<arg value="${basedir}/lib/zul.jar"/>
</exec>
<!-- compress the result using zk's Css Compressor -->
<java classname="CompressCss" fork="true">
<!-- input folder (same as above) -->
<arg value="${basedir}/src/main/webapp"/>
<!-- output folder (same as above) -->
<arg value="${basedir}/src/main/webapp"/>
<classpath>
<!-- required jars -->
<pathelement location="${basedir}/lib/zkjszips.jar"/>
<pathelement location="${basedir}/lib/yuicompressor.jar"/>
<pathelement location="${basedir}/lib/commons-io.jar"/>
<pathelement location="${basedir}/lib/CssCompressor.jar"/>
</classpath>
</java>
</target>
</project>

• Execute ant command in command line tool, i.e:

cd project_folder
ant lessc

Compile LESS by Maven

• Have Node.js installed in your environment.
• Execute the following command to install the native LESS engine by Less.js [1]

npm install -g less

• Modify pom.xml in maven project

<!-- Add Plugin Repository -->

<pluginRepositories>
<pluginRepository>
<id>zkmaven</id>
<name>ZK Maven Plugin Repository</name>
<url>http://mavensync.zkoss.org/maven2/</url>
</pluginRepository>
</pluginRepositories>
<dependencies>
<!-- only needed if using _zkmixins.less provided by ZK -->
<dependency>
<groupId>org.zkoss.zk</groupId>
<artifactId>zul</artifactId>
<version>7.0.3</version>
Compile LESS 26

</dependency>
</dependencies>
<build>
<plugins>
<!-- Add zkless-engine-maven-plugin -->
<plugin>
<groupId>org.zkoss.maven</groupId>
<artifactId>zkless-engine-maven-plugin</artifactId>
<version>0.9.6</version>
<executions>
<execution>
<id>compile-less</id>
<goals>
<goal>lessc</goal>
</goals>
<configuration>
<!-- LESS source folder -->
<sourceDirectory>
${project.basedir}/src/main/resources
</sourceDirectory>
<!-- *.CSS.DSP output folder -->
<outputDirectory>
${project.basedir}/src/main/resources
</outputDirectory>
<!-- Compress Option, default is true -->
<!-- <compress>false</compress> -->
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

• Execute mvn install command to trigger LESS compilation.

Compile LESS to DSP during Development phase

It is not friendly to debug LESS during development by running Ant or Maven each time you modify your LESS
files.
Therefore, we provide a servlet named ZKLessServlet that can be used in web project to develop LESS by simply
refreshing the browser page.
Note: This is only recommended in development environment.
Steps to use ZKLessServlet within a Maven Project:
• Have Node.js installed in your environment.
• Install the native LESS engine by the following command:

npm install -g less

Compile LESS 27

• Add maven dependency if you are using maven.

<repositories>
<repository>
<id>ZK CE</id>
<name>ZK CE Repository</name>
<url>http://mavensync.zkoss.org/maven2</url>
</repository>
<!-- omitted other repository -->
</repositories>
<dependencies>
<dependency>
<groupId>org.zkoss.maven</groupId>
<artifactId>zkless-servlet</artifactId>
<version>0.9.6</version>
</dependency>
<!-- omitted other dependency -->
</dependencies>

• Add servlet settings in web.xml

<web-app>
<!-- omitted other servlets -->
<servlet>
<servlet-name>zkLess</servlet-name>
<servlet-class>org.zkoss.less.ZKLessServlet</servlet-class>
<init-param>
<param-name>org.zkoss.less.LessResource</param-name>
<!-- specify to the folder that contains *.less -->
<param-value>/less</param-value>
</init-param>
<init-param>
<param-name>org.zkoss.less.OutputFormat</param-name>
<!-- specify output file suffix, default .css.dsp -->
<param-value>.css.dsp</param-value>
</init-param>
<init-param>
<param-name>org.zkoss.less.CompressOutput</param-name>
<!-- compress output, default true -->
<param-value>true</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>zkLess</servlet-name>
<!-- specify to folder that contains *.less -->
<url-pattern>/less/*</url-pattern>
</servlet-mapping>
</web-app>
Compile LESS 28

• Project structure and use LESS directly in zul page.

Remember to put all your LESS files and import resources under webapp/less which is the folder specified in
web.xml
Project structure should look like the following:

zkMavenWebProject - src/main/webapp
WEB-INF
web.xml
zk.xml
less
test.less
pages
test.zul

• Use test.less inside test.zul as follows

<!-- test.zul -->

<?link rel="stylesheet" href="../less/test.less"?>
<zk>
<button label="test" />
</zk>

• Now you can modify LESS and see the result by refreshing your browser page.

Version History
Version Date Content

References
[1] http:/ / nodejs. org/
[2] http:/ / ant. apache. org/ manual/ install. html
[3] https:/ / github. com/ zkoss/ zk/ tree/ 7. 0-Stable/ dist/ lib/ ext
[4] http:/ / sourceforge. net/ projects/ zk1/ files/ ZK/
Look and Feel Customization 29

Look and Feel Customization

This section will demonstrate how to customize look and feel of ZK components.

Partial customize with Sclass and Zclass

Partial customization is a convenient way to fast prototype the look and feel and to change the style of a specific
component. Here we will demonstrate how to you can execute partial customization by using Sclass and Zclass.

Using Sclass
Using sclass is very easy, simply add another CSS class name within the component in line 8:

<zk>
<style>
.mybutton {
border-radius: 10px;
background: linear-gradient(to bottom, #f0f9ff 0%,#a1dbff 100%);
}
</style>
<button label="Test Sclass" sclass="mybutton" />
<button label="Default" />
</zk>

We can see that only the first button has been applied .mybutton style.

Using Zclass
Normally, zclass is used to customize a totally different look and feel to that of the default one. For example, if you
only apply border-radius and gradient background style like the following

<zk>
<style>
.mybutton {
border-radius: 10px;
background: linear-gradient(to bottom, #f0f9ff 0%,#a1dbff 100%);
}
</style>
<button label="Test Zclass" zclass="mybutton" />
<button label="Default" />
</zk>

you can see that the button looses its default style such as font size and border style as illustrated below:
Partial customize with Sclass and Zclass 30

Note: Applying zclass will lose all default styles, make sure you really want to customize the entire look and feel of
the component before you do this.

Advanced Usage
Some components have complex DOM structures, therefore sometimes you cannot override the style by just using
sclass as described above. For example, if we try to style menu text color to blue and we use sclass to do the job:

<zk>
<style>
.mymenu {
color: blue;
}
</style>
<menubar id="menubar" hflex="min">
<menu label="Custom Style" sclass="mymenu">
<!-- omitted -->
</menu>
<menu label="Default Style">
<!-- omitted -->
</menu>
</menubar>
</zk>

you can see that the style is not applied.

However, we can use CSS class rule with "sclass zclass" pattern to achieve this goal. Modify the style like the
following:

<zk>
<style>
.mymenu .z-menu-text {
color: blue;
}
</style>
<menubar id="menubar" hflex="min">
<menu label="Custom Style" sclass="mymenu">
<!-- omitted -->
</menu>
<menu label="Default Style">
<!-- omitted -->
</menu>
</menubar>
</zk>

the style is now correctly applied.

Partial customize with Sclass and Zclass 31

Version History
Version Date Content

Customize Component
We have introduced how to execute partial customization with sclass for specific components. Now we will
introduce how to customize component style by LESS and make it the default style inside a project. Subsections are
detailed samples on how you can customize components.

Before you Start

Modern browsers (such as Chrome, Firefox with Firebug) provide useful debugging tools. By pressing F12, you will
be able to see the complete DOM structure and all required information for doing Component Customization. If any
information is not given in the documentation, use the developer tool.

Prepare ZKLess Servlet and ZKLess Dependencies

• Before start customizing your own component styles, first, follow the instruction, compile LESS to DSP during
development phase [1] to have your ZKLess Servlet ready.
• Second, download _header, _zkvariables, and _zkmixins from github [2] and put them into
project/less/web/zul/less
• The project structure should look like this:
Customize Component 32

Step to Customize Component by LESS

Here we will use Window component as an example to demonstrate how to customize a component.
• 1. Link to Window Component page or use browser's developer tool to check the DOM structure.
• 2. Create window.less file under less folder in ZK web project.
• The project structure (here we use maven project)

• Copy LESS content into window.less file from Github [3].

• 3. Tweak window style and Check window style at runtime by ZK Less Servlet.
• Modify window.less to customize look and feel of the Window component, for example, change its
background color and padding by re-defining LESS variables as follows:

@import "~./zul/less/_header.less";

@windowBackgroundColor: #D9E5EF;
@windowFramePadding: 8px;

/* omitted */

• Follow this instruction to add ZKLessServlet to web.xml to compile less at runtime.

• Use window.less in window.zul page as follows to check the style modification.

<?link rel="stylesheet" href="../less/window.less"?>

<zk>
<window title="Customize Window">
Window Content
</window>
</zk>

• Once the server is started, window.less will be compiled into window.css.dsp in the same folder.
• Continue to customize Window component and check the style changes by simply refreshing the browser.
• 4. Use final style in production.
• Remove <?link rel="stylesheet" href="../less/window.less"?> in window.zul page.
• Remove ZK Less Servlet settings in web.xml.
Customize Component 33

• Enable DSP Loader Servlet in web.xml

• Put window.css.dsp files (can be found under less folder) wherever you want. Then add the following settings
in zk.xml file.

<desktop-config>
<theme-uri>/less/window.css.dsp</theme-uri>
</desktop-config>

References
[1] http:/ / books. zkoss. org/ wiki/ ZK_Style_Customization_Guide/ Integrate_with_LESS/ How_ZK_works_with_LESS/
Compile_LESS#Compile_LESS_to_DSP_during_Development_phase
[2] https:/ / github. com/ zkoss/ zk/ tree/ master/ zul/ src/ archive/ web/ zul/ less
[3] http:/ / github. com/ zkoss/ zk/ blob/ master/ zul/ src/ archive/ web/ js/ zul/ wnd/ less/ window. less

Button
Component Reference
Component Reference: Button

DOM Structure
<button class="z-button">
<img class="z-button-image" />
</button>

LESS Source
Basically, LESS source is correspondent to it's DOM structure, each state also have different styles.

.z-button {
/* normal style */

/* hover style */
&:hover {
}
/* focus style */
&:focus {
}
/* active style */
&:active {
}
/* disabled style */
&[disabled] {
}
}

Check complete LESS source for Button from Github [1].

Button 34

LESS Variables
The following LESS variables are used for the Button component. Check other variables from here.

Variables Default Value

@baseButtonHeight 24px

@buttonBorderColor #A9A9A9

@buttonGradientStart #FEFEFE

@buttonGradientEnd #EEEEEE

Customize Sample

Target Design
Assume the image below is our target design for Button component. No border, gradient background, rounded corner
or shadow effects.

Implementation Details

Setup environment and Analyze design

• Check the instruction to setup component customization environment.
• Analyze the design
• Used Color
Text: 14px, #FFFFFF
Normal Background: #5687A8
Hover Background: #5E94B8
Pressed Background: #4C7895
Focus Background: #436983
Disabled Background: #ACACAC
• Size
Height: 32px
Horizontal Padding: 16px
Vertical Padding: 4px
Button 35

Modify button.less file to achieve target design

Refer here for built-in zk less functions.

• Change text color and remove border and text-shadow effect:

.z-button {
.fontStyle(@baseTitleFontFamily, 14px, normal, #FFFFFF);
text-shadow: none; /* remove text shadow */
border: none;
/* omitted */
}

• Remove rounded corner:

.z-button {
.borderRadius(0);
}

• Modify Normal state background:

.z-button {
.verGradient(#5687A8, #5687A8); /* no gradient, pass the same color
arguments for the function */
}

• Modify Hover state:

.z-button {
&:hover {
color: #FFFFFF;
.verGradient(#5E94B8, #5E94B8); /* no gradient, pass the same
color arguments for the function */
.boxShadow(inset 0 -2px 0 #436983); /* for simulation 3d effect
*/
}
}

• Modify Pressed state:

.z-button {
&:active {
color: #FFFFFF;
.verGradient(#4C7895, #4C7895); /* no gradient, pass the same
color arguments for the function */
.boxShadow(inset 0 2px 0 #3A5B72); /* for simulation 3d effect
*/
}
}

• Modify Focus state:

.z-button {
&:focus {
Button 36

color: #FFFFFF;
.verGradient(#436983, #436983); /* no gradient, pass the same
color arguments for the function */
.boxShadow(none);
}
}

• Modify Disabled state:

.z-button {
&[disabled] {
color: #FFFFFF;
.verGradient(#ACACAC, #ACACAC); /* no gradient, pass the same
color arguments for the function */
.boxShadow(none);
.opacity(1); /* no opacity needed */
}
}

• Modify Size:

.z-button {
/* omitted */
min-height: 32px;
padding: 4px 16px;
}

Final result

Additional Customization
If icon font is used inside a button component as below:

<button label="Button" iconSclass="z-icon-flag" />

The icon color is same as label by default, if you wish to change icon color only, add extra style like this:

.z-button {
/* omitted */

> [class*="z-icon-"] {
color: red;
}
Button 37

Version History
Version Date Content

References
[1] http:/ / github. com/ zkoss/ zk/ blob/ master/ zul/ src/ archive/ web/ js/ zul/ wgt/ less/ button. less

Borderlayout
Component Reference
Component Reference: Borderlayout, North, South, Center, West, East

DOM Structure
<div class="z-borderlayout">
<!-- North -->
<div>
<div class="z-north">
<div class="z-north-header">
<i class="z-borderlayout-icon z-icon-chevron-up"></i>
</div>
<div class="z-north-body"></div>
</div>
<div class="z-north-splitter">
<span class="z-north-splitter-button">
<i class="z-north-icon z-icon-ellipsis-horizontal"></i>
<i class="z-north-icon z-icon-caret-up"></i>
<i class="z-north-icon z-icon-ellipsis-horizontal"></i>
</span>
</div>
<div class="z-north-collapsed">
<i class="z-borderlayout-icon z-icon-chevron-down"></i>
</div>
</div>
<!-- South (same as North) -->
<!-- East (same as North) -->
<!-- West (same as North) -->
<!-- Center -->
<div>
<div class="z-center">
<div class="z-center-header"></div>
<div class="z-center-body"></div>
Borderlayout 38

</div>
</div>
</div>

• Line 6: Chevron-direction Icon Font used for North, South, East and West.
North: Chevron-up [1]
South: Chevron-down [2]
West: Chevron-left [3]
East: Chevron-right [4]
• Line 12, 14: Ellipsis-horizontal Icon Font [5] used for North and South, Ellipsis-vertical Icon Font [6] used for East
and West.
• Line 13: Caret-direction Icon Font used forNorth, South, East and West.
North: Caret-up [7]
South: Caret-down [8]
West: Caret-left [9]
East:Caret-right [10]
• Line 18: Chevron-direction Icon Font used for Collapsed North, South, East and West.
South: Chevron-up [1]
North: Chevron-down [2]
East: Chevron-left [3]
West: Chevron-right [4]

LESS Source
Basically, LESS source is correspondent to its DOM structure. North, South, East and West have different styles.

/* borderlayout and it's icon */

.z-borderlayout {
&-icon {}
}
/* North, South, East, West and Center style */
.z-north,
.z-south,
.z-west,
.z-east,
.z-center {
&-header {}
&-body {}
}
.z-north,
.z-south,
.z-west,
.z-east {
&-collapsed {}
&-splitter {}
&-icon {}
Borderlayout 39

Check complete LESS source for Borderlayout from Github [11].

LESS Variables
The following LESS variables are used for Splitter between North, South, East and West components. Check other
variables from here.

Variables Default Value

@splitterGradientStart #FDFDFD

@splitterGradientEnd #F1F1F1

Customize Sample

Target Design
Assume the image below is our target design for Borderlayout component and Splitter component.

Implementation Details

Setup environment and Analyze design

• Check the instruction to setup component customization environment.
• Analyze the design
• Used Color for Borderlayout (include North, South, East, West, and Center)
Title Text: 14px, #555555
Border: #E3E3E3
Background: #FFFFFF
Icon: 12px, #ACACAC
Icon Background: #FFFFFF
Icon Hover: 12px, #FFFFFF
Icon Hover Background: #5687A8
• Used Color for Splitter
Background: #EBEBEB
Borderlayout 40

Icon: 12px, #ACACAC

• Borderlayout Size
Height (North and South): 40px
Width (East and West): 40px
Horizontal Padding: 8px
Vertical Padding: 8px
Icon: 24px * 24px
• Splitter Size
Height (North and South): 8px
Width (East and West): 8px

Modify borderlayout.less file to achieve target design

Refer here for built-in zk less functions.

• Modify Borderlayout Icon color and size.

.z-borderlayout {
/* omitted */

&-icon {
.iconFontStyle(12px, #ACACAC);
.displaySize(block, 24px, 24px);
line-height: 24px;
.opacity(1);
position: absolute;
right: 8px; /* horizontal padding */
/* omitted */

&:hover {
color: #FFFFFF;
background: #5687A8;
}
}
}

• Modify Borderlayout Title (North, South, East, West and Center) color and size.

.z-north,
.z-south,
.z-west,
.z-center,
.z-east {
border: 1px solid #E3E3E3;
/* omitted */

&-header {
.fontStyle(@baseTitleFontFamily, 14px, bold, #555555);
height: 40px;
Borderlayout 41

border-bottom: 1px solid #E3E3E3;

padding: 8px 8px 7px;
line-height: 24px;
.verGradient(#FFFFFF, #FFFFFF); /* no gradient, pass the
same color arguments for the function */
/* omitted */
}

&-collapsed {
.size(40px, 40px);
border: 1px solid #E3E3E3;
padding: 8px;
background: #FFFFFF;
/* omitted */
}

&-caption {
height: 40px;
}
}

• Modify Splitter (North, South, East, West and Center) color and size.

.z-east,
.z-west,
.z-north,
.z-south {
&-splitter {
.size(8px, 8px);
.horGradient(#EBEBEB, #EBEBEB); /* no gradient, pass the
same color arguments for the function */
/* omitted */

// splitter-button
&-button {
color: #ACACAC;
border: 0; /* no border */
/* omitted */
}
&-button-disabled {
border: 0;
}
}

&-icon {
font-size: 12px;
.opacity(1);
/* omitted */
Borderlayout 42

}
}
.z-north-splitter,
.z-south-splitter {
border-left: 1px solid #E3E3E3;
border-right: 1px solid #E3E3E3;
.verGradient(#EBEBEB, #EBEBEB); /* no gradient, pass the same
color arguments for the function */
/* omitted */
}

/* don't need Ellipsis icons */

.z-west-icon.z-icon-ellipsis-vertical,
.z-east-icon.z-icon-ellipsis-vertical {
display: none;
}
.z-north-icon.z-icon-ellipsis-horizontal,
.z-south-icon.z-icon-ellipsis-horizontal {
display: none;
}

Final result
Borderlayout 43

Additional Customization
The collapsed bar position is decide by LayoutRegion.getCmargins() [12]. Therefore, it is not possible to change the
position of collpased bar by CSS. However, it can still be customized by
[13]
LayoutRegion.setCmargins(java.lang.String) like the following.
<borderlayout width="600px" height="400px">
<east title="East" size="20%" collapsible="true" splittable="true" cmargins="0, 3, 0, 0">
</east>
</borderlayout>

Version History
Version Date Content

References
[1] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ chevron-up/
[2] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ chevron-down/
[3] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ chevron-left/
[4] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ chevron-right/
[5] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ ellipsis-horizontal/
[6] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ ellipsis-vertical/
[7] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ caret-up/
[8] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ caret-down/
[9] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ caret-left/
[10] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ caret-right/
[11] http:/ / github. com/ zkoss/ zk/ blob/ master/ zul/ src/ archive/ web/ js/ zul/ layout/ less/ borderlayout. less
[12] http:/ / www. zkoss. org/ javadoc/ latest/ jsdoc/ zul/ layout/ LayoutRegion. html#getCmargins()
[13] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ LayoutRegion. html#setCmargins(java. lang. String)
Tabbox 44

Tabbox
Component Reference
Component Reference: Tabbox

DOM Structure

Default Mold
<div class="z-tabbox z-tabbox-orient z-tabbox-scroll">
<div class="z-tabs">
<ul class="z-tabs-content">
<li class="z-tab">
<a class="z-tab-content">
<div class="z-tab-button">
<i class="z-icon-times z-tab-icon"></i>
</div>
<span class="z-tab-text">
<img class="z-tab-image">
</span>
</a>
</li>
<!-- other tab -->
</ul>
</div>
<div class="z-tabpanels">
<div class="z-tabpanel"></div>
<!-- other tabpanel -->
</div>
<div class="z-tabbox-icon z-tabbox-left">
<i class="z-icon-chevron-left"></i>
</div>
<div class="z-tabbox-icon z-tabbox-right">
<i class="z-icon-chevron-right"></i>
</div>
</div>

• Line 1: z-tabbox-orient represents tabbox orientation:

• z-tabbox-top (default),
• z-tabbox-bottom,
• z-tabbox-left or
• z-tabbox-right
• Line 7: Close Icon Font [1] used.
• Line 22: Chevron-left Icon Font [3] used for tab scrolling.
• Line 25: Chevron-right Icon Font [4] used for tab scrolling.
Tabbox 45

Accordion Mold
<div class="z-tabbox z-tabbox-accordion">
<div class="z-tabpanels">
<div class="z-tabpanel">
<div class="z-tab">
<a class="z-tab-content">
<div class="z-tab-button">
<i class="z-icon-times z-tab-icon"></i>
</div>
<span class="z-tab-text"></span>
</a>
</div>
<div class=" z-tabpanel-content"></div>
</div>
<!-- other tabpanel with tab inside -->
</div>
</div>

• Line 7: Close Icon Font [1] used.

LESS Source
Basically, LESS source is correspondent to its DOM structure and each orientation have different styles.

.z-tabbox {
/* basic style */

/* Scrollable style */
&-scroll {
}
/* icon style */
&-icon {
}
/* bottom style */
&-bottom {
}
/* left style */
&-left {
}
/* right style */
&-right {
}
/* Accordion mold */
&-accordion {
}
}
/* default tabs style */
.z-tabs {
Tabbox 46

&-content {}
}
/* default tab style */
.z-tab {
&-content {}
&-button {}
&-icon {}
&-text {}
&-image {}
}
/* default tabpanels style */
.z-tabpanels {
}
/* default tabpanel style */
.z-tabpanel {
}

Check complete LESS source for Tabbox from Github [2].

LESS Variables
The following LESS variables are used for Tabbox component. Check other variables from here.

Variables Default Value

@tabSelectedBackgroundColor #FFFFFF

Customize Sample

Target Design
Assume the image below is our target design for Tabbox component.
• Default Mold

• Accordion Mold
Tabbox 47

Implementation Details

Setup environment and Analyze design

• Check the instruction to setup component customization environment.
• Analyze the design
• Used Color
Tab Text: 16px, #FFFFFF
Selected Tab Text: 16px, #5687A8
Border: #E3E3E3
Normal Background: #5687A8
Selected Background: #FFFFFF
Icon (scroll and tab close): 12px, #FFFFFF
Tab Close Icon Hover: 12px, #5687A8
Tab Icon Hover Background: #FFFFFF
Disabled Background: #ACACAC
• Size
Tab Height: 48px
Tab Horizontal Padding: 8px
Tab Vertical Padding: 8px
Tab Icon: 24px * 24px
Tabbox 48

Modify tabbox.less file to achieve target design

Refer here for built-in zk less functions.

• Change overall color by overriding built-in zk less variables.

@import "~./zul/less/_header.less";

@baseBorderColor: #E3E3E3;
@baseBorderRadius: 0px;
@baseGradientStart: #5687A8;
@baseGradientEnd: #5687A8;
@hoverGradientStart: #4C7895;
@hoverGradientEnd: #4C7895;
@tabSelectedBackgroundColor: #FFFFFF;

• Modify scrollable button size

.z-tabbox {
&-icon {
.iconFontStyle(12px, #FFFFFF);
min-height: 48px;
padding: 0;
line-height: 46px;
/* omitted */

> i {
.opacity(1); /* remove opacity */
}
&:hover {
color: #FFFFFF;
}
}
&-left-scroll,
&-right-scroll {
width: 48px;
}
&-up-scroll,
&-down-scroll {
height: 48px;
}
&-scroll {
> .z-tabs {
margin: 0 48px;
}
}
}

• Modify Tab size and text size

Tabbox 49

.z-tab {
font-size: 16px;
/* omitted */

&-icon {
position: static; /* position decided by .z-tab-button,
change it from absolute to static */
/* omitted */
}

&-text {
color: #FFFFFF;
padding: 7px 12px; /* expand height to 48px by padding */
line-height: 32px;
/* omitted */
}

&-button {
.iconFontStyle(12px, #FFFFFF);
.displaySize(block, 24px, 24px);
margin-top: -12px; /* for put icon in vertical middle
position */
line-height: 24px;
.opacity(1); /* remove opacity effect */
top: 50%; /* for put icon in vertical middle position */
right: 8px; /* refer to horizontal padding */
/* omitted */

&:hover {
color: #5687A8;
background: #FFFFFF;
}
& + .z-tab-text {
margin-right: 32px;
}
}
&-selected {
/* omitted */

.z-tab-text {
font-weight: bold;
color: #5687A8;
}
}
&-disabled {
background: #ACACAC;
.opacity(1);
Tabbox 50

/* omitted */

&:hover {
.verGradient(#ACACAC, #ACACAC);
}
.z-tab-button:hover {
.opacity(1);
}
.z-tab-text {
color: #FFFFFF;
.opacity(1);
/* omitted */
}
}
}

• Modify Accordion size

.z-tabbox {
&-accordion {
/* omitted */

.z-tabpanel > .z-tab {

/* omitted */
&-selected {
/* omitted */

.z-tab-text {
color: #FFFFFF;
}
}
}
.z-tab-button {
.opacity(1); /* remove opacity effect */
&:hover {
color: #5687A8;
}
/* omitted */
}
.z-tab-text {
padding: 7px 8px; /* expand height to 48px by padding
*/
}
}
}
Tabbox 51

Final result
• Default Mold

• Accordion Mold

Version History
Version Date Content

References
[1] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ times/
[2] http:/ / github. com/ zkoss/ zk/ blob/ master/ zul/ src/ archive/ web/ js/ zul/ tab/ less/ tabbox. less
Window 52

Window
Component Reference
Component Reference: Window

DOM Structure
<div class="z-window z-window-mode">
<div class="z-window-header">
<div class="z-window-icon z-window-close">
<i class="z-icon-times"></i>
</div>
<div class="z-window-icon z-window-maximize">
<i class="z-icon-resize-full"></i>
</div>
<div class="z-window-icon z-window-minimize">
<i class="z-icon-minus"></i>
</div>
</div>
<div class="z-window-content"></div>
</div>

• Line 1: z-window-mode represents various window modes

z-window-embedded
z-window-overlapped
z-window-popup
z-window-modal
z-window-highlighted
• Line 4: Close Icon Font [1] used.
• Line 7: Resize-full Icon Font [1] used.
• Line 10: Minus Icon Font [2] used.

LESS Source
Basically, LESS source is correspondent to its DOM structure, and each mode have different styles.

.z-window {
/* basic style */

/* header style */
&-header {
}
/* icon style */
&-icon {
}
/* content style */
Window 53

&-content {
}

/* Embedded mode */
&-embedded {
}
/* Overlapped mode */
&-overlapped {
}
/* Pop-up mode */
&-popup {
}
/* Modal mode */
&-modal {
}
/* Highlighted mode */
&-highlighted {
}
}

Check complete LESS source for Window from Github [3].

LESS Variables
The following LESS variables are used for Window component. Check other variables from here.

Variables Default Value

@windowBorderColor #9C9C9C

@windowBackgroundColor #D9E5EF

@windowFramePadding 4px
Window 54

Customize Sample

Target Design
Assume the image below is our target design for Window component. No border, gradient background, rounded
corner or shadow effects.

Implementation Details

Setup environment and Analyze design

• Check the instruction to setup component customization environment.
• Analyze the design
• Used Color
Title Text: 24px, #ACACAC
Border: #E3E3E3
Background: #FFFFFF
Icon: 12px, #ACACAC
Icon Hover: 12px #FFFFFF
Icon Hover Background: #5687A8
• Size
Title Height: 48px
Title Padding: 8px(horizontal) 16px(vertical)
Content Padding: 8px(horizontal) 16px(vertical)
Icon: 24px * 24px
Window 55

Modify window.less file to achieve target design

Refer here for built-in zk less functions.

• Change color by overriding zk less variables.

@import "~./zul/less/_header.less";

@windowBorderColor: #E3E3E3;
@windowBackgroundColor: #FFFFFF;
@windowFramePadding: 0px;

• Remove rounded corners, border color and gradient background by overriding zk less variables.

@baseBorderRadius: 0;
@baseBorderColor: #FFFFFF;
@baseGradientStart: #FFFFFF;
@baseGradientEnd: #FFFFFF;

• Modify Header Title Text.

.z-window {
&-header {
.fontStyle(@baseTitleFontFamily, 24px, normal, #ACACAC);
padding: 8px 15px; /* 15px = 16px - 1px(border) */
line-height: 32px;
}
}

• Modify Icons in Header.

.z-window {
&-icon {
font-size: 12px;
color: #ACACAC;
.displaySize(block, 24px, 24px);
margin: 4px 0 0 0;
line-height: 24px;
/* omitted */

&:hover {
color: #FFFFFF;
border-color: #5687A8;
background: #5687A8;
}
}
&-close {} /* remove special style for close icon */
}

• Modify Content style and remove shadow effects.

.z-window {
&-content {
Window 56

border: 0;
padding: 8px 15px; /* 15px = 16px - 1px(border) */
/* omitted */
}
&-shadow {
.boxShadow('none');
}
}

Final result

Version History
Version Date Content

References
[1] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ resize-full/
[2] http:/ / fortawesome. github. io/ Font-Awesome/ icon/ minus/
Navbar 57

Navbar
Component Reference
Component Reference: Nav, Navbar, Navitem, Navseparator

DOM Structure
<div class="z-navbar z-navbar-orient">
<ul>
<!-- Navitem -->
<li class="z-navitem">
<a class="z-navitem-content">
<img class="z-navitem-image" />
<i class="z-icon-font"></i>
<span class="z-navitem-text"></span>
</a>
</li>
<!-- Navseparator-->
<li class="z-navseparator"></li>
<!-- Nav-->
<li class="z-nav">
<a class="z-nav-content">
<img class="z-nav-image" />
<i class="z-icon-font"></i>
<span class="z-nav-text"></span>
</a>
<ul><!-- second/third level --> </ul>
</li>
</ul>
</div>

• Line 1: z-navbar-orient represents Navbar orient (z-navbar-horizontal or z-navbar-vertical)

• Line 7,17: Can be any Icon Font from Font Awesome [1].

LESS Source
Basically, LESS source is correspondent to its DOM structure, and each orient have different styles.

/* navbar */
.z-navbar {
/* overall style */
> ul { /* first level */
ul { /* second level */
ul { /* third level */
}
}
}
Navbar 58

/* horizontal style */
&-horizontal {
}
/* vertical style */
&-vertical {
}
}
/* nav, navitem */
.z-nav,
.z-navitem {
&-content {}
&-image {}
&-text {}
}
/* navseparator */
.z-navseparator {
}

LESS Variables
The following LESS variables are used for Navbar, Nav, Navitem and Navseparator components. Check other
variables from here.

Variables Default Value

@navImageSize 16px

@navColor #333333

@navBorderColor #F4F4F3

@navBackgroundColor #FFFFFF (first level, each level is 3% darker)

@navHoverBackgroundColor #E8E8E8

@navSelectedColor #FFFFFF

@navSelectedBackgroundColor #372F2B

@navSeparatorColor #838383

@navCollapsedWidth 32px

Customize Sample

Target Design
Assume the image below is our target design for Navbar component - no border, gradient background, rounded
corner or shadow effects.
Navbar 59

Implementation Details

Setup environment and Analyze design

• Check this instruction to setup component customization environment.
• Analyze the design
• Used Color
Text: 14px, #FFFFFF, bold
1st Level Background: #5687A8, each level is 8% darker in HSV color format, which is darken(#5687A8,
(@level-1) * 5.6) in LESS
Hover Text: #5687A8
Hover Background: #FFFFFF
Selected Text: #5687A8
Selected Background: #FFFFFF
Disabled Text: #FFFFFF, 50% opacity (opacity is the same with default style)
Badge Text: 14px, #FFFFFF
Badge Text Background: 8% darker than it's background in HSV color format, which is darken(#5687A8,
@level * 5.6) in LESS
• Size
Height: 40px
Width: 180px (minimal, same with default style)
Horizontal Padding: 8px
Vertical Padding: 8px
Badge Text: 24px * 24px with circle shape

Modify nav.less file to achieve target design

Refer here for built-in zk less functions.

• Change color by overriding zk less variables.

@import "~./zul/less/_header.less";

@navColor: #FFFFFF;
@navBorderColor: #5687A8;
@navBackgroundColor: #5687A8; /* first level */
@navHoverBackgroundColor: #FFFFFF;
@navSelectedColor: #FFFFFF;
@navSelectedBackgroundColor: #FFFFFF;
@navSeparatorColor: #4C7895;

• Modify LESS mixin .navLevel(@level) to adopt darkened background on each level.

.navLevel(@level) {
.z-nav-content,
.z-navitem-content {
&:hover {
color: #5687A8; /* add text hover color here */
Navbar 60

background: @navHoverBackgroundColor;
}
&[disabled]:hover {
color: @navColor;
background: darken(@navBackgroundColor, (@level - 1) * 5.6);
}
}
.z-nav-content,
.z-navitem-content,
.z-navseparator {
background: darken(@navBackgroundColor, (@level - 1) * 5.6);
}
}

• Modify Nav, Navitem size to match target design.

.z-nav,
.z-navitem {
&-content {
height: 40px;
line-height: 40px;
/* omitted */
}
}

• Modify Nav, Navitem text style to match target design.

.z-nav,
.z-navitem {
&-text {
font-size: 14px;
font-weight: bold;
/* omitted */
}
}

• Modify Badge Text style inside Nav to match target design.

/* Add extra style inside .navLevel(@level) function */

.navLevel(@level) {
/* omitted */
.z-nav-info {
background: darken(@navBackgroundColor, @level * 5.6);
}
}

.z-nav-info {
.fontStyle(@baseContentFontFamily, 14px, bold, #FFFFFF);
.displaySize(block, 24px, 24px);
.borderRadius(12px); /* make it circle shape */
Navbar 61

line-height: 24px;
position: absolute;
top: 8px; /* match padding */
right: 8px; /* match padding */
text-align: center;
.boxShadow(none);
}

Final result

Version History
Version Date Content

References
[1] http:/ / fortawesome. github. io/ Font-Awesome/ icons/
Create New Look and Feel 62

Create New Look and Feel

Introduction
In this guide, we will demonstrate how to create a new look and feel of ZK components with Atlantic [1] theme as an
example. Atlantic theme incorporates the flat design which is very different from the default trendy design(e.g.
Breeze theme). Here we will explain the theme creation procedures step by step.

Prerequisites
1. Eclipse with maven plug-in installed (see installation guide).
2. ZK maven archetype installed (see installation guide).
3. Create a demo project by ZK maven archetype to check the design.
4. Familiar with LESS.
5. Familiar with ZK Component's DOM structure.

Create Theme Project with ZK Maven Archetype

• [File] -> [New] -> [Other] --> [Maven Project]

• Make sure Create a simple project is unchecked in the first screen of the New Maven Project wizard and click
Next > button.
• From the Select an Archetype screen, select ZK Maven Archetype from the catalog dropdown list. Then Select
zk-archetype-theme from the list.
• Next, fill in details for Group Id, Artifact Id, Version and Package, and in Properties, fill in zk version,
theme-name and theme-listener-class.
Create New Look and Feel 63

• The created project structure.

Here we can see all the LESS files from default trendy design are generated at the same time

Customize Look and Feel based on Flat Design

Here is the sample design for Mesh (grid, listbox and tree) Element.

Following steps make up a common customization method for accomplishing a new look and feel using LESS
1. Flat design does not use any gradient backgrounds, we therefore suggest to remove all gradient background
related variables found in _zkvariables.less file.
2. Define new variables for this design.
Create New Look and Feel 64

3. Find grid.less file within the project and change the style to adopt the design.
4. Right click on Atlantic project and execute Run As > Maven install to compile LESS and generate theme jar
file.
5. Check the real look of grid component in the demo project mentioned in prerequisites.
• Add dependency in demo project's pom.xml file

<dependency>
<groupId>org.zkoss.theme</groupId>
<artifactId>atlantic</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>

• Set preferred theme in demo project's zk.xml file

<library-property>
<name>org.zkoss.theme.preferred</name>
<value>atlantic</value>
</library-property>

• Follow this instruction to start up the demo project and check the style.
6. Repeat Step 1 to 5 for every component and elements.

Package and Use the Theme

After the theme is completely tuned based on flat design, right click on the Atlantic project and execute Run As >
Maven install to generate theme jar file. You can then use the theme jar (see usage instruction) in other ZK web
projects as well.

Version History
Version Date Content

References
[1] http:/ / github. com/ zkoss/ atlantic
Upgrade Customized Style From other ZK Version 65

Upgrade Customized Style From other ZK

Version
ZK 7 takes a big step forward on theme styling using CSS3 which is an approach a lot different from that of ZK 6.5.
This section will show tips on how to upgrade customized style from other ZK versions to ZK 7.

Upgrade From ZK 6.5

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 starts with the
prefix "z-" get box-sizing: border-box applied by default. If you want to keep the DIV width as 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;
}
Upgrade From ZK 6.5 66

Tip 2: Component Mold

Since we are no longer supporting browsers that don't support CSS 3 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 showed you 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 ZK 6.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
components.

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 easier to customize, we separate it into two CSS classes 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 the content part of window for all modes, simply override CSS class
z-window-content.
Upgrade From ZK 6.5 67

Upgrade sample
In this smalltalk we showed 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(see image bellow) to achieve the rounded corner style. In
ZK 7, we applied CSS 3, therefore, the complex 3 x 3 grid structure is no longer needed.
Upgrade From ZK 6.5 68

Upgrade Sample
In this smalltalk we showed 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 */
}
Upgrade From ZK 6.5 69

Brief Summary
To check the style after we removed 3 x 3 grid structure in ZK 7, we recommend you to use developer tools provided
by browsers such as Firebug for FireFox, Developer Tools for Chrome to check new DOM structure first, then move
your existing customization style into the new CSS class. Check Tip 4 Appendix for the complete list that removes
the 3 x 3 (or 3x1) grid structure..

Tip 5: CSS Class Naming

In ZK 6.5, we use abbreviations for CSS class names which can be hard to understand what it represents sometimes.
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 abbreviations have been changed to full names, we also use CSS selector likes :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 overriding 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;
}
Upgrade From ZK 6.5 70

Brief Summary
In most situations, to upgrade to ZK 7.0 from ZK 6.5 based on these changes is to modify CSS class names with full
naming patterns (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 on the market, here we integrate in ZK 7 with Font Awesome 4.0.1 [1]. 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 [7] 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, the font icon that ZK 7 uses by default also
shows up. To disable the font icon you can override the 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 wish to custom your
scrollbar, we will also demonstrate how to disable it and use browser default scrollbar instead.

Customize Scrollbar Style

The custom scrollbar 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:
Upgrade From ZK 6.5 71

/* 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;
}

You can check the customized result.

ZK 7 default scrollbar style Customized scrollbar style

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>

Note: the value of org.zkoss.zul.nativebar is true by default (since 7.0.2)

Tip 2 Appendix
Upgrade From ZK 6.5 72

Component ZK 6.5 mold ZK 7 mold

Button os default
trendy

Textbox default default

Intbox rounded
Decimalbox
Longbox
Doublebox
Combobox
Bandbox
Datebox
Timebox
Spinner
Doublespinner

Splitter default default

os

Tabbox accordion accordion

accordion-lite

Tip 3 Appendix
Component ZK 6.5 sample ZK 7 sample

Splitter z-splitter-hor z-splitter z-splitter-horizontal

z-splitter-ver z-splitter z-splitter-vertical

Slider z-slider-hor z-slider z-slider-horizontal

z-slider-ver z-slider z-slider-vertical

Menubar z-menubar-hor z-menubar z-menubar-horizontal

z-menubar-ver 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 z-separator-horizontal

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

Groupbox z-groupbox-3d z-groupbox z-groupbox-3d

Tabbox z-tabbox z-tabbox z-tabbox-top

z-tabbox-ver z-tabbox z-tabbox-bottom
z-tabbox-accordion z-tabbox z-tabbox-left
z-tabbox z-tabbox-right
z-tabbox z-tabbox-accordion

Window z-window-embedded z-window z-window-embedded

z-window-modal z-window z-window-modal
z-window-highlighted z-window z-window-highlighted
z-window-overlapped z-window z-window-overlapped
z-window-popup z-window z-window-popup
 Upgrade From ZK 6.5 73

Tip 4 Appendix
onent ZK 6.5 DOM structure ZK 7 DOM structure

Trendy mold <font size="7.32">

<button class="z-button" />
<font size="7.32">
</font>
<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>
</font>
n <font size="7.32"> <font size="7.32">
<table class="z-caption"> <div class="z-caption">
<tr> <div class="z-caption-content"></div>
<td class="z-caption-l"></td> </div>
<td class="z-caption-r"></td> </font>
</tr>
</table>
</font>
 Upgrade From ZK 6.5 74

obutton <font size="7.32"> <font size="7.32">

<span class="z-combobutton"> <span class="z-combobutton">
<table> <span class="z-combobutton-content">
<tr> <span class="z-combobutton-text"
<td class="z-combobutton-tl"> <span class="z-combobutton-button
<button class="z-combobutton" /> <i class="z-combobutton-icon"
<td class="z-combobutton-tm"></td> </span>
<td class="z-combobutton-tr"></td> </span>
</tr> </span>
<tr> </font>
<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>
</font>
x rounded mold <font size="7.32">
<input class="z-component" />
albox
<font size="7.32">
</font>
ox
<i class="z-component-rounded">
ebox
<input class="z-component-rounded-inp" />
<i class="z-component-rounded-right-edge" />
</i>
</font>
box <font size="7.32"> <font size="7.32">
<div class="z-groupbox"> <div class="z-groupbox">
<div class="z-groupbox-tl"> <div class="z-groupbox-header"></div>
<div class="z-groupbox-tr"></div> <div class="z-groupbox-content"></div
</div> </div>
<div class="z-groupbox-hl"> </font>
<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>
</font>
 Upgrade From ZK 6.5 75

<font size="7.32"> <font size="7.32">

<div class="z-panel"> <div class="z-panel">
<div class="z-panel-tl"> <div class="z-panel-head">
<div class="z-panel-tr"></div> <div class="z-panel-header"></div
</div> </div>
<div class="z-panel-hl"> <div class="z-panel-body">
<div class="z-panel-hr"> <div class="z-panelchildren"></di
<div class="z-panel-hm"> </div>
<div class="z-panel-header"></div> </div>
</div> </font>
</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>
</font>
w <font size="7.32"> <font size="7.32">
<div class="z-window"> <div class="z-window">
<div class="z-window-tl"> <div class="z-window-header"></div>
<div class="z-window-tr"></div> <div class="z-window-content"></div>
</div> </div>
<div class="z-window-hl"> </font>
<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>
</font>
 Upgrade From ZK 6.5 76

horizontal / vertical orient <font size="7.32">

<li class="z-tab">
<font size="7.32">
<a class="z-tab-content">
<li class="z-tab">
<div class="z-tab-button"></div>
<a class="z-tab-close"></a>
<span class="z-tab-text"></span>
<div class="z-tab-hl">
</a>
<div class="z-tab-hr">
</li>
<div class="z-tab-hm"></div>
</font>
</div>
</div>
</li>
</font>

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*
Upgrade From ZK 6.5 77

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
Version Date Content
Article Sources and Contributors 78

Article Sources and Contributors

ZK Style Customization Guide Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide Contributors: Jeanher, Vincent, Wingor

Introduction Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Introduction Contributors: Southerncrossie, Vincent

ZK CSS Class Design Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/ZK_CSS_Class_Design Contributors: Vincent

Sclass Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/ZK_CSS_Class_Design/Sclass Contributors: Southerncrossie, Vincent

Zclass Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/ZK_CSS_Class_Design/Zclass Contributors: Vincent

ZK Class Naming Rule Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/ZK_CSS_Class_Design/ZK_Class_Naming_Rule Contributors: Southerncrossie, Vincent

By DOM Structure Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/ZK_CSS_Class_Design/ZK_Class_Naming_Rule/By_DOM_Structure Contributors:

Southerncrossie, Vincent

By Event Effect Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/ZK_CSS_Class_Design/ZK_Class_Naming_Rule/By_Event_Effect Contributors:

Southerncrossie, Vincent

Integrate with LESS Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS Contributors: Vincent

Introduction to LESS Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS/Introduction_to_LESS Contributors: Southerncrossie, Vincent

How ZK works with LESS Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS/How_ZK_works_with_LESS Contributors: Vincent

ZK LESS Variables Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS/How_ZK_works_with_LESS/ZK_LESS_Variables Contributors:

Southerncrossie, Vincent

ZK LESS Functions Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS/How_ZK_works_with_LESS/ZK_LESS_Functions Contributors:

Southerncrossie, Vincent

ZK LESS Syntax Notes Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS/How_ZK_works_with_LESS/ZK_LESS_Syntax_Notes

Contributors: Hanhsu

Compile LESS Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Integrate_with_LESS/How_ZK_works_with_LESS/Compile_LESS Contributors: Hanhsu,

Southerncrossie, Vincent

Look and Feel Customization Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization Contributors: Vincent

Partial customize with Sclass and Zclass Source:

http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Partial_customize_with_Sclass_and_Zclass Contributors: Jumperchen, Southerncrossie,
Vincent

Customize Component Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component Contributors: Ashishd, Hanhsu,

Jeanher, Southerncrossie, Vincent

Button Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component/Button Contributors: Southerncrossie, Vincent

Borderlayout Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component/Borderlayout Contributors:

Southerncrossie, Vincent

Tabbox Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component/Tabbox Contributors: Southerncrossie, Vincent

Window Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component/Window Contributors: Southerncrossie, Vincent

Navbar Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component/Navbar Contributors: Southerncrossie, Vincent

Create New Look and Feel Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Create_New_Look_and_Feel Contributors: Hawk,

Southerncrossie, Vincent

Upgrade Customized Style From other ZK Version Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Upgrade_Customized_Style_From_other_ZK_Version

Contributors: Southerncrossie, Vincent

Upgrade From ZK 6.5 Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Upgrade_Customized_Style_From_other_ZK_Version/Upgrade_From_ZK_6.5

Contributors: Jumperchen, Southerncrossie, Vincent
Image Sources, Licenses and Contributors 79

Image Sources, Licenses and Contributors

Image:Zk-css-dom.PNG Source: http://new.zkoss.org/index.php?title=File:Zk-css-dom.PNG License: unknown Contributors: Elton776
File:styleguide-sclass.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-sclass.png License: unknown Contributors: Vincent
File:styleguide-zclass.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-zclass.png License: unknown Contributors: Vincent
File:styleguide-sclass-advanced1.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-sclass-advanced1.png License: unknown Contributors: Vincent
File:styleguide-sclass-advanced2.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-sclass-advanced2.png License: unknown Contributors: Vincent
File:Zkless_servlet_scaffod.png Source: http://new.zkoss.org/index.php?title=File:Zkless_servlet_scaffod.png License: unknown Contributors: Hanhsu
File:Styleguide_prj_str.png Source: http://new.zkoss.org/index.php?title=File:Styleguide_prj_str.png License: unknown Contributors: Hanhsu
File:styleguide-button-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-button-design.png License: unknown Contributors: Vincent
File:styleguide-button.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-button.png License: unknown Contributors: Vincent
File:styleguide-borderlayout-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-borderlayout-design.png License: unknown Contributors: Vincent
File:styleguide-borderlayout.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-borderlayout.png License: unknown Contributors: Vincent
File:styleguide-tabbox-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-tabbox-design.png License: unknown Contributors: Vincent
File:styleguide-accordion-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-accordion-design.png License: unknown Contributors: Vincent
File:styleguide-tabbox.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-tabbox.png License: unknown Contributors: Vincent
File:styleguide-accordion.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-accordion.png License: unknown Contributors: Vincent
File:styleguide-window-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-window-design.png License: unknown Contributors: Vincent
File:styleguide-window.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-window.png License: unknown Contributors: Vincent
File:styleguide-nav-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-nav-design.png License: unknown Contributors: Vincent
File:styleguide-nav.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-nav.png License: unknown Contributors: Vincent
File:ZK_Installation_Guide_Quick_Start_Maven_New_project-01.png Source: http://new.zkoss.org/index.php?title=File:ZK_Installation_Guide_Quick_Start_Maven_New_project-01.png
License: unknown Contributors: Jimmyshiau
File:styleguide-newtheme3.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-newtheme3.png License: unknown Contributors: Vincent
File:styleguide-newtheme4.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-newtheme4.png License: unknown Contributors: Vincent
Image:Button2.png Source: http://new.zkoss.org/index.php?title=File:Button2.png License: unknown Contributors: Elton776
File:ZK7_scrollbar_1.png Source: http://new.zkoss.org/index.php?title=File:ZK7_scrollbar_1.png License: unknown Contributors: Vincent
File:ZK7_scrollbar_2.png Source: http://new.zkoss.org/index.php?title=File:ZK7_scrollbar_2.png License: unknown Contributors: Vincent