ZK 7.0.0 Style Customization Guide

PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information.PDF generated at: Wed, 27 Nov 2013 07:53:08 CST

ZK Style CustomizationGuideFor ZK 7.0.0

ContentsArticles

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 14 Compile LESS 21 Look and Feel Customization 25 Partical customize with Sclass and Zclass 25 Customize Component 27 Button 28 Borderlayout 33 Tabbox 40 Window 48 Navbar 52 Create New Look and Feel 57 Upgrade Customized Style From other ZK Version 61 Upgrade From ZK 6.5 61

ReferencesArticle Sources and Contributors 74Image Sources, Licenses and Contributors 75

ZK Style Customization Guide 1

ZK Style Customization GuideDocumentation:Books/ZK_Style_Customization_Guide

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

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, pleaserefer to ZK Installation Guide, for concepts, please refer to ZK Essentials. For a full description of componentproperties 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 andsapphire. You could derive your own theme from any of them and it is also a good source to know how a customtheme 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]), itwill 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

will generate the following output

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(HtmlBaseComponent.setZclass(java.lang.String) [1]) will be used to name the CSS classes associated with the DOMstructure of a component, including the root and the children. In addition, each kind of components is assigned witha 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 ifzclass 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

will generate the following output

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

Version History


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 onepart. The following recommended naming patterns are to clarify the DOM structure of ZK components, not alimitation.

Layout ElementsThe following naming patterns are based on component layout. For example, "z-window-header" means header partof 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 ElementsThe 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 ElementsThe 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.

-iconfor component interaction

-popup:pop-up element, like datebox, combobox, and so on.

-button:a button.

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

Switch Resize Split

By DOM Structure 6

-close:

describes an icon which is closed, liketree, group, an so on.

-collapse:

describes a collapsible icon, like panel.

-collapsed:

describes a collapsible icon which iscollapsed, like panel.

-expand:

describes an expandable icon, likepanel.

-expanded:

describes an expandable icon which isexpanded, like panel.

-maximize:

describes a maximizable icon.

-maximized:

describes a maximizable iconwhich is maximized.

-minimize:

describes a minimizable icon.

-splitter:

describes a splittableicon.

-nosplitter:

describes anon-splittable icon.

Version History


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

Mouse OperationThe 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 StateThe following naming patterns are based on component states.

-selectedselected state.

-checkedchecked state.

-checkablecan be checked state.

[disabled] or -disableddisabled state.

:visited

visited state.-invalid

invalid state.[readonly] or -readonly

readonly state.

Version History


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

IntroductionLESS is the dynamic stylesheet language. LESS extends CSS with dynamic behavior such as variables, mixins,operations and functions.[1]

LESS was developed by Alexis Sellier [2], more commonly known as cloudhead [2]. It is now maintained andextended by the LESS core team. [3]

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

VariablesDefine variables with "@" sign and use it as follows:

@green: #46A546;

.greendiv {

background: @green;

}

will output

.greendiv {

background: #46A546;

}

MixinsDefine 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;

}

Version History


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

