Custom Components

The composite Property

When you work with composite components programmatically, every component within a composite has a property called composite that points to the containing composite object. This makes it easy to define actions for a composite that refer to methods of the composite class. You can see this in the first <button> element from the example above:

<button caption="OK"
        onclick="zenThis.composite.okBtn();"/>

The onclick attribute value for this <button> definition uses zenThis.composite to represent the containing composite object. This convention allows the <button> to call the okBtn method that is defined within the composite class.

Composites and Panes

To review panes and how their contents are defined, see the section “Panes” in the “Zen Layout” chapter of Using Zen.

When a <pane> component is placed within a composite element, the contents of the pane can be defined within the composite class (or subclass of the composite). At runtime, the composite first looks for a pane with a given name within the current page; if it does not find it there, it looks within the composite class.

Package for Custom Component Classes

InterSystems suggests you use one class package for all your custom component classes. There are several reasons for these conventions:

• The Zen framework automatically generates JavaScript and CSS stylesheet include files for your custom components. These files are generated on a per-class-package basis, so it is much easier to organize this if your custom components are contained within their own package.

• You might encounter compile order issues when a Zen page references a custom component, or when a Zen page references a composite component that includes a custom component. There are several ways to prevent compile order issues, as described in the next section, “Compile Order for Custom Component Classes.” One approach is to place all custom components in one package and ensure that your build procedure compiles that package before any package that contains Zen page classes.

When you reference the custom component in a Zen page XData block, do not use the package name. Use only the class name, as shown in the example in the next section, “XML Namespace for Custom Component Classes.”

XML Namespace for Custom Component Classes

Custom components need their own XML namespace to avoid naming conflicts with other components. Define and reference this namespace as follows:

• Provide the NAMESPACE parameter in each custom component class that you create. In the following example:

  • The custom component class name is:

    myCustom

  • The namespace is:

    http://www.mycompany.com/mycomponents

  
  Class MyPackage.myCustom Extends %ZEN.Component.textarea
  {
  
  /// This is the XML namespace for this component.
  Parameter NAMESPACE = "http://www.mycompany.com/mycomponents";
  
  /// This Style block contains component-specific CSS style definitions.
  XData Style
  {
  }
  
  /* Here is the rest of the class... */
  }

  

• Define a prefix for the namespace at the beginning of each XData block that references a custom component. Then, when referencing the custom component, use the prefix. In the following example:

  • The custom component class name is:

    myCustom

  • The namespace is:

    http://www.mycompany.com/mycomponents

  • The prefix is:

    myco

  XData demoPane [ XMLNamespace = "http://www.intersystems.com/zen" ]
  {
  <pane xmlns="http://www.intersystems.com/zen" 
        xmlns:myco="http://www.mycompany.com/mycomponents" 
        valign="top" >
    <myco:myCustom id="DemoText" name="DemoText" 
                   label="Operator Instructions:" 
                   cols="32" rows="8" 
                   title="Type comments and drag text into the editing area" 
                   hint="Describe how to use the product at this step." 
                   enclosingClass="myValid" />
    <hgroup align="center">
      <button caption="Clear" onclick="zenPage.clearAllValues()" />
      <button caption="Revert" onclick="zenPage.revertToSaved()" />
      <submit caption="Save" />
    </hgroup>
  </pane>
  }

  

InterSystems suggests that you define one XML namespace to use for all of your custom components, and use that XML namespace only for custom components.

Compile Order for Custom Component Classes

You might encounter compile order issues when a Zen page references a composite or custom component. The symptom of a compile order issue is when you receive a compile-time error message that you can fix by simply recompiling your code. In these cases, to prevent error messages and compile the application correctly, your build procedure must compile the classes in order beginning at the lowest level class and working upward, as follows:

1. Custom components. These are the lowest level classes for the compile order, so compile them first.

2. Composite components. These might reference custom components, so compile them after any custom components.

3. Pages. These might reference composite or custom components, so compile pages last, after you have already compiled custom and composite components.

There are several ways to prevent issues with compile order in Zen applications:

• Allow all classes to remain in the same package, but provide the DependsOn keyword in higher-level classes that need to reference lower-level classes. This is easiest to achieve when there are a small number of classes and not much layering of references to other classes. Simply place a DependsOn statement at the beginning of each higher-level class definition that references a lower-level class. The DependsOn value must identify the package and class name of the lower-level class. For example:

  
  Class MyPackage.MyZenPage Extends %ZEN.Component.page 
                            [ DependsOn = MyPackage.myCustom ]
  {
  /* Here is the rest of the class... */
  }

  

