Other Zen Components

<iframe> Attributes

The Zen <iframe> component has the following attributes:

If you wish to change the contents of the frame from the client, you can do so programmatically by resetting the value of the src property of the iframe object.

When changing the src property value on the client side, do not simply set the property, as in:

var frame=zen('contentFrame');
frame.src='C:\myfile';

Instead, use the setProperty() method, as in:

var frame=zen('contentFrame');
frame.setProperty('src','C:\myfile');

Images as Button Controls

If you wish to place an image on a button control, so that you can define an onclick event or other types of event for it, use the <image> control, which gives greater control over event handling. For details, see the description of the <image> control in the chapter “Zen Controls.”

Rendering Image Data Streams

InterSystems advises that you do not use <iframe> to render image data streams. Instead, use <image> as described in the chapter “Zen Controls.” This convention is imperative when the image is in JPG format and the browser is Internet Explorer (IE). This topic explains the details.

Suppose you want to use an <iframe> to render content retrieved from the database via a CSP routine that serves up a data stream. The stream could be PDFs, GIFs, JPGs, Docs, RTFs, etc. It turns out that, when the image is in JPG format and the browser is IE, rendering JPG data in an <iframe> incapacitates core Zen functionality.

The root of the problem is in the way IE renders data streams.

When browsers like Firefox see that the data stream isn’t an HTML page, they create a dummy DOM to wrap around the incoming stream; GIFs and JPGs become HTML <IMG> tags with their src attribute set to the URI provided, PDFs automatically generate HTML <EMBED> tags to launch the viewer, etc. In these cases, a DOM is always created and the normal scoping rules of JavaScript execution apply.

IE is different. It does not create a DOM; it swaps out normal page processing in favor of a dedicated viewer for the content in question. For ordinary web pages this is usually not an issue. If you are just loading a picture or downloading a PDF, there is nothing to interact with the DOM, so it does not matter if the DOM is there or not.

The problem arises when the content is being loaded into an <iframe> under IE.

Content requiring an external plug-in, such a PDFs or RTFs, seem to work fine with IE. The embedded GIF viewer also seems to play well. The JPG viewer, however, does not. If a JPG image is loaded as a direct stream into an <iframe>, when IE initializes the embedded viewer it obliterates, not just the JavaScript execution space for the <iframe>, but the entire JavaScript namespace for the page, deleting global client-side variables and JavaScript function definitions. After the viewer is initialized, JavaScript continues to function outside the <iframe> for event callbacks and such, but chances are good that any client-side data initialized before the loading of the <iframe> has been reset to null.

The best cross-platform solution for dealing with cases like these is to use the Zen components <iframe> and <image> as follows:

• <iframe> for HTML documents or data streams requiring external plug-ins (such as PDFs)

• <image> to render data streams of types GIF, JPG or PNG

The only downside to this solution is that if streams are being retrieved from the database, two queries are required: one to determine the type of data being sent and a second to send the actual data. The overhead in this case is almost exclusively the network overhead, as the data volume is trivial. Therefore, the best practice for rendering data streams retrieved from the database is as follows:

1. Define the template display page with both an <iframe> and an <image>. Both components are initially hidden (hidden='true').

2. Query to find out what type of data is to be rendered.

3. Based on this query, set the src attribute of either the <iframe> or the <image> to the URI of the data stream and set the corresponding component to be visible (hidden='false')

4. When the page is closing, reset the displayed component to be hidden (hidden='true') so that the page is ready for the next data stream.

Other permutations are possible, but this is the basic idea. It is not necessary to use an <iframe> to display image data on a web page, and doing so with a JPG under IE breaks Zen, so do not use <iframe> for this purpose; use <image> instead.

<dynaView> OnGetViewContents Callback Method

<dynaView> gets its data by invoking a server-side callback method defined in the Zen page class. The method name is specified using the <dynaView> OnGetViewContents attribute, as shown in the following example. In this example, the method name is GetViewContents.

<dynaView id="view" viewType="details"
          OnGetViewContents="GetViewContents"
          onchange="zenPage.viewChange(zenThis);" >
  <parameter paramName="label" value="Draft" />
</dynaView>

A <dynaView> can contain zero or more <parameter> elements. Each <parameter> specifies an input parameter for the OnGetViewContents callback method. Each <parameter> may have the following attributes:

The OnGetViewContents callback method must have a signature that looks like this:

Method GetViewContents(
    ByRef pParms As %String,
    Output pContents As %String,
    Output pHeaders As %String) As %Status

Where:

• The method returns a %StatusOpens in a new tab value indicating success or failure.

• pParms represents any <parameter> elements defined by the <dynaView>. pParms is an array. Each member of this array uses its paramName as a subscript and its value as a value.

• pContents is a multidimensional array that describes the set of items that is displayed within the view box. The array is subscripted by item number (starting with 1). Each array element is a $List structure containing the following information. You can use the ObjectScript function $LISTBUILD ($LB) to create each list item for pContents, using statements such as the following inside the callback method:

    Set pContents(n) =
    $LB(textValue,logicalValue,icon,col2,col3)
  

  

  Where:

  • textValue is the value displayed for the item

  • logicalValue is a logical value associated with the item

  • icon is the URI of the image to be displayed with the item (if any)

  • Any subsequent values (col2, col3, and so forth) define the values to display in any additional columns when the dynaView is in “details” mode

• pHeaders is a multidimensional array that provides a set of column headers, subscripted by column number. When the dynaView is in “details” mode, this is used to define how many columns of data to display and what the column headers are. For example:

      // define 3 column headers
      Set pHeaders(1) = "Name"
      Set pHeaders(2) = "Size"
      Set pHeaders(3) = "Date"
  
  

  

The icons used in a dynaView belong to a CSS class called dynaViewIcon, which enables you to use CSS to control the appearance of the icon. For example, the following CSS insures that the icon is displayed as 16px x 16px:

    .dynaViewIcon {
        height: 16px;
        width: 16px;
    }

<dynaView> Attributes

The previous topic described the OnGetViewContents attribute in detail. The following table lists all the <dynaView> attributes.

When you work with %ZEN.Component.dynaViewOpens in a new tab programmatically, you must also know about the following properties of the dynaView class:

• Each <parameter> element provided in the original <dynaView> definition in XData Contents becomes a member of the dynaView parameters property, a list collection of %ZEN.Auxiliary.parameterOpens in a new tab objects. Each <parameter> acquires an ordinal position in the parameters collection: 1, 2, 3, etc.

• The read-only text property holds the text (display) value of the currently selected node within the tree. This is the node label that displays in the <dynaView>.

• The read-only value property holds the logical (actual) value of the currently selected node within the tree. This is the string that is activated when the user clicks the corresponding label in the <dynaView>.

<schedulePane> OnGetScheduleInfo Callback Method

<schedulePane> gets its data by invoking a server-side callback method defined in the Zen page class. The method name is specified using the <schedulePane> OnGetScheduleInfo attribute, as shown in the following example. In this example, the method name is GetScheduleInfo.

<schedulePane id="schedule" caption="Schedule for Bob"
  dateFormat="5" interval="30" startTime="540" endTime="1020"
  dropEnabled="true" ondrop="zenPage.scheduleDataDrop(dragData);"
  onselectitem="zenPage.selectItem(id,time);"
  OnGetScheduleInfo="GetScheduleInfo">
  <parameter id="parmPerson" paramName="Person" value="Bob" />
</schedulePane>

A <schedulePane> can contain zero or more <parameter> elements. Each <parameter> specifies an input parameter for the OnGetScheduleInfo callback method. Each <parameter> may have the following attributes:

The OnGetScheduleInfo callback method must have a signature that looks like this:

ClassMethod GetScheduleInfo
  (ByRef pParms As %String,
   pStartDate As %Date,
   pEndDate As %Date,
   ByRef pInfo As %List) As %Boolean

Where:

• The method returns a %BooleanOpens in a new tab value which is true to indicate success; otherwise it is false.

• pParms represents any <parameter> elements defined by the <schedulePane>. pParms is an array. Each member of this array uses its paramName as a subscript and its value as a value.

• pStartDate is the starting date and time in $HOROLOG ($H) format, the internal storage format for dates in Caché. As described in the Caché ObjectScript Reference, this format gives the number of days since December 31, 1840; then a comma; then the number of seconds since midnight. That is:

  date,time

  Where both date and time are integers.

• pEndDate is the ending date and time in $HOROLOG ($H) format.