How ZK works with LESS This section will introduce how ZK integrate with LESS and compile LESS to *.css.dsp files (Think of them asnormal 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 customizinga theme with a new look and feel.

TypographyDefine 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 sizingDefine 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;


Component Basic ColoringDefine 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 FontDefine icon's font color (all icon font used in ZK comes from font-awesome [1]).

// Icon Font

@iconColor: #636363;

@iconHoverColor: #636363;

@iconDisabledColor: #AAAAAA;

Component StateDefine 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;


// 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 VariablesAbove described are common variables that are shared among every component. Below we will define independentvariables that uniquely belongs to each individual component.

Button, Input, TableDefine 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


@tableTitleBorderColor: @baseBorderColor;

@tableContentBorderColor: #FFFFFF;

@tableBackgroundColor: #FFFFFF;

@tableStripeBackgroundColor: #F7F7F7;

@tableFootBackgroundColor: #FAFAFA;

Layout Components// window

@windowBorderColor: #9C9C9C;

@windowBackgroundColor: #D9E5EF;

@windowFramePadding: 4px;

// paging

@pagingColor: @textColorBlue;

@pagingBorderColor: @baseBorderColor;

@pagingBackgroundColor: #FAFAFA;

Version History


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

ZK LESS Functions 14

ZK LESS Functions

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

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

Function Usage

encodeURL .myDiv { background: ${c:encodeURL('~./path/to/image.png')};}

encodeThemeURL .myDiv { background: ${c:encodeThemeURL('~./path/to/image.png')};}

if .myDiv { background: rgba(200, 200, 200, 0.8);


Function Usage

gradient .myDiv { ${t:gradient('ver', '#FFFFFF 0%; #EEEEEE 100%')};}

boxbox2box3

.myDiv1 { ${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 .myDiv { ${t:boxShadow('1px 1px 0 rgba(0, 0, 0, 0.2)')};}

borderRadius .myDiv { ${t:borderRadius('5px')};}

transform .myDiv { ${t:transform('translate3d(0, 0, 0)')};}

applyCSS3 .myDiv { ${t:applyCSS3('transition-property', 'opacity')}; ${t:applyCSS3('transition-duration', '350ms')}}

ZK LESS FunctionSince ZK LESS engine compile LESS files into DSP pages, you can use the DSP functions mentioned above inside aLESS 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

BackgroundImage

Usage

.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;}

Theme Functions in Mixins



GradientBackground

Usage

.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;}


RoundedCorner

Usage

.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



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


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


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

Compile LESS 21

Compile LESS

Compile LESS to CSSIf your LESS files don't use any DSP functions, you can simply compile it by following instruction on the LESSofficial website. Or, if you prefer to compile LESS from java, you can use lesscss-engine [1] developed by AsualDZZD.

Compile LESS to DSPIf you prefer to use DSP page, here we introduce how to compile LESS to DSP files by Ant and Maven.

Compile LESS by Ant Follow the online document [2] to install Apache Ant. Download the following necessary jars in your project/lib folder from zk repository [3] (right click -> save as).

commons-logging.jar js.jar lesscss-engine.jar yuicompressor.jar zkjszips.jar zkless.jar (extension from lesscss-engine [1]) zul.jar (extract zk-bin-7.0.X.zip file from sourceforge [4])

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

Execute ant command in command line tool.

Compile LESS 22

Compile LESS by Maven Modify pom.xml in maven project

zkmaven

ZK Maven Plugin Repository

http://mavensync.zkoss.org/maven2/

org.zkoss.zk

zul

7.0.0

org.zkoss.maven

zkless-engine-maven-plugin

0.8.2

compile-less

lessc

${project.basedir}/src/main/resources

${project.basedir}/src/main/resources

Execute mvn install command to trigger LESS compilation.

Compile LESS 23

Compile LESS to DSP during Development phaseIt is not friendly to debug LESS during development by running Ant. Therefore, we provide a servlet namedZKLessServlet 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: Add maven dependency if you are using maven.

ZK CE

ZK CE Repository

http://mavensync.zkoss.org/maven2

org.zkoss.maven

zkless-servlet

0.8.2

Add servlet settings in web.xml

zkLess

org.zkoss.less.ZKLessServlet

org.zkoss.less.LessResource

/less

org.zkoss.less.OutputFormat

.css.dsp

org.zkoss.less.CompressOutput

true

1

zkLess

/less/*

Compile LESS 24

Project structure and use LESS directly in zul page.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

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

Version History


References[1] http:/ / www. asual. com/ lesscss/[2] http:/ / ant. apache. org/ manual/ install. html[3] http:/ / github. com/ zkoss/ zk/ tree/ v7. 0. 0-Preview/ dist/ lib/ ext[4] http:/ / sourceforge. net/ projects/ zk1/ files/ ZK/

Look and Feel Customization 25

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

Partical 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 specificcomponent. Here we will demonstrate how to you can execute partial customization by using Sclass and Zclass.

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

.mybutton {

border-radius: 10px;

background: linear-gradient(to bottom, #f0f9ff 0%,#a1dbff 100%);

}

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

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

.mybutton {

border-radius: 10px;

background: linear-gradient(to bottom, #f0f9ff 0%,#a1dbff 100%);

}

you can see that the button looses its default style such as font size and border style as illustrated below:

Partical customize with Sclass and Zclass 26

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

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

.mymenu {

color: blue;

}

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 thefollowing:

.mymenu .z-menu-text {

color: blue;

}

the style is now correctly applied.

Partical customize with Sclass and Zclass 27

Version History


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

Step to Customize Component by LESSHere we will use Window component as an example to demonstrate how to customize a component. 1. Link to Window Component page to check the DOM structure and LESS content. 2. Create window.less file under less folder in ZK web project with LESS content found from previous step.

The project structure (here we use maven project)

Copy LESS content into window.less file from Github [1]. 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 itsbackground color and padding by re-defining LESS variables as follows:

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

@windowBackgroundColor: #D9E5EF;


/* 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.

Customize Component 28

Window Content

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 in window.zul page. Remove ZK Less Servlet settings in web.xml. 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.

/less/window.css.dsp

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

Button

Component ReferenceComponent Reference: Button

DOM Structure

LESS SourceBasically, 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 {

Button 29

}

/* active style */

&:active {

}

/* disabled style */

&[disabled] {

}

}

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

LESS VariablesThe following LESS variables are used for the Button component. Check other variables from Github [2].

Variables DefaultValue

@baseButtonHeight 24px

@buttonBorderColor #A9A9A9

@buttonGradientStart #FEFEFE

@buttonGradientEnd #EEEEEE

Customize Sample

Target DesignAssume the image below is our target design for Button component. No border, gradient background, rounded corneror shadow effects.

Button 30

Implementation Details

Setup environment and Analyze design Check the instruction to setup component customization environment. Analyze the design

Used ColorText: 14px, #FFFFFFNormal Background: #5687A8Hover Background: #5E94B8Pressed Background: #4C7895Focus Background: #436983Disabled Background: #ACACAC

SizeHeight: 32pxHorizontal Padding: 16pxVertical Padding: 4px

Modify button.less file to achieve target designRefer 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 */

Button 31

.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


.boxShadow(inset 0 2px 0 #3A5B72); /* for simulation 3d effect

*/

}

}