• For larger applications, InterSystems recommends that you place all custom component classes in one package, all composite components in a second package, and all Zen page classes in a third package. Ensure that your build procedure compiles these three package in the proper order, from the lowest to the highest level, by invoking separate commands to compile each package individually.

• It is also possible to allow larger applications to keep all classes in the same package if you assign the classes to separate compile groups. You can do this by adding the System keyword in the lower-level classes to sort them into compile groups, as follows:

  1. Set custom component classes to [System=3] so these are compiled first.

  2. Set composite components to [System=4] so these are compiled next.

  3. Provide no System keyword or value for the remainder of the application classes, so these are compiled last.

  You can set the System keyword in Studio. Setting the value for this property to 3 or 4 has the desired result. A value of 0 is the default value; it is the same as having no System value set for the class.

  Caution:

  InterSystems strongly recommends you do not use the value 1 or 2 for the System keyword. Values larger than 4 are not supported and the Studio Inspector does not allow you to choose them.

Zen Component Wizard

Use the Studio New Zen Component Wizard to create a new Zen component class. You can start the wizard using the Studio File New command, selecting the Zen tab, and clicking the New Zen Component icon.

Component Base Classes

When creating a new component, you must choose a base class for it. There are five significant options to choose from. The following figure and table summarize the choices.

Component Class Parameters

Depending on the base class you choose for your custom component, various class parameters are available for your use. Each of the component base classes sets its class parameters to values that are typically useful for that type of component. You can reset these values if you wish. The following table describes the class parameters that are most likely to be of interest.

For others, you may examine the Class Reference documentation for the your base class, as follows: Start the InterSystems online documentation. Select Class Reference from the menu bar at the top of the documentation home page. Choose the %SYS namespace and %ZEN.Component or %ZEN.SVGComponent package. Click on the class name.

XData SVGStyle

Style does not apply to Zen SVG components. Zen SVG components use XData SVGStyle.

To define styles for a custom Zen SVG component class, you can provide an XData SVGStyle block and add CSS statements between the <style type="text/css"> tag and the closing </style> tag. For example:

XData SVGStyle
{
<style type="text/css">
.customSVGComponent {
  fill: url(#myGrad);
  stroke: black;
  stroke-width: 2px;
}
</style>
}

XData SVGDef

The XData SVGStyle example above is from the class ZENTest.customSVGComponentOpens in a new tab in the SAMPLES namespace. It refers to a color myGrad as the fill color for the customSVGComponent shape.

myGrad is defined in the same class, but in a separate block called XData SVGDef. This block defines myGrad as a shaded gradient from blue to red:

XData SVGDef
{
<defs>
<linearGradient id="myGrad" x1="0%" y1="0%" x2="0%" y2="100%">
<stop offset="0%" style="stop-color:darkblue" />
<stop offset="30%" style="stop-color:#FF00FF" />
<stop offset="70%" style="stop-color:#FF00FF" />
<stop offset="100%" style="stop-color:darkred" />
</linearGradient>
</defs>
}

Zen Color Definitions

The built-in class %ZEN.SVGComponent.svgPageOpens in a new tab provides an XData SVGDef block with several useful color definitions:

• The glow-silver color produces a metallic look for instrumentation items such as the <speedometer> meter.

• Meters such as the traffic light use glow-red, glow-yellow, and glow-green for indicator lamps.

• Lamp colors glow-blue, glow-purple, glow-orange, and glow-teal are also available.

<svgFrame> always references this class, or some subclass of it, through its svgPage attribute, so these colors are always available to any SVG component.

Naming Conventions

There are case-sensitive naming conventions for properties in Zen classes. For details, see the section “Zen Naming Conventions” in the “Zen Tutorial” chapter of Using Zen. These conventions may be summarized as follows:

• Client-only properties: myProperty

• Server-only properties (the % is essential): %MyProperty

• Properties that invoke an event handler via Javascript: onmousedown

• Properties that identify a server-side callback method: OnCreateDataSet

• Other properties: myProperty

XML Projection

All Zen components are derived from the %XML.AdaptorOpens in a new tab class and use its mechanisms for defining their XML behavior. If you would like more detail about this, see Projecting Objects to XML. In particular, for the XMLPROJECTION parameter introduced in this topic, see the section “Controlling the Projection for Simple Properties,” which contains a table that describes the effects of each possible value of XMLPROJECTION: "attribute", "element", "wrapped", "none", and more.

All simple properties of Zen components should have an XMLPROJECTION value of "attribute". If you do not want to make a property visible via XML, set its XMLPROJECTION parameter to "none" as in the following example:

Property beeswax As %ZEN.Datatype.string(XMLPROJECTION="none");

Datatypes from the %ZEN.Datatype package use a default XMLPROJECTION value of "attribute" so that they are projected as XML attributes. Zen datatypes offer many conveniences when you are defining properties in a custom component class. For details, see the section “Datatype Classes.”

setProperty Method

If you add a property to a custom component class, you must override the setProperty method in the subclass to implement cases for each property that you have added to the class. You can default to the superclass method for properties of the superclass. There is an example of this practice in this chapter. See the sample component class in the section “Helper Methods for %DrawHTML.”

Datatype Parameters

All Zen classes inherit (from %ZEN.componentParametersOpens in a new tab) the following set of property parameters, which you can apply to any property you add to a Zen class. The property does not need to have a Zen datatype to use these parameters:

• ZENCLIENTONLY

• ZENENCRYPT

• ZENEXPRESSION

• ZENLOCALIZE

• ZENSETTING

Datatype Classes

For convenience, Zen provides a set of datatype classes that you can use when defining properties in Zen classes. The datatype classes are in the %ZEN.Datatype package. The following table lists them.

When you define new Zen classes, you are free to use any datatype classes you wish. Using the %ZEN.Datatype classes makes it easier to understand the purpose of a property in the context of a web application. Also, in many cases datatype classes automatically enable features that you would otherwise have to encode yourself, including easy localization, event handler conventions, and language-independence for Boolean values and list arrays.

Fundamentally, all Zen datatypes classes are strings. All of the datatypes listed in the following table share the same base class, %ZEN.Datatype.datatypeOpens in a new tab, whose value is defined as type %Library.StringOpens in a new tab. As you can see from the entries in the table, each of these strings is interpreted by its subclass in a uniquely useful way.

Helper Methods for %DrawHTML

The Zen framework defines three server-side helper methods for use in the %DrawHTML method for custom components: %MakeId, %Attr, and %GetEventHandlers. The class code for <button> shows one way to use these methods effectively in %DrawHTML:

Class %ZEN.Component.button Extends control
{

Parameter DEFAULTCONTROLCLASS = "button";

/// Caption displayed for this button.<br>
/// This is a localized value.
Property caption As %ZEN.Datatype.caption;

/// defines style sheet used by this component
XData Style
{
<style type="text/css">
/* @doc="Style for button (input)." */
.button {
}
</style>
}

Method %DrawHTML()
{
  Set disabled = $S(..disabled:"disabled",1:"")
  Set tIgnore("onchange") = ""
  &html<
  <input type="button" class="#(..controlClass)#"
  id="#(..%MakeId("control"))#" #(..%Attr("title",..title))#
  #(..%Attr("name",..name))# #(..%Attr("value",..caption))# #(disabled)#
  #(..%Attr("style",..controlStyle))# #(..%GetEventHandlers(.tIgnore))#>
  >
}

/// This method fills in reasonable default values for
/// this control. Used by tools (such as Control Tester) to
/// dynamically create controls.
Method %SetDefaultValues()
{
  Set ..caption = "Button"
}

/// Set the value of a named property.
ClientMethod setProperty(property, value, value2) [ Language = javascript ]
{
  switch(property) {
  case 'caption':
    this.caption = value;
    var el = this.findElement('control');
    if (el) {
      el.value = this.caption;
    }
    break;
  case 'value':
    // do not set control value; just internal value
    this.value = value;
    break;
  default:
    // dispatch
    return this.invokeSuper('setProperty',arguments);
  }
  return true;
}
}

The following topics discuss how each of the %DrawHTML helper methods is used:

• %MakeId — Generate the id value for the HTML element that displays the component on the page. Use a consistent naming scheme so that the client-side method findElement can find the HTML element on the page.

• %Attr — Assign a value to an attribute of the HTML element that displays the component on the page. This method may be called repeatedly to assign values to all the HTML attributes required to render the component.

• %GetEventHandlers — Retrieve all of the event handling information from the component definition, so that the HTML representation of the component can correctly match each user event with the code that should execute.

Identifying HTML Elements

The %MakeId server-side method ensures uniqueness for the id of every HTML element on the output page. The example in the “Helper Methods for %DrawHTML” section calls %MakeId from embedded HTML to set the id for the HTML <input> element as follows:

id="#(..%MakeId("control"))#"

%MakeId concatenates the string provided by the caller with the underscore character “_” followed by the unique sequential number that Zen assigns to every component it places on the page. It then gives this identifier to Zen to use as the value for the id attribute in the enclosing <div> for the element. Additionally, if the component is part of a repeating group, Zen adds a further underscore character “_” followed by the tuple number.

Thus, if you view the source of any generated Zen page you see enclosing <div> elements with generated id values like spacer_23 in the following example:

<div class="spacer" id="spacer_23" style="width:20px;"/>

The following more complex excerpt shows how Zen provides unique HTML id values for each element in a repeating group of radio buttons. This excerpt is part of the page that results when Zen renders the class ZENDemo.FormDemoOpens in a new tab from the SAMPLES namespace:

<tr valign="top">
<td style="padding: 4px; padding-left: 5px; padding-right: 5px;" >
<span id="zenlbl_26" class="zenLabel"  >Marital Status:</span>
<div class="zendiv" id="MaritalStatus" >
<input type="hidden" id="hidden_26" name="$V_MaritalStatus" value="">
<span class="radioSetSpan"><input type="radio" id="textRadio_1_26"
      name="r26" value="S" onclick="zenPage.getComponent(26).clickItem(1);">
   <a class="radioSetCaption" id="caption_1_26" href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(1);return false;">
      Single</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_2_26"
      name="r26" value="M" onclick="zenPage.getComponent(26).clickItem(2);">
   <a class="radioSetCaption" id="caption_2_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(2);return false;">
      Married</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_3_26"
      name="r26" value="D" onclick="zenPage.getComponent(26).clickItem(3);">
   <a class="radioSetCaption" id="caption_3_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(3);return false;">
      Divorced</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_4_26"
      name="r26" value="W" onclick="zenPage.getComponent(26).clickItem(4);">
   <a class="radioSetCaption" id="caption_4_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(4);return false;">
      Widowed</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_5_26"
      name="r26" value="O" onclick="zenPage.getComponent(26).clickItem(5);">
   <a class="radioSetCaption" id="caption_5_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(5);return false;">
      Other</a>&nbsp;</span>
</div>
</td>
</tr>

The client-side equivalent for %MakeId is a JavaScript method called makeId. The custom meter component examples use makeId.

Finding HTML Elements

When you are writing client-side code and need to access a specific HTML element on the page, you can use the findElement method. Its argument is the value that you assigned to the id attribute when placing the component on the page. findElement combines this string with the sequential identifier for the element on the output page to generate the appropriate HTML id for the element on the output page. It uses this information to obtain a pointer to the component object within the page object model for the rendered page, then returns that pointer so that you can use properties and methods of the component object.

Ordinary Zen components inherit findElement from %ZEN.Component.objectOpens in a new tab. For SVG components you must use findSVGElement from %ZEN.SVGComponent.svgComponentOpens in a new tab. The custom meter component examples use findSVGElement.

findElement and findSVGElement work correctly only if you have assigned HTML id values using %MakeId (on the server) or makeId (on the client).

Setting HTML Attribute Values

The %Attr server-side method assigns a value to an attribute of the HTML element that displays the component on the page. This method may be called repeatedly to assign values to all the HTML attributes required to render the component. The following sample %DrawHTML method uses %Attr in rendering the <button> component:

Method %DrawHTML()
{
  Set disabled = $S(..disabled:"disabled",1:"")
  Set tIgnore("onchange") = ""
  &html<<input type="button" class="#(..controlClass)#"
               id="#(..%MakeId("control"))#" #(..%Attr("title",..title))#
                   #(..%Attr("name",..name))# #(..%Attr("value",..caption))#
                   #(disabled)# #(..%Attr("style",..controlStyle))#
                   #(..%GetEventHandlers(.tIgnore))#>>
}

Suppose the value of the <button> controlStyle attribute is currently myActionStyle. As the %DrawHTML method outputs HTML, an expression in this format:

#(..%Attr("style",..controlStyle))#

Generates the following output:

style="myActionStyle"

Attaching Event Handlers to HTML Elements

The %GetEventHandlers server-side method gets all the event handler attributes for a given component and uses them to write out any event handler attributes for the HTML that displays that component in the output page.

For a list of the event handler attributes that you can specify for a control component on a Zen form, see the section “Control Attributes” in the “Zen Controls” chapter of Using Zen Components. The types of events covered by this list include mouse movements, mouse clicks, or key clicks. Other types of Zen component have event handlers, but Zen controls offer the single largest pool for comparison.

Preceding chapters have explained that to set up an event handler for a built-in Zen component you must specify a JavaScript expression as the value of the corresponding event handler attribute. Generally this JavaScript expression invokes a client-side method that serves as the “handler” for this event. Of course, if you set up the component this way you must also write the client-side method that is being invoked.

For custom components, you must take additional steps to connect each user event with its appropriate handler. This connection takes place in the %DrawHTML method for the custom component. Consider the %DrawHTML method for the <image> component:

Method %DrawHTML()
{
  #; handle onclick directly
  Set tIgnore("onclick")=""
  Set tIgnore("onchange")=""

  #; select image to display
  Set tSrc = ..src
  If (..streamId '= "") {
    Set tSrc = ##class(%CSP.Page).Link(
    "%25CSP.StreamServer.cls?STREAMOID="_$ZCVT(..streamId,"O","URL"))
  }

  #; disabled logic
  Set tSrc = $Case(..disabled,0:tSrc,:$S(..srcDisabled="":tSrc,1:..srcDisabled))

  &html<<img id="#(..%MakeId("control"))#"
             #($S(..onclick="":"",1:"class=""imageLink"""))#
             #(..%Attr("src",tSrc))#
             #(..%Attr("title",..title))#
             #(..%Attr("width",..width))#
             #(..%Attr("height",..height))#
             #(..%GetEventHandlers(.tIgnore))#
             onclick="zenPage.getComponent(#(..index)#).imageClick();"/>>
}

