Client Side Library
The chapter “Client Side Layout Managers” describes the default client side layout functionality built into Zen. Zen also offers a client side library module that allows you to override Zen defaults to provide extremely fine control over all client side activities for your application.
Parameter JSINCLUDES = "zenCSLM.js";
By convention, the names of entities defined in the client side library use the prefix ZLM followed by a dot, as in ZLM.setDragAvatar or ZLM.getDragInnerDestination. You can think of the ZLM prefix as a namespace that keeps the library entities distinct from other functions that you might define when working with Zen.
Writing Custom Drag and Drop Methods
This section describes parts of the library that are important when you are customizing drag and drop methods for custom components, as outlined in the “Data Drag and Drop Methods” section in the chapter “Custom Components.”
|dataDrag.toString()||This function returns a string that is equal to the value of the dataDrag.text property, if defined, otherwise the dataDrag.value property.|
|dataDrag.value||The logical value of the “source” control, which is the control whose value is being dragged.|
|dataDrag.text||The display value of the source control. If this is not available, the logical value is used.|
|dataDrag.sourceComponent||A pointer to the source control.|
|dataDrag.targetComponent||The logical value of the “target” control, which is the control onto which the value is being dropped.|
|dataDrag.sourceItem||A pointer to a specific data field within the source control. For example, if the control is a list box it may contain several list entries. Only one of these entries provides the data item that is being dragged.|
|dataDrag.targetItem||A pointer to a specific data field within the target control. This is the field onto which the data item is being dropped. For example, if the control is a list box this identifies a specific item within the list.|
The Zen client side library module provides the following functions to support custom drag and drop methods.
Returns a pointer to the enclosing <div> for the Zen element where the current drag operation ended.
Returns a pointer to the innermost enclosing <div> element that initiated the current drag operation. This <div> is a descendant of the enclosing <div> for the Zen element that would be returned by ZLM.getDragSource.
Returns a pointer to the innermost enclosing <div> element where the current drag operation ended. This <div> is a descendant of the enclosing <div> for the Zen element that would be returned by ZLM.getDragDestination.
Returns a pointer to the enclosing <div> for the Zen element that initiated the current drag operation.
Allows a user-defined dragStartHandler to set the icon to use as the drag avatar of the object being dragged. The newDiv argument is the pointer to an enclosing <div> object, which can be set up for the call to ZLM.setDragAvatar as shown in the following example, and in other examples in the section “Data Drag and Drop Methods”:
Debugging Client Side Code
This topic describes a set of Zen client side library module functions that support debugging by logging messages to a console window devoted to Zen client side activities. The following is a sample message console window. The output in this example reflects calls to ZLM.cerr and ZLM.dumpObj. These are only two of the available functions.
If a message console window is not already open as a result of a previous call to ZLM.showMsgConsole, any of the logging functions described in this section has the effect of opening the message console window. If there is a message console window already open, the logging function keeps writing to that window.
&js<ZLM.cerr("We are now in a ZenMethod");>
This way, activities on both the server and the client side can write to the same message console window, showing the actual sequence of activities on both sides. The window stays open until full control returns to the server, for example when a form is submitted and its server-only method %OnSubmit executes. At that time the window automatically closes.
The Zen client side library module provides the following logging functions.
ZLM.cerr("We are now in a client side method");
Write all known properties of a given object, as well as their current values, to the message console window.
obj can identify a component on the Zen page, or the page itself. You can retrieve a valid obj value for a component with the client-side function zen and the id specified in the component definition. For example, if you have:
<button id="myFavoriteObject" />
Then you can dump its current properties as follows:
ZLM.cerr("What's in my favorite object?"); ZLM.dumpObj(zen("myFavoriteObject"));
Alternatively, obj can be a pointer to the enclosing <div> for the Zen element whose contents are of interest. You can retrieve this value by first invoking the client-side function zen with the id specified in the component definition, and then invoking the client-side component method getEnclosingDiv. The result is a value that you can input to the ZLM.dumpObj function. For example:
var comp = zen("thatComponent"); var div = comp.getEnclosingDiv(); ZLM.dumpObj(div);
To display the entire DOM tree, use document.body as the root; for example:
ZLM.cerr("What does the DOM for the entire page look like right now?"); ZLM.dumpDOMTreeGeometry(document.body);
Alternatively, root can be a pointer to the enclosing <div> for the Zen component whose DOM structure is of interest. You can retrieve this value by first invoking the client-side function zen with the id specified in the component definition, and then invoking the client-side component method getEnclosingDiv. The result is a value that you can input to the ZLM.dumpDOMTreeGeometry function. For example:
var comp = zen("secondGroupFromLeft"); var div = comp.getEnclosingDiv(); ZLM.dumpDOMTreeGeometry(div);
The call to getEnclosingDiv returns an HTML <div> element that we use as a wrapper around Zen components that might have multiple DOM nodes associated with them. This convention is designed to make sure that the DOM tree branches off in an orderly fashion. If the return value is used as input to ZLM.dumpDOMTreeGeometry you get a snapshot of the HTML structure created by the call to %DrawHTML for this component, plus any modifications to that structure resulting from applied stylesheets and/or "onload" client-side post-processing.
Report all known style properties of a given component to the message console window. div is a pointer to the enclosing <div> for the Zen component whose style properties are of interest.
You can retrieve the value of div by first invoking the client-side function zen with the id specified in the component definition, and then invoking the client-side component method getEnclosingDiv. The result is a value that you can input to the ZLM.dumpElementStyle function. For example:
var comp = zen("advancedOptions"); var div = comp.getEnclosingDiv(); ZLM.dumpElementStyle(div);