Modify Focus state:

.z-button {

&:focus {

color: #FFFFFF;

.verGradient(#436983, #436983); /* no gradient, pass the same


.boxShadow(none);

}

}

Modify Disabled state:

.z-button {

&[disabled] {

color: #FFFFFF;

.verGradient(#ACACAC, #ACACAC); /* no gradient, pass the same


.boxShadow(none);

.opacity(1); /* no opacity needed */

}

}

Modify Size:

.z-button {

/* omitted */

min-height: 32px;

padding: 4px 16px;

}

Button 32

Final result

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

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;

}

}

Version History


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

Borderlayout 33

Borderlayout

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

DOM Structure

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]

Borderlayout 34

Line 12, 14: Ellipsis-horizontal Icon Font [5] used for North and South, Ellipsis-vertical Icon Font [6] used for Eastand 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 SourceBasically, 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 {}

}

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

Borderlayout 35

LESS VariablesThe following LESS variables are used for Splitter between North, South, East and West components. Check othervariables from Github [2].


@splitterGradientStart #FDFDFD

@splitterGradientEnd #F1F1F1

Customize Sample

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



Used Color for Borderlayout (include North, South, East, West, and Center)Title Text: 14px, #555555Border: #E3E3E3Background: #FFFFFFIcon: 12px, #ACACACIcon Background: #FFFFFFIcon Hover: 12px, #FFFFFFIcon Hover Background: #5687A8

Used Color for SplitterBackground: #EBEBEBIcon: 12px, #ACACAC

Borderlayout Size

Borderlayout 36

Height (North and South): 40pxWidth (East and West): 40pxHorizontal Padding: 8pxVertical Padding: 8pxIcon: 24px * 24px

Splitter SizeHeight (North and South): 8pxWidth (East and West): 8px

Modify borderlayout.less file to achieve target designReferhere 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;


}

}

}

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;

border-bottom: 1px solid #E3E3E3;

padding: 8px 8px 7px;

Borderlayout 37

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 38

.z-north-splitter,