In the above example, some interesting things take place with regard to event handlers. The following line tells %GetEventHandlers to ignore any value provided for the onchange event handler, even if it discovers that there is such a value:

Set tIgnore("onchange") = ""

You must provide one such line for each event handler that you want to handle directly in %DrawHTML, as shown for onclick and onchange in the example above. Then, at the end of %DrawHTML, pass the variable tIgnore to %GetEventHandlers by reference, as shown in the example:

#(..%GetEventHandlers(.tIgnore))#

The %DrawHTML example above asks %GetEventHandlers to ignore onclick and onchange, but for different reasons in each case: <image> ignores onchange because it does not accept user input. <image> ignores onclick because it is designed to handle all onclick events in the same way, without permitting the Zen programmer to specify a different behavior in the page class. Therefore, it provides code in %DrawHTML to handle this event directly. Any event handlers that are not expressly ignored by %DrawHTML in this way are written out to the page exactly as defined by the Zen programmer.

Now consider this expression from the example above:

#($S(..onclick="":"",1:"class=""imageLink"""))#

This expression uses the ObjectScript $SELECT function to return the first true expression it encounters in a list of expressions. Looking at the expressions provided: If the <image> component’s onclick attribute value is an empty string, this statement writes an empty string. Otherwise, this statement formats the HTML element on the output page by writing out the following string:

class="imageLink"

The following expression directs the client-side HTML page to invoke the component’s imageClick method in response to any user mouse clicks on the corresponding HTML element.

onclick="zenPage.getComponent(#(..index)#).imageClick();"

The imageClick method is a client-side JavaScript method in the <image> component class. It uses the JavaScript helper method zenInvokeCallbackMethod to invoke onclick callback method for this <image> component. The imageClick method looks like this:

ClientMethod imageClick() [ Language = javascript ]
{
  if (!this.disabled) {
    // invoke callback, if present
    zenInvokeCallbackMethod(this.onclick,this,'onclick');
  }
}

Where the zenInvokeCallbackMethod arguments are as follows:

• this.onclick — The component’s onclick attribute value (a JavaScript expression that invokes a client-side JavaScript method)

• this — A pointer to the component object

• 'onclick' — The HTML name for the event (must be quoted)

This completes the connection between the HTML element, the event, and its handler. You must provide similar conventions for any event that you intend your custom component to support.

HTML for Dynamic Components

%DrawHTML works differently for components that change in response to runtime information or that are generated using SVG.

The <calendar> is an example of a component that writes no static HTML at all. Its %DrawHTML method simply sets the values of properties such as the currently selected month and date, in preparation for the more complex JavaScript method renderContents that is invoked whenever the page needs to redraw the calendar. renderContents and its helper methods generate an array of dynamic HTML statements based on the user’s current selections of calendar month and date. For details, examine the class code for %ZEN.Component.calendarOpens in a new tab.

