Saturday, June 1, 2013

ZK CDT: Create Custom Mask Component


This is the first article of ZK CDT (ZK Component Development Tutorial) walkthrough, this article describe what is the most basic part of a ZK component.

The goal of this walkthrough is to create a quicknote component that help you do some quick note on web page (similar to you crop some screenshot, highlight something and add some text in painter), and describe each part of a component through each article in this walkthrough.


View demo online:

As you can see, all components under mask component are covered by a mask and cannot access them with mouse.


ZK Component Development Tutorial: Getting Started

View the article above at first if you do not know anything of ZK Component Development.

NOTE: This article actually contains nothing new, so we will not go into the details, just show the most basic part of a component.



The test page of mask component.

    <!-- The mask component that will cover
        its children by a mask -->
    <mask hflex="1">
        <button label="ZK Website" />
        <iframe width="100%"

The java class of mask comopnent, do nothing, just extends XulElement so it can be used as a ZK component.

package custom.zk.components.quicknote;

import org.zkoss.zul.impl.XulElement;

 * java class for mask component,
 * do nothing, just extends XulElement
 * @author benbai123
public class Mask extends XulElement {
    private static final long serialVersionUID = 9175798878576173600L;


The widget class of mask component, do nothing, just provide the zclass.

 * Widget class of mask component,
 * do nothing, just provide the zclass
custom.zk.components.quicknote.Mask = zk.$extends(zul.Widget, {
    getZclass: function () {
        var zcls = this._zclass;
        return zcls? zcls : 'z-mask';


Define the redraw function that output the html code of mask component.

 * redraw for mask component,
 * wrap children with a div then cover them
function (out) {
    var uuid = this.uuid,
        zcls = this.getZclass();
    // output root dom element of this widget
    out.push('<div', this.domAttrs_(), '>');
    // output children
    for (var w = this.firstChild; w; w = w.nextSibling)
    // output mask that cover children
    out.push('<div id="', uuid, '-mask" class="', zcls,'-cover"></div>');


Define the style of the dom elements in mask component.

<%--// ------------------------------------------- --%>
<%--//                                             --%>
<%--//                Mask component               --%>
<%--//                                             --%>
<%--// ------------------------------------------- --%>
<%--// root element --%>
.z-mask {
    <%--// be the anchor of absolute positioned children --%>
    position: relative;
    overflow: hidden;
<%--// the mask that cover whole element --%>
.z-mask-cover {
    <%--// absoluted positioned --%>
    position: absolute;
    <%--// align the left-top corner of parent (root) element --%>
    left: 0px;
    top: 0px;
    <%--// cover whole root element --%>
    height: 100%;
    width: 100%;
    <%--// make it the top most element under root element --%>
    z-index: 99999;
    <%--// make this mask a little bit visible --%>
    background-color: #ccc;
    opacity: 0.35;


Define components under "custom.zk.components.quicknote"

NOTE: more components will be added with other articles later

<package name="custom.zk.components.quicknote" language="xul/html" depends="zul">
    <widget name="Mask" />
    <!-- more components will be added -->


Define all components in the project

NOTE: more components will be added with other articles later

        <zk-version>5.0.0</zk-version><!-- or later -->

    <!-- the first, basic mask component -->

    <!-- more components will be added -->


Full project at github


No comments:

Post a Comment