.z-south-splitter {

border-left: 1px solid #E3E3E3;

border-right: 1px solid #E3E3E3;

.verGradient(#EBEBEB, #EBEBEB); /* no gradient, pass the same


/* 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 39

Additional CustomizationThe collapsed position is decide by LayoutRegion.getCmargins() [12]. Therefore, it is not possible to change theposition of collpased area by CSS. However, it can still be customized by overriding widget bind_ function and setthe margins like the following.

function() {

this.$bind_();

this.setCmargins("0, 3, 0, 0"); //top, left, right,

bottom

}

]]>

Version History


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()

Tabbox 40

Tabbox

Component ReferenceComponent Reference: Tabbox

DOM Structure

Default Mold

Line 1: z-tabbox-orient represents tabbox orientation: z-tabbox-horizontal (default), z-tabbox-horizontal-bottom, z-tabbox-vertical or z-tabbox-vertical-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 41

Accordion Mold

Line 7: Close Icon Font [1] used.

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

.z-tabbox {

/* basic style */

/* Scrollable style */

&-scroll {

}

/* icon style */

&-icon {

}

/* horizontal-bottom style */

&-horizontal-bottom {

}

/* vertical style */

&-vertical {

}

/* vertical-right style */

&-vertical-right {

}

/* Accordion mold */

&-accordion {

}

}

/* default tabs style */

.z-tabs {

Tabbox 42

&-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 Window from Github [2].

LESS VariablesThe following LESS variables are used for Tabbox component. Check other variables from Github [2].


@tabSelectedBackgroundColor #FFFFFF

Customize Sample

Target DesignAssume the image below is our target design for Tabbox component.

Tabbox 43



Used ColorTab Text: 16px, #FFFFFFSelected Tab Text: 16px, #5687A8Border: #E3E3E3Normal Background: #5687A8Selected Background: #FFFFFFIcon (scroll and tab close): 12px, #FFFFFFTab Close Icon Hover: 12px, #5687A8Tab Icon Hover Background: #FFFFFFDisabled Background: #ACACAC

SizeTab Height: 48pxTab Horizontal Padding: 8pxTab Vertical Padding: 8pxTab Icon: 24px * 24px

Tabbox 44

Modify tabbox.less file to achieve target designReferhere 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 45

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


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;


}

& + .z-tab-text {

margin-right: 32px;

}

}

&-selected {

/* omitted */

.z-tab-text {

font-weight: bold;

color: #5687A8;

}

}

&-disabled {

background: #ACACAC;

.opacity(1);

Tabbox 46

/* 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 47

Final result

Version History


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 48

Window

Component ReferenceComponent Reference: Window

DOM Structure

Line 1: z-window-mode represents window mode (z-window-embedded, z-window-overlapped,z-window-popup, z-window-modal or z-window-highlighted)

Line 4: Close Icon Font [1] used. Line 7: Resize-full Icon Font [2] used. Line 10: Minus Icon Font [3] used.

LESS SourceBasically, 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 */

&-content {

}

/* Embedded mode */

&-embedded {

Window 49

}

/* Overlapped mode */

&-overlapped {

}

/* Pop-up mode */

&-popup {

}

/* Modal mode */

&-modal {

}

/* Highlighted mode */

&-highlighted {

}

}

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

LESS VariablesThe following LESS variables are used for Window component. Check other variables from Github [2].


@windowBorderColor #9C9C9C

@windowBackgroundColor #D9E5EF

@windowFramePadding 4px

Customize Sample

Target DesignAssume the image below is our target design for Window component. No border, gradient background, roundedcorner or shadow effects.

Window 50



Used ColorTitle Text: 24px, #ACACACBorder: #E3E3E3Background: #FFFFFFIcon: 12px, #ACACACIcon Hover: 12px #FFFFFFIcon Hover Background: #5687A8

SizeTitle Height: 48pxTitle Padding: 8px(horizontal) 16px(vertical)Content Padding: 8px(horizontal) 16px(vertical)Icon: 24px * 24px

Modify window.less file to achieve target designReferhere for built-in zk less functions.

Change color by overriding zk less variables.


@windowBorderColor: #E3E3E3;

@windowBackgroundColor: #FFFFFF;


Remove rounded corners, border color and gradient background.


@baseBorderRadius: 0;

@baseBorderColor: #FFFFFF;