• pInfo is a multidimensional array that describes the time slots that are displayed within the schedule calendar. The array is subscripted as follows:

  • day is the date in $HOROLOG ($H) format.

  • time is an integer expressing the start time for this time slot as a number of minutes since midnight. Your code is more readable if you express this value as a calculated multiple of 60, using 9*60 for 9 a.m. instead of the literal value 540, but either is correct.

  • n is an integer (starting with 1, and usually equal to 1) that you can use as needed to distinguish between time slots that have the same day and time values.

  Each pInfo array element is a $List structure containing the following information. You can use the ObjectScript function $LISTBUILD ($LB) to create each list item for pInfo, using statements such as the following inside the callback method:

    Set pInfo(day,time,n) =
    $LISTBUILD(duration,id,text,type,style)
  

  

  Where:

  • duration is an integer specifying the number of minutes to reserve for this time slot in the schedule.

  • id is an integer that the onselectitem event handler uses to uniquely identify this time slot when it is selected in the schedule.

  • text is the text description to display in this time slot in the schedule.

  • type is either 0 or 1:

    • 0 is an unavailable time slot

    • 1 is a scheduled time slot

  • style is a CSS style to apply to this time slot in the schedule. This value overrides any competing styles that might otherwise apply to this time slot.

The following example sets up a 60-minute staff meeting at 9 a.m. on the given start date, designates it as a scheduled time slot, and colors its background green on the schedule calendar display:

ClassMethod GetScheduleInfo(ByRef pParms As %String,
                            pStartDate As %Date,
                            pEndDate As %Date,
                            ByRef pInfo As %List)
                            As %Boolean
{
  Set pInfo(pStartDate,9*60,1)
  = $LB(60,1,"Staff Meeting",1,"background: green;")
  Quit 1
}

You can also provide a style that applies to all of the time slots in a particular day by setting a top node of the pInfo array to a CSS style value. For example:

  Set pInfo(day) = "background: yellow;"

<schedulePane> Attributes

This topic has already described the OnGetScheduleInfo attribute in detail. The following table lists all the <schedulePane> attributes.