%OnDrawEnclosingDiv

If defined in a component subclass, this callback method, makes it possible for the subclass to inject additional HTML attributes into the component’s enclosing <div> element at runtime. %OnDrawEnclosingDiv has no input arguments. If implemented, the method should return a %StringOpens in a new tab value. The string must include a leading space to avoid conflict with other attributes that may already be modifying the <div> element.

%OnDrawTitleOptions

The .expando class offers a server-side callback method %OnDrawTitleOptions which, if defined in a subclass of .expando, provides a way to add content to the right side of the title bar when the <expando> has its framed attribute set to true. Any HTML written by %OnDrawTitleOptions is injected into the title bar of the <expando> when it is displayed. For details, see “<expando>” in the “Navigation Components” chapter of Using Zen Components.

Data Drag and Drop Methods

It is possible to provide values for the component attributes onafterdrag, onbeforedrag, ondrag, and ondrop each time you place a component on the page, as described in the “Drag and Drop” section of the “Zen Component Concepts” chapter of Using Zen. However, rather than requiring Zen application developers to set data drag and drop attributes per component, you can build the desired behavior into a custom control component. This way, when placing a component on the page, developers can simply choose the custom control, which already has the desired behavior.

If you want to customize data drag and drop for a custom control class, there is a group of methods in the base classes %ZEN.Component.componentOpens in a new tab and %ZEN.Component.controlOpens in a new tab that you can override. Each of these methods accepts one parameter, dragData, which is a pointer to a JavaScript object whose methods and properties are defined in the Zen client side library. These methods also call functions defined within the library, such as ZLM.setDragAvatar. For full details about any of these items, refer to the “Client Side Library” chapter in this book.

The following table traces the sequence of internal events when drag and drop occurs between a source Zen component and a target Zen component. During these events, certain JavaScript methods in the source and target component classes call certain JavaScript functions within the Zen client side library. The component methods are triggered automatically by the Zen framework. When you customize data drag and drop for a custom control class, you can change the details of what happens inside these methods when they are automatically invoked.

There are several methods in the base classes %ZEN.Component.componentOpens in a new tab and %ZEN.Component.controlOpens in a new tab that are designed for you to override. The next several sections describe them. Other methods in the previous table are part of the Zen framework, and InterSystems recommends that you do not attempt to customize them. The methods designed for override are:

• getDragData

• dragStartHandler

• dragFinishHandler

• dropStartHandler

getDragData

getDragData is a JavaScript method that is called automatically each time the user begins a drag operation on any control or <image> component. Other components do not support the getDragData method. The base class for control components, %ZEN.Component.controlOpens in a new tab, implements a base version of getDragData that looks like the following example. Its purpose is to set the text and value fields in the dataDrag object.

ClientMethod getDragData(dragData) [ Language = javascript ]
{
  dragData.value = this.getValue();
  if (null != this.text) {
    // if there is a text property, use it as the text value
    dragData.text = this.text;
  }
  else {
    dragData.text = dragData.value;
  }
  return true;
}

Subclasses of %ZEN.Component.controlOpens in a new tab can override getDragData to provide customized behavior. It does not matter what happens inside the method as long as it sets values for dataDrag.text and dataDrag.value before it returns true. The next example shows how the class %ZEN.Component.imageOpens in a new tab overrides getDragData. This method assigns the string value of the <image> text attribute as both the logical value and the display value to be dragged:

ClientMethod getDragData(dragData) [ Language = javascript ]
{
  dragData.value = this.text;
  dragData.text = this.text;
  return true;
}

dragStartHandler