@baseGradientStart: #FFFFFF;

@baseGradientEnd: #FFFFFF;

Modify Header Title Text.


.z-window {

&-header {

.fontStyle(@baseTitleFontFamily, 24px, light, #ACACAC);

padding: 8px 15px; /* 15px = 16px - 1px(border) */

line-height: 32px;

Window 51

}

}

Modify Icons in Header.


.z-window {

&-icon {

font-size: 12px;

color: #ACACAC;


margin: 4px 0 0 0;

line-height: 24px;

/* omitted */

&:hover {

color: #FFFFFF;

border-color: #5687A8;


}

}

&-close {} /* remove special style for close icon */

}

Modify Content style and remove shadow effects.


.z-window {

&-content {

border: 0;

padding: 8px 15px; /* 15px = 16px - 1px(border) */

/* omitted */

}

&-shadow {

.boxShadow('none');

}

}

Window 52

Final result

Version History


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

Navbar

Component ReferenceComponent Reference: Nav, Navbar, Navitem, Navseparator

DOM Structure

Navbar 53

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 SourceBasically, 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 */

}

}

}

/* horizontal style */

&-horizontal {

}

/* vertical style */

&-vertical {

}

}

/* nav, navitem */

.z-nav,

.z-navitem {

&-content {}

&-image {}

&-text {}

}

/* navseparator */

.z-navseparator {

}

Navbar 54

LESS VariablesThe following LESS variables are used for Navbar, Nav, Navitem and Navseparator components. Check othervariables from Github [2].

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 DesignAssume the image below is our target design for Navbar component - no border, gradient background, roundedcorner or shadow effects.


Setup environment and Analyze design Check this instruction to setup component customization environment. Analyze the design

Used ColorText: 14px, #FFFFFF, bold1st Level Background: #5687A8, each level is 8% darker in HSV format, which is darken(#5687A8,(@level-1) * 5.6) in LESSHover Text: #5687A8Hover Background: #FFFFFFSelected Text: #5687A8Selected Background: #FFFFFFDisabled Text: #FFFFFF, 50% opacity (opacity is the same with default style)Badge Text: 14px, #FFFFFF

Navbar 55

Badge Text Background: 8% darker than it's background in HSV, which is darken(#5687A8, @level * 5.6) inLESS

SizeHeight: 40pxWidth: 180px (minimal, same with default style)Horizontal Padding: 8pxVertical Padding: 8pxBadge Text: 24px * 24px with circle shape

Modify nav.less file to achieve target designReferhere for built-in zk less functions.

Change color by overriding zk less variables.


@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 */

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.

Navbar 56


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

.z-nav-info {

background: darken(@navBackgroundColor, @level * 5.6);

}

}

.z-nav-info {

.fontStyle(@baseContentFontFamily, 14px, bold, #FFFFFF);


.borderRadius(12px);

line-height: 24px;

position: absolute;

top: 8px; /* match padding */

right: 8px; /* match padding */

text-align: center;

.boxShadow(none);

}

Navbar 57

Final result

Version History


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

Create New Look and Feel

IntroductionIn this guide, we will demonstrate how to create a new look and feel of ZK components with Atlantic [1] theme as anexample. 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.

Prerequisites1. 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 New Look and Feel 58

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 clickNext > button.

From the Select an Archetype screen, select ZK Maven Archetype from the catalog dropdown list. Then Selectzk-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.

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 DesignHere 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 LESS1. 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.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

org.zkoss.theme

atlantic

0.0.1-SNAPSHOT

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

org.zkoss.theme.preferred

atlantic

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 ThemeAfter 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 [2]) in other ZK webprojects as well.

Version History


References[1] http:/ / github. com/ zkoss/ atlantic[2] http:/ / github. com/ zkoss/ zkthemes/ blob/ master/ sapphire/ readme. txt

Upgrade Customized Style From other ZK Version 61

Upgrade Customized Style From other ZKVersion 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 SizingTo improve performance at client side, we use the border-box model for all components in ZK 7 instead of thecontent-box model. It means a specified CSS property - width/min-width and height/min-height - on the elementwill consider border width.

Upgrade SampleIn 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 theprefix "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 {


width: 102px;

}

or