Attribute	Description
Zen component attributes	<schedulePane> has the same general-purpose attributes as any Zen component. For descriptions, see these sections: “Behavior” in the “Zen Component Concepts” chapter of Using Zen “Component Style Attributes” in the “Zen Style” chapter of Using Zen
caption	Text to display as a caption along the top of the schedule. The text is not HTML escaped, so it can contain markup. The caption value can be a literal string, or it can contain a Zen #()# runtime expression. Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.captionOpens in a new tab. See “Zen Attribute Data Types.”
cellHeight	Integer giving the height of time slots in the schedule calendar, in pixels. The default is 30, as shown in the illustration for dateFormat. Do not specify units with cellHeight.
date	Date to display, in YYYY-MM-DD format. The default is the current date. The schedule calendar displays a range of days that contain this date value. The actual range depends on the current value of the view attribute: "day", "week", or "month". The date value can be a literal string, or it can contain a Zen #()# runtime expression.
dateFormat	Integer that specifies the date format to use in the headers for the schedule calendar. The <schedulePane> automatically displays this date below the name of the day of the week. The default dateFormat is –1. This generates the date in the format “Feb 18, 2009” as shown in the following illustration. As the illustration shows, you can also configure the headerHeight and cellHeight attributes for this part of the schedule calendar display. For a list of the integers you can use as values for dateFormat, see the description of dformat in the “Parameters” section for the $ZDATETIME ($ZDT) function in the Caché ObjectScript Reference. dateFormat allows nearly the same range of values as dformat. dateFormat supports –1 and the values 1 through 13.
dayList	Comma-separated list of the full names of days of the week. The default dayList value uses the $$$Text macro with the English values Sunday through Saturday. Using this macro ensures that this dayList value is automatically included in the list of strings to translate for your application when you export them from the message dictionary, as long as you also set the DOMAIN parameter in the Zen class. For details, see the “$$$Text Macros” section in the “Zen Localization” chapter of Developing Zen Applications. You can use $$$Text with dayList because its ZENLOCALIZE datatype parameter is set to 1 (true). Any localized dayList string must remain a comma-separated list of seven items when translated. Be sure to coordinate dayList changes with shortDayList and firstDayOfWeek.
endTime	Ending time for the daily time slots to be displayed on the schedule calendar. This is an integer expressing the number of minutes since midnight. The default endTime is 1080, which means 6 p.m. The range for endTime is 0 through 1440, which covers all 24 hours in the day. If the end user schedules an appointment that falls outside the startTime and endTime, the calendar expands to display that time slot. The endTime value can be a literal string, or it can contain a Zen #()# runtime expression.
firstDayOfWeek	Integer that specifies which day of the week is displayed as the starting day of the week in the schedule calendar. 0 means Sunday, 1 means Monday, and so on up to 6, which means Saturday. The default firstDayOfWeek is 0. The purpose of the firstDayOfWeek attribute is to allow you to customize the schedule calendar for different locales. Be sure to coordinate firstDayOfWeek changes with dayList and shortDayList.
headerHeight	Integer giving the height of the header row at the top of the schedule calendar, in pixels. This header row is where Zen displays the names of days and their dates. The default is 40, as shown in the illustration for dateFormat. Do not specify units with headerHeight.
interval	Integer giving the number of minutes in each time slot on the calendar. The default interval is 30; the minimum is 5. The interval value can be a literal string, or it can contain a Zen #()# runtime expression.
monthList	Comma-separated list of the full names of months of the year. The default monthList value uses the $$$Text macro with the English values January through December. You can use $$$Text with monthList because its ZENLOCALIZE datatype parameter is set to 1 (true). Any localized monthList string must remain a comma-separated list of twelve items when translated.
OnGetScheduleInfo	Name of a server-side callback method in the Zen page class. This method gets the information needed to display the schedule. For details, see the section “<schedulePane> OnGetScheduleInfo Callback Method.”
onselectitem	The onselectitem event handler for the <schedulePane>. Zen invokes this handler when the user clicks on an item within the schedule calendar. See “Zen Component Event Handlers.” An onselectitem definition generally looks like this:<schedulePane onselectitem="zenPage.selectItem(id,time);" ... > While the signature for the onselectitem handler method in the Zen page class looks like this:ClientMethod selectItem(id, time)[ Language = javascript ] The handler uses the following two special variables as arguments: id — the user defined identifier for a scheduled item as provided by the OnGetScheduleInfo callback (or null for an empty cell). time — the time value associated with the cell (in yyyy-mm-dd hh:mm:ss format).
shortDayList	Comma-separated list of the abbreviated names of days of the week. The default shortDayList value uses the $$$Text macro with the following string: Sun,Mon,Tue,Wed,Thu,Fri,Sat You can use $$$Text with shortDayList because its ZENLOCALIZE datatype parameter is set to 1 (true). Any localized shortDayList string must remain a comma-separated list of seven items when translated. Be sure to coordinate shortDayList changes with dayList and firstDayOfWeek.
shortMonthList	Comma-separated list of the abbreviated names of months of the year. The default shortMonthList value uses the $$$Text macro with the following string: Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec You can use $$$Text with shortMonthList because its ZENLOCALIZE datatype parameter is set to 1 (true). Any localized shortMonthList string must remain a comma-separated list of twelve items when translated.
startTime	Starting time for the daily time slots to be displayed on the schedule calendar. This is an integer expressing the number of minutes since midnight. The default startTime is 480, which means 8 a.m. The range for startTime is 0 through 1440, which covers all 24 hours in the day. If the end user schedules an appointment that falls outside the startTime and endTime, the calendar expands to display that time slot. The startTime value can be a literal string, or it can contain a Zen #()# runtime expression.
view	Specifies what type of schedule to display. Possible values are "day", "week", or "month". The default is "day". The view value can be a literal string, or it can contain a Zen #()# runtime expression.

When you work with %ZEN.ComponentEx.schedulePaneOpens in a new tab programmatically, you must also know about the following properties of the schedulePane class:

• Each <parameter> element provided in the original <schedulePane> definition in XData Contents becomes a member of the schedulePane parameters property, a list collection of %ZEN.Auxiliary.parameterOpens in a new tab objects. Each <parameter> acquires an ordinal position in the parameters collection: 1, 2, 3, etc.

• The read-only selectedTime property holds the start time of the currently selected time slot in the schedule calendar. The selectedTime is an integer that gives the number of seconds since 0, at midnight.

• The read-only selectedInterval property holds the length, in minutes, of the currently selected time slot in the schedule calendar. Add the selectedInterval to the selectedTime to calculate an end time.