ZK CDT: Create Custom Mask Component

Introduction

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.

Result

View demo online:
http://screencast.com/t/es25fmktpF4

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

Pre-request

ZK Component Development Tutorial: Getting Started
http://ben-bai.blogspot.tw/2012/08/zk-component-development-tutorial.html

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.

Program

mask.zul

The test page of mask component.

<zk>
    <!-- The mask component that will cover
        its children by a mask -->
    <mask hflex="1">
        <button label="ZK Website" />
        <iframe width="100%"
            height="1000px"
            src="http://www.zkoss.org/"></iframe>
    </mask>
</zk>

Mask.java

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

Mask.js

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

mask.js

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)
        w.redraw(out);
    // output mask that cover children
    out.push('<div id="', uuid, '-mask" class="', zcls,'-cover"></div>');
    out.push('</div>');
}

mask.css.dsp

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

zk.wpd

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 -->
</package>

lang-addon.xml

Define all components in the project

NOTE: more components will be added with other articles later

<language-addon>
    <addon-name>zkQuickNote</addon-name>
    <language-name>xul/html</language-name>
    <version>
        <version-class>custom.zk.components.Version</version-class>
        <version-uid>0.8.0</version-uid>
        <zk-version>5.0.0</zk-version><!-- or later -->
    </version>

    <!-- the first, basic mask component -->
    <component>
        <component-name>mask</component-name>
        <component-class>custom.zk.components.quicknote.Mask</component-class>
        <widget-class>custom.zk.components.quicknote.Mask</widget-class>
        <mold>
            <mold-name>default</mold-name>
            <mold-uri>mold/mask.js</mold-uri>
            <css-uri>css/mask.css.dsp</css-uri>
        </mold>
    </component>

    <!-- more components will be added -->
</language-addon>

Download

Full project at github
https://github.com/benbai123/ZK_Practice/tree/master/Components/projects/Components_Development__Series/001_walkthrough/ZKQuickNote

mask_component.swf
https://github.com/benbai123/ZK_Practice/blob/master/Components/demos/component_development_series/001_walkthrough/mask_component.swf