.z-div {


width: 100px;

box-sizing: content-box;

}

Upgrade From ZK 6.5 62

Tip 2: Component MoldSince we are no longer supporting browsers that don't support CSS 3 in ZK 7, some components' molds are nowsharing the same DOM structure with their default mold to improve performance. However, you do not need tochange your Component.setMold() code since ZK handles this transparently.

Upgrade sampleIn this smalltalk we showed you how to customize the button component using CSS 3 with the os mold based on ZK6.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 thesame markup using the same CSS class "z-button" (default mold). Here the new style override:

.z-button {

color: #FFFFFF;

font-weight: bold;

/* omitted */

}

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

Tip 3: Component ZclassSome components' zclass-es consist of several parts (separated by dashes "-"), for instance, the zclass of the Windowcomponent 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 patternz-window-mode-header. In order to make it easier to customize, we separate it into two CSS classes with "zclassmodeclass" pattern.For example,

Then, if you want to customize the content part of window for all modes, simply override CSS classz-window-content.


Upgrade sampleIn 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 SummaryTo adapt this change for ZK 7, check Tip 3 Appendix for the complete list of related changes eliminating CSSclasses.

Tip 4: DOM StructureIn ZK 6.5, several components use a 3 x 3 grid structure(see image bellow) to achieve the rounded corner style. InZK 7, we applied CSS 3, therefore, the complex 3 x 3 grid structure is no longer needed.


Upgrade SampleIn 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.) toadd 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 {


/* 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.

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

.z-window {


/* omitted */

}


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

Tip 5: CSS Class NamingIn 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, orz-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 andattribute selector like [disabled] to make it more intuitive.

Upgrade SampleIn this smalltalk we demonstrate how to customize comboitem style when it is selected by overriding CSS classz-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 asfollows:

.z-combobox-popup .z-comboitem:hover,

.z-combobox-popup .z-comboitem-selected {

color: #2BCCDA;

background-color: #000000;

}


Brief SummaryIn most situations, to upgrade to ZK 7.0 from ZK 6.5 based on these changes is to modify CSS class names with fullnaming patterns (from z-component-shortname to z-component-fullname). Check Tip 5 Appendix for the completelist of ZK 7 CSS class naming rule.

Tip 6: Image Icons and Font IconsIn order to reduce page loading time, we use font icons in ZK 7 to replace original image icons. There are a lot ofweb icon fonts on the market, here we integrate in ZK 7 with Font Awesome 4.0.1 [1]. Thus, it is easy to use fonticons in ZK application by simply replace prefix fa to z-icon, for example, z-icon-caret-up represents a trianglearrow up [7] font icon.

Upgrade SampleIn 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 alsoshows up. To disable the font icon you can override the font icon CSS class as follows:

.z-combobox-button {


}

.z-combobox-icon {

display: none;

}

or

.z-combobox-button {


}

.z-combobox-icon.z-icon-caret-down:before {

content: '';

}

Tip 7: ScrollbarSince ZK 7, we provide custom scrollbar for Grid, Listbox and Tree component by default, which means you canalso customize scrollbar style. Here we will demonstrate how to style it. Or, if you do not wish to custom yourscrollbar, we will also demonstrate how to disable it and use browser default scrollbar instead.

