_global_
Class jq

java.lang.Object
  extended by _global_.jq

public class jq
extends java.lang.Object

Represents the object returned by the jq function. For example, jq('#id');

ZK 5 Client Engine is based on jQuery. It inherits all functionality provided by jQuery. Refer to jQuery documentation for complete reference. However, we use the global function called jq to represent jQuery. Furthermore, for documentation purpose, we use @{link jq} to represent the object returned by the jq function.

Notice that there is no package called _. Rather, it represents the global namespace of JavaScript. In other words, it is the namespace of the window object in a browser.

Diffirence and Enhancement to jQuery

jq jq(Object selector, Object context);

Refer jQuery as jq

First of all, the jQuery class is referenced as jq(), and it is suggested to use jq instead of $ or jQuery when developing a widget, since it might be renamed later by an application (say, overridden by other client framework). Here is an example uses jq:

jq(document.body).append("
");

Dual Objects

To extend jQuery's functionally, each time jq(...) or zk(...) is called, an instance of jq and an instance of jqzk are created. The former one provides the standard jQuery API plus some minimal enhancement as described below. The later is ZK's addions APIs.

You can retrieve one of the other with zk and jqzk.jq.

jq('#abc').zk; //the same as zk('#abc')
zk('#abc').jq; //the same as jq('#abc');

Extra Selectors

@tagName

jq is extended to support the selection by use of ZK widget's tagName. For example,

jq('@window');

Notice that it looks for the ZK widget tree to see if any widget whose className ends with window.

If you want to search the widget in the nested tag, you can specify the selector after @. For example, the following searches the space owner named x, then y, and finally z

jq('@x @y @z');
or search the element from the given attribute of the widget, you can specify the selector as follows. For example,
jq('@window[border="normal"]')

$id

jq is extended to support the selection by use of widget's ID (Widget.id), and then DOM element's ID. For example,

jq('$xx');

Notice that it looks for any bound widget whose ID is xx, and select the associated DOM element if found.

If you want to search the widget in the inner ID space, you can specify the selector after $. For example, the following searches the space owner named x, then y, and finally z

jq('$x $y $z');
or advanced search combine with CSS3 and @, you can specify like this.
jq('@window[border="normal"] > $x + div$y > @button:first');

A widget

jq is extended to support Widget. If the selector is a widget, jq will select the associated DOM element of the widget.

jq(widget).after('
'); //assume widget is an instance of Widget

In other words, it is the same as

jq(widget.$n()).after('
');

Extra Contexts

The zk context

jq('foo', zk);

With the zk context, the selector without any prefix is assumed to be the identifier of ID. In other words, you don't need to prefix it with '#'. Thus, the above example is the same as

jq('#foo')

Of course, if the selector is not a string or prefix with a non-alphnumeric letter, the zk context is ignored.

Extra Global Functions

The zk function

jq zk(Object selector);

It is the same as jq(selector, zk).zk. In other words, it assumes the zk context and returns an instance of jqzk rather than an instance of jq.

Other Extension

Not override previous copy if any

Unlike the original jQuery behavior, ZK's jQuery doesn't override the previous copy, if any, so ZK can be more compatible with other frameworks that might use jQuery. For example, if you manually include a copy of jQuery before loading ZK Client Engine, jQuery will refer to the copy of jQuery you included explicitly. To refer ZK's copy, always use jq.

Author:
tomyeh

Field Summary
 jqzk zk
          The associated instance of jqzk that provides additional utilities to jQuery.
 
Method Summary
static Array $$(String id, String subId)
          Returns an array of DOMElement that matches.
 void after(java.lang.Object content, Desktop desktop)
          Insert content after each of the matched elements.
static void alert(String msg, Map opts)
          Shows up a message.
 void append(java.lang.Object content, Desktop desktop)
          Append content to inside of every matched element.
 void before(java.lang.Object content, Desktop desktop)
          Insert content before each of the matched elements.
static Map borders()
          A map of the border style names: {l: 'border-left', t: 'border-top'...}.
static boolean clearSelection()
          Clears the current selection in the browser window.
static boolean confirm()
          It is the same as window.confirm
static String css(DOMElement elem, String name, String extra)
          An override function that provide a way to get the style value where is defined in the CSS file or the style object, rather than the computed value.
static String d2j(Date d)
          Marshalls the Date object into a string such that it can be sent back to the server.
 jq empty()
          Removes all children of the matched element from the DOM.
static java.lang.Object evalJSON(String s)
          Decodes a JSON string to a JavaScript object.
static Map filterTextStyle(Map styles, Array plus)
          Returns the text-relevant style of the specified styles (same as HTMLs.getTextRelevantStyle in Java).
static String filterTextStyle(String style, Array plus)
          Returns the text-relevant style of the specified style (same as HTMLs.getTextRelevantStyle in Java).
static void focusOut()
          Move the focus out of any element.
static DOMElement head()
          Returns the head element of this document.
 jq hide()
          Hides all matched elements from the DOM.
static int innerHeight()
          Returns the width of the viewport (visible part) of the browser window.
static int innerWidth()
          Returns the height of the viewport (visible part) of the browser window.
static int innerX()
          Returns the X coordination of the visible part of the browser window.
static int innerY()
          Returns the Y coordination of the visible part of the browser window.
static boolean isAncestor(DOMElement p, DOMElement c)
          Tests if one element (p) is an ancestor of another (c).
static boolean isOverlapped(Offset ofs1, Offset dim1, Offset ofs2, Offset dim2)
          Returns if the specified rectangles are overlapped with each other.
static Date j2d(String s)
          Unmarshalls the string back to a Date object.
static Map margins()
          A map of the margin style names: {l: 'margin-left', t: 'margin-top'...}.
static DOMElement newFrame(String id, String src, String style)
          Creates an IFRAME element with the specified ID, src and style.
static DOMElement newHidden(String name, String value, DOMElement parent)
          Creates a HIDDEN element
static DOMElement newStackup(DOMElement el, String id, DOMElement anchor)
          Creates a 'stackup' (actually, an iframe) that makes an element (with position:absolute) shown above others.
static String nodeName(DOMElement el)
          Returns the node name of the specified element in the lower case.
static boolean nodeName(DOMElement el, String tag1)
          Returns if the node name of the specified element is the same as one of the specified name (case insensitive).
static void onzsync(java.lang.Object obj)
          To register one object for the zsync invocation.
static Map paddings()
          A map of the padding style names: {l: 'padding-left', t: 'padding-top'...}.
static Map parseStyle(String style)
          Parses a string-type CSS style into a map of names and values of styles.
 void prepend(java.lang.Object content, Desktop desktop)
          Prepend content to the inside of every matched element.
static String px(java.lang.Integer v)
          Converting an integer to a string ending with "px".
static String px0(java.lang.Integer v)
          Converting an integer a string ending with "px".
 jq remove()
          Removes all matched elements from the DOM.
 jq replaceWith(Widget widget, Desktop desktop, Skipper skipper)
          Replaces the match elements with the specified HTML, DOM or Widget.
static int scrollbarWidth()
          Returns the width of the scrollbar
 jq show()
          Shows all matched elements from the DOM.
static void toJSON(java.lang.Object obj, java.lang.Object replace)
          Encodes a JavaScript object to a JSON string.
static void unzsync(java.lang.Object obj)
          To unregister one object for the zsync invocation.
static void zsync()
          To invoke the zsync method of the registered objects.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

zk

public jqzk zk
The associated instance of jqzk that provides additional utilities to jQuery.

Method Detail

nodeName

public static boolean nodeName(DOMElement el,
                               String tag1)
Returns if the node name of the specified element is the same as one of the specified name (case insensitive).

Parameters:
el - the element to test
tag1 - the name to test. You can have any number of names to test, such as jq.nodeName(el, "tr", "td", "span")
Returns:
boolean if the node name is the same as one of the specified names.
Since:
5.0.1

nodeName

public static String nodeName(DOMElement el)
Returns the node name of the specified element in the lower case.

Parameters:
el - the element to test. If el is null, an empty string is returned.
Returns:
String the node name.
Since:
5.0.1

px

public static String px(java.lang.Integer v)
Converting an integer to a string ending with "px".

It is usually used for generating left or top.

Parameters:
v - the number of pixels
Returns:
String the integer with string.
See Also:
px0(java.lang.Integer)

px0

public static String px0(java.lang.Integer v)
Converting an integer a string ending with "px".

Unlike px(java.lang.Integer), this method assumes 0 if v is negative.

It is usually used for generating width or height.

Parameters:
v - the number of pixels. 0 is assumed if negative.
Returns:
String the integer with string.
See Also:
px(java.lang.Integer)

$$

public static Array $$(String id,
                       String subId)
Returns an array of DOMElement that matches. It invokes document.getElementsByName to retrieve the DOM elements.

Parameters:
id - the identifier
subId - [Optional] the identifier of the sub-element. Example, jq.$$('_u_12', 'cave');.
Returns:
Array an array of DOMElement that matches the specified condition

isAncestor

public static boolean isAncestor(DOMElement p,
                                 DOMElement c)
Tests if one element (p) is an ancestor of another (c).

Notice that, if you want to test widgets, please use zUtl.isAncestor(java.lang.Object, java.lang.Object) instead.

Parameters:
p - the parent element to test
c - the child element to test
Returns:
boolean if p is an ancesotor of c.
See Also:
zUtl.isAncestor(java.lang.Object, java.lang.Object)

innerX

public static int innerX()
Returns the X coordination of the visible part of the browser window.

Returns:
int

innerY

public static int innerY()
Returns the Y coordination of the visible part of the browser window.

Returns:
int

innerWidth

public static int innerWidth()
Returns the height of the viewport (visible part) of the browser window. It is the same as jq(window).width().

Returns:
int

innerHeight

public static int innerHeight()
Returns the width of the viewport (visible part) of the browser window. It is the same as jq(window).height().

Returns:
int

scrollbarWidth

public static int scrollbarWidth()
Returns the width of the scrollbar

Returns:
int

isOverlapped

public static boolean isOverlapped(Offset ofs1,
                                   Offset dim1,
                                   Offset ofs2,
                                   Offset dim2)
Returns if the specified rectangles are overlapped with each other.

Parameters:
ofs1 - the offset of the first rectangle
dim1 - the dimension (size) of the first rectangle
ofs2 - the offset of the second rectangle
dim2 - the dimension (size) of the second rectangle
Returns:
boolean

clearSelection

public static boolean clearSelection()
Clears the current selection in the browser window.

Notice: jqzk.setSelectionRange(int, int) is used for the input-type elements, while this method is applied to the whole browser window.

Returns:
boolean whether it is cleared successfully
See Also:
jqzk.setSelectionRange(int, int), jqzk.enableSelection(), jqzk.disableSelection()

filterTextStyle

public static Map filterTextStyle(Map styles,
                                  Array plus)
Returns the text-relevant style of the specified styles (same as HTMLs.getTextRelevantStyle in Java).
>
jq.filterTextStyle({width:"100px", fontSize: "10pt"});
  //return {font-size: "10pt"}

Parameters:
styles - the styles to filter
plus - an array of the names of the additional style to include, such as ['width', 'height']. Ignored if not specified or null.
Returns:
Map the text-related styles

filterTextStyle

public static String filterTextStyle(String style,
                                     Array plus)
Returns the text-relevant style of the specified style (same as HTMLs.getTextRelevantStyle in Java).
>
jq.filterTextStyle('width:100px;font-size:10pt;font-weight:bold');
  //return 'font-size:10pt;font-weight:bold'

Parameters:
style - the style to filter
plus - an array of the names of the additional style to include, such as ['width', 'height']. Ignored if not specified or null.
Returns:
String the text-related style

parseStyle

public static Map parseStyle(String style)
Parses a string-type CSS style into a map of names and values of styles. It is usually used with jq.css(map) to update the CSS style of an element.

Parameters:
style - the style to parse
Returns:
Map a map of styles (name, value)

newFrame

public static DOMElement newFrame(String id,
                                  String src,
                                  String style)
Creates an IFRAME element with the specified ID, src and style.

Parameters:
id - ID (required)
src - the source URL. If omitted, an one-pixel gif is assumed.
style - the CSS style. Ingored if omitted.
Returns:
DOMElement

newStackup

public static DOMElement newStackup(DOMElement el,
                                    String id,
                                    DOMElement anchor)
Creates a 'stackup' (actually, an iframe) that makes an element (with position:absolute) shown above others. It is used to solve the layer issues of the browser.
  1. IE6: SELECT's dropdown above any other DOM element
  2. All browser: PDF iframe above any other DOM element. However, this approach works only in FF and IE, and FF doesn't position IFRAME well if two or more of them are with the absolute position.

Notice that you usually have to call jqzk.makeVParent() before calling this, since DIV with relative or absolute position will crop the child element. In other words, you have to make the element as the top-level element before creating a stackup for it.

To remove the stackup, call remove().

If you want to create a shadow, you don't need to access this method since Shadow has an option to create and maintain the stackup automatically.

Parameters:
el - the element to retrieve the dimensions. If omitted, the stackup is not appended to the DOM tree.
id - ID of the stackup (iframe). If omitted and el is specified, it is el.id + '$ifrstk'. If both el and id are omitted, 'z_ifrstk' is assumed.
anchor - where to insert the DOM element before (i.e., anchor will become the next sibling of the stackup, so anchor will be on top of the stackup if z-index is the same). If omitted, el is assumed.
Returns:
DOMElement

newHidden

public static DOMElement newHidden(String name,
                                   String value,
                                   DOMElement parent)
Creates a HIDDEN element

Parameters:
name - the name of the HIDDEN tag.
value - the value of the HIDDEN tag.
parent - the parent node. Ignored if not specified.
Returns:
DOMElement

head

public static DOMElement head()
Returns the head element of this document.

Returns:
DOMElement the head element
Since:
5.0.1

confirm

public static boolean confirm()
It is the same as window.confirmzk.alerting so widgets know to ignore onblur (since the focus will be back later).

It is strongly suggested to use this method instead of window.confirm.

Returns:
boolean whether the Yes button is pressed

alert

public static void alert(String msg,
                         Map opts)
Shows up a message. If opts.mode is os, this method is the same as window.alert, except it will set zk.alerting, so widgets (particularly input widgets) know to ignore onblur (since the focus will be back later).

It is strongly suggested to use this method instead of window.alert.

If opts is omitted or opts.mode is not os, it is similar to org.zkoss.zul.Messagebox.show() at the server.


jq.alert('Hi');
jq.alert('This is a popup message box', {mode:"popup", icon: "ERROR"});
jq.alert('With listener', {
        button : {
                YES: function () {jq.alert('Yes clicked')},
                NO: function () {jq.alert('No clicked')}
        }
});

Parameters:
msg - the message to show
opts - the options.
Allowed Options
Name Allowed Values Default Value Description
icon 'QUESTION', 'EXCLAMATION', 'INFORMATION', 'ERROR', 'NONE' 'INFORMATION' Specifies the icon to display.
mode 'overlapped', 'popup', 'modal' 'modal' Specifies which window mode to use.
title any string 'ZK' Specifies the message box's title.
desktop a desktop (Desktop) or null The current desktop Specifies which desktop this message box belongs to. You rarely need to specify it.
button a map (Map) of buttons. If null or empty, OK is assumed Specifies what buttons to display. The key is the button name, and the value is a function (Function) to execute when the button is clicked. The label is assumed to be msgzul[name.toUpperCase()]||name. Localized labels include OK, Cancel, Yes, No, Retry, Abort, Ignore, Reload. You can add your own labels by puttingit to msgzul.

onzsync

public static void onzsync(java.lang.Object obj)
To register one object for the zsync invocation. For example,
jq.onzsync(obj1);

Parameters:
obj - the object to register
Since:
5.0.1
See Also:
zsync(), unzsync(java.lang.Object)

unzsync

public static void unzsync(java.lang.Object obj)
To unregister one object for the zsync invocation. For example,
jq.unzsync(obj1);

Parameters:
obj - the object to register
Since:
5.0.1
See Also:
zsync(), onzsync(java.lang.Object)

zsync

public static void zsync()
To invoke the zsync method of the registered objects.

zsync is called automatically when zWatch fires onSize, onShow or onHide. It is useful if you have a DOM element whose position is absolute. Then, if you register the widget, the widget's zsync method will be called when some widget becomes visible, is added and so on.

For example, Window uses DIV to simulate the shadow in IE, then it can register itself in Widget.bind_(zk.Desktop, zk.Skipper, _global_.Array) and then synchronize the position and size of shadow (DIV) in zsync as follows.


bind_: function () {
  if (zk.ie) jq.onzsync(this); //register
...
},
unbind_: function () {
  if (zk.ie) jq.unzsync(this); //unregister
...
},
zsync: function () {
this._syncShadow(); //synchronize shadow
...
}

Notice that it is better not to use the absolute position for any child element, so the browser will maintain the position for you. After all, it runs faster and zsync won't be called if some 3rd-party library is used to create DOM element directly (without ZK).


margins

public static Map margins()
A map of the margin style names: {l: 'margin-left', t: 'margin-top'...}. It is usually used with jqzk.sumStyles(_global_.String, _global_.Array) to calculate the numbers specified in these styles.

Returns:
Map
See Also:
margins(), paddings()

borders

public static Map borders()
A map of the border style names: {l: 'border-left', t: 'border-top'...}. It is usually used with jqzk.sumStyles(_global_.String, _global_.Array) to calculate the numbers specified in these styles.

Returns:
Map
See Also:
margins(), paddings()

paddings

public static Map paddings()
A map of the padding style names: {l: 'padding-left', t: 'padding-top'...}. It is usually used with jqzk.sumStyles(_global_.String, _global_.Array) to calculate the numbers specified in these styles.

Returns:
Map
See Also:
margins(), borders()

focusOut

public static void focusOut()
Move the focus out of any element.

Notice that you cannot simply use jq(window).focus() or zk(window).focus(), because it has no effect for browsers other than IE.

Since:
5.0.1

css

public static String css(DOMElement elem,
                         String name,
                         String extra)
An override function that provide a way to get the style value where is defined in the CSS file or the style object, rather than the computed value.

Note that the function is only applied to the width or height property, and the third argument must be 'styleonly'.

For example,


jq.css(elem, 'height', 'styleonly');
or
jq.css(elem, 'width', 'styleonly');

Parameters:
elem - a Dom element
name - the style name
extra - an option in this case, it must be 'styleonly'
Returns:
String the style value.
Since:
5.0.6

evalJSON

public static java.lang.Object evalJSON(String s)
Decodes a JSON string to a JavaScript object.

It is similar to jq.parseJSON (jQuery's default function), except 1) it doesn't check if the string is a valid JSON 2) it uses eval to evaluate

Thus, it might not be safe to invoke this if the string's source is not trustable (and then it is better to use jq.parseJSON)

Parameters:
s - the JSON string
Returns:
Object the converted object.

toJSON

public static void toJSON(java.lang.Object obj,
                          java.lang.Object replace)
Encodes a JavaScript object to a JSON string. To decode, use jq.evalJSON(s), where s is a JSON string.

You can provide an optional replacer method. It will be passed the key and value of each member, with this bound to the containing object. The value that is returned from your method will be serialized. If your method returns undefined, then the member will be excluded from the serialization. Values that do not have JSON representations, such as undefined or functions, will not be serialized. Such values in objects will be dropped; in arrays they will be replaced with null. You can use a replacer function to replace those with JSON values. JSON.stringify(undefined) returns undefined.

The optional space parameter produces a stringification of the value that is filled with line breaks and indentation to make it easier to read.

If the space parameter is a non-empty string, then that string will be used for indentation. If the space parameter is a number, then the indentation will be that many spaces.

Example:


text = jq.toJSON(['e', {pluribus: 'unum'}]);
// text is '["e",{"pluribus":"unum"}]'

text = jq.toJSON([new Date()], function (key, value) {
    return this[key] instanceof Date ?
        'Date(' + this[key] + ')' : value;
});
// text is '["Date(---current time---)"]'

Parameters:
obj - any JavaScript object
replace - an optional parameter that determines how object values are stringified for objects. It can be a function.

d2j

public static String d2j(Date d)
Marshalls the Date object into a string such that it can be sent back to the server.

It works with org.zkoss.json.JSONs.d2j() to transfer data from client to server.

Parameters:
d - the date object to marshall. If null, null is returned
Returns:
String a string
Since:
5.0.5

j2d

public static Date j2d(String s)
Unmarshalls the string back to a Date object.

It works with org.zkoss.json.JSONs.j2d() to transfer data from server to client.

Parameters:
s - the string that is marshalled at the server
Returns:
Date the date object after unmarshalled back
Since:
5.0.5

replaceWith

public jq replaceWith(Widget widget,
                      Desktop desktop,
                      Skipper skipper)
Replaces the match elements with the specified HTML, DOM or Widget. We extends jQuery's replaceWith to allow replacing with an instance of Widget.

Parameters:
widget - a widget
desktop - the desktop. It is optional.
skipper - the skipper. It is optional.
Returns:
jq the jq object matching the DOM element after replaced

remove

public jq remove()
Removes all matched elements from the DOM.

Unlike jQuery, it does nothing if nothing is matched.

Returns:
jq this object

empty

public jq empty()
Removes all children of the matched element from the DOM.

Unlike jQuery, it does nothing if nothing is matched.

Returns:
jq this object

show

public jq show()
Shows all matched elements from the DOM.

Unlike jQuery, it does nothing if nothing is matched.

Returns:
jq this object

hide

public jq hide()
Hides all matched elements from the DOM.

Unlike jQuery, it does nothing if nothing is matched.

Returns:
jq this object

before

public void before(java.lang.Object content,
                   Desktop desktop)
Insert content before each of the matched elements.

Notice that this method is extended to handle Widget.

Refer to

after

public void after(java.lang.Object content,
                  Desktop desktop)
Insert content after each of the matched elements.

Notice that this method is extended to handle Widget.

Refer to

append

public void append(java.lang.Object content,
                   Desktop desktop)
Append content to inside of every matched element.

Notice that this method is extended to handle Widget.

Refer to

prepend

public void prepend(java.lang.Object content,
                    Desktop desktop)
Prepend content to the inside of every matched element.

Notice that this method is extended to handle Widget.

Refer to


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo