ZK provides several skeletal implementations to minimize the effort required to implement a component.
AbstractComponent is the most base skeletal implementation. Use it only if the component you implement is for non-HTML clients (such as mobile devices).
AbstractComponent implements the redraw method to support molds, annotations, ID space, page association, parent-children relationship, event listener registration, serialization, clone, and all component APIs.
The use of AbstractComponent is straightforward: just implement your own methods – no abstract method to implement at all. For example,
public class MyComp extends org.zkoss.zk.ui.AbstractComponent {
private Object _value;
public Object getValue() {
return _value;
}
public void setValue(Object value) {
_value = value;
}
}
In addition to Component and ComponentCtrl, AbstractComponent also provides a collection of utilities to minimize the effort of the implementation.
AbstractComponent provides three kinds of methods to communicate with the client: invalidates, smart updates and AU responses. Invalidates notify ZK that a component needs to be redrawn completely. Smart updates notify ZK that a property of a component has been changed. AU responses allows a handle to ask the view to do anything it wants, such as change focus, start a timer, execute a piece of JavaScript codes and so on.
public class MyComp extends org.zkoss.zk.ui.AbstractComponent {
private String _label = "";
public String getLabel() {
return _label;
}
public void setLabel(String label) {
if (!label.equals(_label)) {
_label = label;
smartUpdate("label", _label);
}
}
public void updateContent(Object value) {
//whatever...
invalidate();
}
}
The communication between the view and the handle is one of the most important topic. We will discuss it later more detailedly.
To encapsulate API that are used only for component development, we introduce a concept called extra controls (aka., extra interfaces). If a component needs to provide some extra interfaces that will be used only for component development, it can override the newExtraCtrl method to instantiate an instance carrying the extra interfaces. For example, Slider allows the client to change the position of the slider, and then it has to implements the org.zkoss.zk.ui.ext.client.Scrollable interface. As depicted below, Slider first implements the ExtraCtrl class to implement the Scrollable interface. Then, Slider overrides newExtraCtrl to instantiate an ExtraCtrl instance.
public class Slider extends org.zkoss.zk.ui.HtmlBasedComponent {
private int _curpos;
protected Object newExtraCtrl() {
return new ExtraCtrl();
}
protected class ExtraCtrl extends HtmlBasedComponent.ExtraCtrl
implements Scrollable {
public final void setCurposByClient(int curpos) {
_curpos = curpos;
}
}
}
Notice that you generally have to extend from base class's extra controls, such that it inherits all extra controls. In the above case, it extends from the HtmlBasedComponent.ExtraCtrl class.
If you are implementing a component for HTML-based browser, you might consider to extend from HtmlBasedComponent. It extends from AbstractComponent to provide more HTML features, such as CSS style, CSS class, width, height, drag-and-drop, tooltip text, and so on. By extending from HtmlBasedComponent, your component inherits the HTML features for free – no special initialization, implementation, or invocation is required.
In additions, it provides
|
Name |
Description |
|---|---|
|
getInnerAttrsgetOuterAttrs |
HtmlBasedComponent assumes the view might have nested tags – the outer and inner tags. Then, getInnerAttrs and getOuterAttrs are used to generate the attributes for the inner and outer tags correspondingly. If a component isn't implemented with the nested tags, it just concatenates the return of both methods as shown below. Refer to the next chapter for more detailed about the view. <span id="${self.uuid}"${self.outAttrs}${self.innerAttrs}>
</span>
|
|
getRealSclassgetRealStyle |
When getOuterAttrs is called, it invokes these two methods to generate the class and style attributes. By default, they delegate the invocation to getSclass and getStyle, respectively. If you need to add a CSS style (in addition to that an user specifies by calling setStyle), you can override getRealStyle. For exmple, protected String getRealStyle() {return super.getRealStyle() + "padding:5px;";
}
|
|
getAllOnClickAttrs |
Used to generate attributes for onClick, onDoubleClick and onRightClick events. If the component supports these events, it shall call back this method in getOuterAttrs. Then, if the application registers a listener for them, the event will be sent back from the client automically (non-deferrable; no JavaScript codes required). public String getOuterAttrs() {String attrs = super.getOuterAttrs();
String clkattrs = getAllOnClickAttrs();rerturn clkattrs != null ? attrs + clkattrs: attrs;
}
|
XulElement is the skeletal implementation for XUL components. If you want to implement a component that will be added to the xul/html language, this class is a good starting point.
XulElement extends from HtmlBasedComonent. It provides the XUL features, such as popup, context menu, tooltip and client-side-action.