Customize Scrollbar StyleThe custom scrollbar consists of two buttons to click for scrolling left/right, an indicator to represent current scrollposition 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 {


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 {


}

/* 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 scrollbarTo disable custom scrollbar provided by ZK 7. Add the library property called org.zkoss.zul.nativebar in zk.xml andset it to true.

org.zkoss.zul.nativebar

true

Tip 2 Appendix


Component ZK 6.5 mold ZK 7mold

Button ostrendy

default

TextboxIntboxDecimalboxLongboxDoubleboxComboboxBandboxDateboxTimeboxSpinnerDoublespinner

defaultrounded

default

Splitter defaultos

default

Tabbox accordionaccordion-lite

accordion

Tip 3 Appendix

Component ZK 6.5 sample ZK 7 sample

Splitter z-splitter-horz-splitter-ver

z-splitter z-splitter-horizontalz-splitter z-splitter-vertical

Slider z-slider-horz-slider-ver

z-slider z-slider-horizontalz-slider z-slider-vertical

Menubar z-menubar-horz-menubar-ver

z-menubar z-menubar-horizontalz-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-horizontalz-separator-vertical

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

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

Tabbox z-tabboxz-tabbox-verz-tabbox-accordion

z-tabbox z-tabbox-topz-tabbox z-tabbox-bottomz-tabbox z-tabbox-leftz-tabbox z-tabbox-rightz-tabbox z-tabbox-accordion

Window z-window-embeddedz-window-modalz-window-highlightedz-window-overlappedz-window-popup

z-window z-window-embeddedz-window z-window-modalz-window z-window-highlightedz-window z-window-overlappedz-window z-window-popup


Tip 4 Appendix

Component ZK 6.5 DOM structure ZK 7 DOM structure

Button Trendy mold

Caption


Combobutton

TextboxIntboxDecimalboxLongboxDoublebox

rounded mold

Groupbox


Panel

Window


Tab horizontal / vertical orient

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 andPosition

-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


Article Sources and Contributors 74

Article Sources and ContributorsZK Style Customization Guide Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide Contributors: Vincent

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

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:Southerncrossie, Vincent

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

Partical customize with Sclass and Zclass Source:http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Partical_customize_with_Sclass_and_Zclass Contributors: Southerncrossie, Vincent

Customize Component Source: http://new.zkoss.org/index.php?title=ZK_Style_Customization_Guide/Look_and_Feel_Customization/Customize_Component Contributors: 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: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_VersionContributors: 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.5Contributors: Southerncrossie, Vincent

Image Sources, Licenses and Contributors 75

Image Sources, Licenses and ContributorsImage:Zk-css-dom.PNG Source: http://new.zkoss.org/index.php?title=File:Zk-css-dom.PNG License: unknown Contributors: Elton776File:styleguide-sclass.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-sclass.png License: unknown Contributors: VincentFile:styleguide-zclass.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-zclass.png License: unknown Contributors: VincentFile:styleguide-sclass-advanced1.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-sclass-advanced1.png License: unknown Contributors: VincentFile:styleguide-sclass-advanced2.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-sclass-advanced2.png License: unknown Contributors: VincentFile:styleguide-component.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-component.png License: unknown Contributors: VincentFile:styleguide-button-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-button-design.png License: unknown Contributors: VincentFile:styleguide-button.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-button.png License: unknown Contributors: VincentFile:styleguide-borderlayout-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-borderlayout-design.png License: unknown Contributors: VincentFile:styleguide-borderlayout.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-borderlayout.png License: unknown Contributors: VincentFile:styleguide-tabbox-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-tabbox-design.png License: unknown Contributors: VincentFile:styleguide-accordion-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-accordion-design.png License: unknown Contributors: VincentFile:styleguide-tabbox.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-tabbox.png License: unknown Contributors: VincentFile:styleguide-accordion.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-accordion.png License: unknown Contributors: VincentFile:styleguide-window-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-window-design.png License: unknown Contributors: VincentFile:styleguide-window.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-window.png License: unknown Contributors: VincentFile:styleguide-nav-design.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-nav-design.png License: unknown Contributors: VincentFile:styleguide-nav.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-nav.png License: unknown Contributors: VincentFile: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.pngLicense: unknown Contributors: JimmyshiauFile:styleguide-newtheme3.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-newtheme3.png License: unknown Contributors: VincentFile:styleguide-newtheme4.png Source: http://new.zkoss.org/index.php?title=File:Styleguide-newtheme4.png License: unknown Contributors: VincentImage:Button2.png Source: http://new.zkoss.org/index.php?title=File:Button2.png License: unknown Contributors: Elton776File:ZK7_scrollbar_1.png Source: http://new.zkoss.org/index.php?title=File:ZK7_scrollbar_1.png License: unknown Contributors: VincentFile:ZK7_scrollbar_2.png Source: http://new.zkoss.org/index.php?title=File:ZK7_scrollbar_2.png License: unknown Contributors: Vincent

Date post:	22-Nov-2015
Category:	Documents
Upload:	fcosys
View:	203 times
Download:	12 times

ZK 7.0.0 Style Customization Guide

Documents