dragStartHandler is a JavaScript method that is automatically called whenever a drag operation is started within a component. The base class for control components, %ZEN.Component.controlOpens in a new tab, implements a base version of the dragStartHandler method, which looks like the following example. This dragStartHandler method does the following:

• Calls getDragData to set dragData.text and dragData.value

• Creates an avatar (icon) to represent the field as it is dragged across the page

• Calls a client side library function (ZLM.setDragAvatar) to use this icon

ClientMethod dragStartHandler(dragData) [ Language = javascript ]
{
  // get drag data
  if (!this.getDragData(dragData)) {
    return false;
  }

  // avatar
  var icon = this.getEnclosingDiv().cloneNode(true);
  icon.style.position="absolute";
  icon.style.border ="1px solid darkgray";
  icon.style.background ="#D0D0F0";
  ZLM.setDragAvatar(icon);

  return true;
}

Subclasses of %ZEN.Component.controlOpens in a new tab can override dragStartHandler to provide customized behavior. For example, the class %ZEN.Component.abstractListBoxOpens in a new tab overrides dragStartHandler as shown in the next example. This example does the following:

• Omits any call to getDragData.

• Acquires a pointer (dragItem) to the specific list item where the drag began

• Finds the exact pointer (anchor) to this item within the list control

• Sets the sourceItem, value, and text fields in the dragData object

• Creates an avatar (icon) to represent the field as it is dragged across the page

• Calls a client side library function (ZLM.setDragAvatar) to use this icon

ClientMethod dragStartHandler(dragData) [ Language = javascript ]
{
  var ok = false;
  var dragItem = this._dragSource;
  if (null != dragItem) {
    delete this._dragSource;
    var anchor = this.findElement('item_' + dragItem);
    if (anchor) {
      dragData.sourceItem = dragItem;
      ok = true;
      dragData.value = this.getOptionValue(dragItem);
      dragData.text = this.getOptionText(dragItem);

      // avatar
      var icon = anchor.cloneNode(true);
      icon.style.position ="absolute";
      icon.style.width = this.getEnclosingDiv().offsetWidth + 'px';
      icon.style.border = "1px solid darkgray";
      ZLM.setDragAvatar(icon);
    }
  }
  return ok;
}

dropStartHandler

dropStartHandler is a JavaScript method that is automatically called whenever a drop operation is started within a component. The base class for control components, %ZEN.Component.controlOpens in a new tab, implements a base version of dropStartHandler that looks like the following example. It sets the value of the target control to dragData.toString(). This value was previously set by the activities of other drag and drop methods in the class. Generally it is the value acquired from the source control.

ClientMethod dropStartHandler(dragData) [ Language = javascript ]
{
  this.setValue(dragData.toString());
  return true;
}

Subclasses of %ZEN.Component.controlOpens in a new tab can override dropStartHandler to provide customized behavior. For example, the class %ZEN.Component.listBoxOpens in a new tab overrides the base control dropStartHandler as shown in the next example. This example does the following:

• Gets the value and text fields from the dragData object.

• If this <listBox> is receiving a drop from some other component:

  Call appendOption to:

  • Create a new list option that has the value and text fields as its logical and display values

  • Append this new option to the <listBox>

  • Redisplay the <listBox>

• If this <listBox> is receiving a drop from itself:

  • Call the client side library function ZLM.getDragInnerDestination to retrieve the identifier for the innermost enclosing <div> where the drag operation ended.

  • Use this to calculate the appropriate dragData.targetItem identifier.

  • Call moveOption to:

    • Move the list option at position dragData.sourceItem to the position identified dragData.targetItem

    • Shift the other list options to make room

    • Redisplay the <listBox>

ClientMethod dropStartHandler(dragData) [ Language = javascript ]
{
  var value = dragData.value;
  var text = dragData.text;

  if (this != dragData.sourceComponent) {
    // drag from another component: append
    this.appendOption(value,text);
  }
  else {
    // move item within this list
    var tgtId = ZLM.getDragInnerDestination().id;
    var tgtIndex = -1;
    if (tgtId && tgtId.indexOf('item')!=-1) {
      tgtIndex = tgtId.split('_')[1];
    }
    dragData.targetItem = tgtIndex;
    var srcIndex = dragData.sourceItem;
    this.moveOption(srcIndex,tgtIndex);
  }
  return true;
}