Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%ZEN.Component.abstractPage

class %ZEN.Component.abstractPage extends %ZEN.Component.group, %CSP.Page

Represents a page within a Zen application. This is the base class used for all pages. User pages will extend from the page class, which is a subclass of this.

Property Inventory

Method Inventory

Parameters

parameter APPLICATION;
This is the class name of this application this page belongs to. If not defined, this page does not belong to an application.
parameter AUTOLOGOUT = 1;
If true, then attempt to refresh this page when its session timeout period has expired. This will cause a login page to display if the current session has ended and security is set to require login.
parameter AUTONS = 0;
If true, auto-switch namespace to whatever $NAMESPACE is passed in.
parameter CLIENTCACHE = 0;
If false (the default) disable browser caching of pages.
parameter CSS3INCLUDES;
Comma-separated list of additional CSS3 include files for the page. If this is defined *and* this page is using CSS3, then the CSSINCLUDES parameter is ignored. If this is not defined *and* this page is using CSS3, then the CSSINCLUDES parameter is used.
parameter CSSINCLUDES;
Comma-separated list of additional CSS include files for the page. If this page is using CSS3 then the CSS3INCLUDES parameter is used (if defined).
parameter DEFAULTCELLVALIGN = top;
Inherited description: Subclasses can set this to change default cellVAlign for a group.
parameter DEFAULTGROUPCLASS = page;
Inherited description: Subclasses can set this to change default css class for a group.
parameter DEFAULTHEIGHT = 100%;
Inherited description: Subclasses can set this to change default height for a component.
parameter DEFAULTLAYOUT = vertical;
Inherited description: Subclasses can set this to change default layout for a group.
parameter DEFAULTWIDTH = 100%;
Inherited description: Subclasses can set this to change default width for a component.
parameter DOMAIN = %ZEN;
Localization domain
parameter ERRORDIVID = zenErrorDiv;
The id of the <div> element used to display errors encountered in the page definition. The default value is "zenErrorDiv".
parameter FAVORITEICON;
If defined, this is the url of the "favorite" (or shortcut) icon to display for this page.
Defining this causes Zen to include a <link rel="shortcut icon" href="FAVORITEICON"> in the head section of the page.
For maximum browser compatibility this should be an .ico file.
parameter HTMLATTRS;
If defined, this string will be written as attributes within the html element at the top of the page.
parameter HTMLDOCTYPE = <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">;
If HTMLDTD is true we will look here for the DOCTYPE declaration. Using this option can lead to less optimal behavior in zen library components For legacy purposes this defaults to the original doctype declaration for HTMLDTD
parameter HTMLDTD = 0;
If true, draw an HTML Document Type Declaration at the start of this page.
parameter INLINESVG = 0;
Experimental parameter.
If true, this page uses inline SVG as opposed to using the embed element. This is only supported for W3C compliant browsers.
parameter JSINCLUDES;
Comma-separated list of additional JS include files for the page.
parameter PAGENAME;
Optional. This is the display name used for this page. If not provided, the class name is used.
parameter PAGETITLE;
Optional. This is the default value for the page's title.
parameter RESOURCE;
This is a comma-delimited list of system Resources and associated permissions. A user must hold the specified permissions on at least one of the specified resources in order to view this page or invoke any of its server-side methods from the client.
The format of each item in the list should be as follows:
Resource[:Permission]
Permission is optional, and defaults to USE if not supplied. If it is supplied, it should be one of USE, READ or WRITE.
parameter SHOWSTATS = 1;
If true, then display server statistics (within a comment) at the end of this page.
parameter SYSMODULE = core;
Inherited description: If set, this indicates that this system component should be placed in the given "module". A module is a grouping of components within the same class package that share common include (js or css) files. Note that certain root classes are implicitly placed within the "core" module.
Classes outside of the Zen library should not set this, they should use the MODULE instead.
parameter SYSTEMMODULES = ZEN_Component__core,ZEN_Auxiliary;
Comma-separated list of Zen library modules whose HTML class and style definitions are in pre-generated include files.
parameter USERPACKAGES;
Comma-separated list of User class packages whose HTML class and style definitions are in pre-generated include files.
parameter USERSVGPACKAGES;
Comma-separated list of User class packages whose SVG class and style definitions are in pre-generated include files.
This is ignored unless useSVG is true.
parameter VALIDATEXML = 0;
If true, validate XML Contents using the Zen schema.
parameter XMLNAME = page;
Inherited description: This parameter provides the default XMLNAME for the class. If it is empty then the class name will be used to construct a default XML name. The default XMLNAME is used as the top level tag when exporting objects and the export context did not provide an XML container name.

Properties

property backgroundTimerInterval as %ZEN.Datatype.integer [ InitialExpression = 1000 ];
This is the interval, in milliseconds, at which timer events are fired in order to check on the status of background tasks started by this page.
Property methods: backgroundTimerIntervalDisplayToLogical(), backgroundTimerIntervalGet(), backgroundTimerIntervalIsValid(), backgroundTimerIntervalLogicalToDisplay(), backgroundTimerIntervalLogicalToOdbc(), backgroundTimerIntervalNormalize(), backgroundTimerIntervalSet()
property cssLevel as %ZEN.Datatype.integer (XMLPROJECTION = "none", ZENSETTING = 0) [ InitialExpression = 2 ];
This property specifies what level of CSS support is used by this page. Currently this can be 2 or 3. This is set by the %OnDetermineCSSLevel() method. If the page has a CSS level of 3 or higher, then the <!DOCTYPE html> directive will be served at the top of the web page.
By default, cssLevel is set to 3 for any browser whose user agent includes Mozilla/5.0 or above. You can turn this off by overriding the %OnDetermineCSSLevel() for a page or change it globally by setting the ^%ISC.ZEN.cssLevel global to 2.
Property methods: cssLevelDisplayToLogical(), cssLevelGet(), cssLevelIsValid(), cssLevelLogicalToDisplay(), cssLevelLogicalToOdbc(), cssLevelNormalize(), cssLevelSet()
property dragAndDrop as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, then drag and drop supported is enabled for this page.
This must be set before the page is initially displayed; it cannot be used to enable or disable drag and drop once the page has been loaded.
Property methods: dragAndDropDisplayToLogical(), dragAndDropGet(), dragAndDropIsValid(), dragAndDropLogicalToDisplay(), dragAndDropLogicalToOdbc(), dragAndDropLogicalToXSD(), dragAndDropNormalize(), dragAndDropSet(), dragAndDropXSDToLogical()
property title as %ZEN.Datatype.caption (ZENEXPRESSION = 1) [ InitialExpression = ..#PAGETITLE ];
Title of this page.
Property methods: titleDisplayToLogical(), titleGet(), titleIsValid(), titleLogicalToDisplay(), titleLogicalToOdbc(), titleNormalize(), titleSet()
property useSVG as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true, then the various JavaScript include files for SVG component are included for this page.
If the page contains one or more svgFrame components, then this flag is automatically set true. Pages only need to set this in the case where the initial page definition does not contain any svgFrame components and SVG components are later created dynamically.
This must be set before the page is initially displayed or it will have no effect.
Property methods: useSVGDisplayToLogical(), useSVGGet(), useSVGIsValid(), useSVGLogicalToDisplay(), useSVGLogicalToOdbc(), useSVGLogicalToXSD(), useSVGNormalize(), useSVGSet(), useSVGXSDToLogical()
property useSoftModals as %ZEN.Datatype.boolean (XMLPROJECTION = "none") [ InitialExpression = ..%OnUseSoftModals() ];
This property specifies whether modal dialogs launched using zenLaunchPopupWindow() should use a soft modal group in a div element instead of a new window. The default value for this property is 1 (as returned from %OnUseSoftModals()()). Users should either override the %OnUseSoftModals()() method in their pages as needed to control this behaviour, or set the ^%ISC.ZEN.useSoftModals global node to 1 to use modal divs for popups by default or 0 to launch popups in native browser windows.
Property methods: useSoftModalsDisplayToLogical(), useSoftModalsGet(), useSoftModalsIsValid(), useSoftModalsLogicalToDisplay(), useSoftModalsLogicalToOdbc(), useSoftModalsLogicalToXSD(), useSoftModalsNormalize(), useSoftModalsSet(), useSoftModalsXSDToLogical()
property zenPersistentPopup as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
This flag indicates whether the current Zen page should not sever its connection to its parent window when the page is opened as a popup and the popup window's onbeforeunload event is triggered. The default behaviour (when the flag is 0/false) is to notify the parent window (through window.opener) that the popup is being closed whenever the onbeforeunload event is triggered. If the flag is set to 1/true, then this notification will no longer occur, and the user code is then responsible for two things:
  1. When the popup is closed (or is otherwise determined to need closing), the zenPopupClosed() function attached to the parent window should be invoked if it exists. The function should exist as window.opener.zenPopupClosed() (if called from the popup) or window.zenPopupClosed() (if called from the parent window). This invocation provides the parent window with notification that the popup has in fact been closed.
  2. The user code needs to be adjusted to handle the various cases where the popup context, especially the Javascript environment, may be different to the situation where the page has been launched as a popup. In particular, actions such as POSTs or refreshes may either clear the current Javascript context or leave certain references pointing to outdated objects (this last could occur if users maintain independent maps to Zen components).
In general, the use of this flag should be used in limited circumstances where popups absolutely must perform multiple actions.
Property methods: zenPersistentPopupDisplayToLogical(), zenPersistentPopupGet(), zenPersistentPopupIsValid(), zenPersistentPopupLogicalToDisplay(), zenPersistentPopupLogicalToOdbc(), zenPersistentPopupLogicalToXSD(), zenPersistentPopupNormalize(), zenPersistentPopupSet(), zenPersistentPopupXSDToLogical()

Methods

method %AddComponent(pComponent As %ZEN.Component.object) as %Status
Called by a component to register that it is part of this page.
final method %ApplyURLParms() as %Status
Copy URL parameters supplied to this page into the appropriate properties of this page.
method %DrawAutoLogout()
Write JavaScript to automatically logout out this page when session ends
final method %DrawClassDefinitions()
Draw out client-side class definitions for components on this page. Caller is responsible for drawing enclosing script tags.
method %DrawHTMLPage(pMobileMode As %Boolean = 0)
Draw html contents of this page. If present, this will invoke the user callback methods: %OnDrawHTMLHead() and %OnDrawHTMLBody().
final method %DrawObjectDefinitions()
Write out client-side object definitions for components on this page.
Caller is responsible for drawing enclosing script tags.
final classmethod %EndBackgroundMethod()
This method is called by a method running in the background when it is finished in order to delete its status information (see %RunBackgroundMethod()).
classmethod %EndScript() as %String
Return string used to end client-side script code
final method %GetComponent(idx As %Integer) as %ZEN.Component.object
Server-only method for finding a component within this page given its index number.
final method %GetComponentById(id As %String) as %ZEN.Component.object
Server-only method for finding a component within this page given its id.
final method %GetComponentByName(pName As %String) as %ZEN.Component.object
Server-only method for finding a component within this page given its name.
If multiple components have the same name, returns the first one.
Return csv-list of links defined by the Contents of this page.
final classmethod %GetPageName() as %String
Server-side utility method: Return display name of this page.
final method %GetValueById(pID As %String) as %String
Server-side method: Find control on this page with id pID and return its value.
final method %GetValueByName(pID As %String) as %String
Server-side method: Find control on this page with name pName and get its value.
Zen-wrapper for %CSP.Page Link() method.
Tranforms the link specified by link into a URL and returns it as a string.

The URL may be encrypted.

The array, query, contains an optional set of name-value pairs which are added to the URL.

If the optional argument addQ is true, then a ? or &, as appropriate, is added to end of the URL

classmethod %LinkCSS(pFile As %String) as %String
Return string used to include a CSS file
classmethod %LinkScript(pFile As %String) as %String
Return string used to include a script file
method %OnAfterCreatePage() as %Status
This callback is called after the server-side page object and all of its children are created.
Subclasses can override this to add, remove, or modify items within the page object model, or to provide values for controls.
classmethod %OnBeforeCreatePage() as %Status
This class method callback is called just before the server-side page object is created.
abstract classmethod %OnCreateApplication(Output pStatus As %Status, pApplicationName As %String) as %ZEN.application
This callback, if implemented, is invoked when this page is about to create an instance of the %ZEN.application class.
If this method returns a %ZEN.application object, then this object will be used as the application object for the page. If this method returns "", then the application class specified by the APPLICATION parameter will be used.
pApplicationName contains the value of the APPLICATION parameter for the page.
This method should set pStatus to a $$$ERROR code if it fails.
method %OnCreatePage() as %Status
This callback is called just after the server-side page object is created but before its children are created.
method %OnDetermineCSSLevel() as %Integer
This callback method determines lets a page specify level of CSS support is used by this page. The default is to return "", which indicates that the built-in ZEN CSS level detection is used. A page can override this and return 2 or 3.
method %OnDrawHTMLBody() as %Status
This callback is called at the start of the HTML BODY section of the page.
(default implementation is a simple expression).
method %OnDrawHTMLHead() as %Status
This callback is called at the end of the HTML HEAD section of the page.
(default implementation is a simple expression).
method %OnDrawHTMLMeta() as %Status
This callback is called at the start of the HTML HEAD section of the page (just after the title).
It allows a page to write out meta tags, if desired. The default implementation writes out an IE-specific meta tag to ensure that IE 9 and 10 don't fall back into Compatibility Mode when we are returning an HTML5 page (i.e. cssLevel is set to 3).
classmethod %OnFinishBackgroundTask(pTaskID As %String)
This server-side callback method is called whenever the client calls to monitor the current background task and the task is complete. Typically a subclass uses this to send back JavaScript to update the page.
classmethod %OnMonitorBackgroundTask(pTaskID As %String, pStatus As %String, pPercentComplete As %Float)
This server-side callback method is called whenever the client calls to monitor the current background task. Typically a subclass uses this to send back JavaScript to update a progress bar.
classmethod %OnPreHTTP() as %Boolean
Zen page notification of an HTTP request. This method can be overwritten by subclasses.
This is called before the standard Zen pre-HTTP processing occurs.
classmethod %OnSubmit(pSubmit As %ZEN.Submit) as %Status
This callback is called when a form on this page is submitted. pSubmit is a %ZEN.Submit object containing details of the form submit.
Subclasses override this method.
classmethod %OnUseSoftModals() as %Boolean
Return whether the current page should use soft modal divs. The default behaviour is to return 1 for the current instance, but users may set the ^%ISC.ZEN.useSoftModals global change this system-wide. In some cases, it may be worth modifying the value of the flag based on the user agent, particularly if users are expected to access the application from mobile devices where new windows behave differently.
method %RemoveComponent(pComponent As %ZEN.Component.object) as %Status
Called by a component when it is removed from this page. Applications should not call this method directly. If you need to remove a component from a page, use the %RemoveChild() of %ZEN.Component.group instead.
final classmethod %RunBackgroundMethod(pMethod As %String, args...) as %Status
Start a background job to run a class method of this page.
pMethod is the name of the method to run.
args is a variable number of arguments that are passed on to the background method.
Only one background task is monitored at a time. If this method is called while a previous background task is running, the new method will become the current monitored task (the previous task will run to completion, but the client will not be notified).
final classmethod %SetBackgroundMethodStatus(pStatus As %String = "", pPercentComplete As %Float = 0)
This method is called by a method running in the background to update its status information (see %RunBackgroundMethod()). pStatus is the status message (which will be seen by the client page).
pPercentComplete is an optional value indicating the how much of the background task is complete (as a percentage between 0 and 100). A client page may use this information to display progress to the user.
method %SetErrorById(pID As %String, pError As %String)
Server-side method: Find component on this page with id pID and set its error value.
This is used to associate an error message with a component.
method %SetErrorByName(pName As %String, pError As %String)
Server-side method: Find component on this page with name pName and set its error value.
This is used to associate an error message with a component.
method %SetValueById(pID As %String, pValue As %String)
Server-side method: Find control on this page with id pID and set its value.
method %SetValueByName(pName As %String, pValue As %String)
Server-side method: Find control on this page with name pName and set its value.
method %SetValuesByName(ByRef pValues As %String)
Server-side method: Given an array of values, subscripted by control name, apply the values to the controls.
classmethod %StartScript() as %String
Return string used to introduce client-side script code
classmethod %ZENVersion() as %String
Return Zen Library version.
This is used to make sure that the class library is in sync with the zenutils.js file and any generated js files. This must match the value in the zenutils.js file.
classmethod OnPage() as %Status
Render the contents of this Zen page.
classmethod OnPostHTTP()
PostHTTP handler for all Zen pages. Users should not override this method. This dispatched to a common PostHTTP handler
classmethod OnPostHyperEvent(class As %Library.String, method As %Library.String) as %Status
Event handler which is invoked after a hyperevent method is called on this page.
classmethod OnPreHTTP() as %Boolean
PreHTTP handler for all Zen pages. Users should not override this method; If you need to be notified use the %OnPreHTTP() supplied by Zen.
This dispatched to a common PreHTTP handler
classmethod OnPreHyperEvent(class As %String, method As %String) as %Status
Event handler which is invoked before a hyperevent method is called on all Zen pages. This dispatched to a common PreHyperEvent handler.
If an application overrides this method, then it must invoke this base implementation code (using ##super).
final clientmethod cancelPopup() [ Language = javascript ]
This client method will cancel a popup page (i.e. close the window with no additional action).
It is only valid to call this method on a page that has been launched as a popup window.
clientmethod correctIELayering(div) [ Language = javascript ]
Correct for an embedded object layering bug that has persisted in IE since the invention of the embed tag. The symptom of this bug is the inability of a pop-up to obscure part or all of an SVG element. This routine should be called on the enclosing div of the popped-up component (or zenModalDiv if using a standard pop-up) IMMEDIATELY AFTER the div has been made visible
final clientmethod createComponent(name) [ Language = javascript ]
Client-side method to create a Zen component on the client. name is the name of the component class. (e.g. "text").
Note: this will only create components in the "zen" XML NAMESPACE; Use createComponentNS() to create components in other namespaces.
Use this and not the new operator to create ZEN components.
final clientmethod createComponentNS(ns, name, parent, div) [ Language = javascript ]
Client-side method to create a Zen component on the client.
ns is the XML namespace of the component (e.g., "http://www.intersystems.com/zendemo").
Note that components within the Zen library use an internal shorthand for namespaces.
name is the name of the component class. (e.g. "text").
Use this and not the new operator to create Zen components.
parent, if provided, is the Zen group to which the newly created component will be added.
div, if provided, is an HTML div element that will become the enclosing div for the newly created component. In this case, the component be rendered by this methd. This feature should only be used by components that can adequately create this div element.
final clientmethod deleteComponent(comp, refresh, sync) [ Language = javascript ]
Client-side method to remove a Zen component from a page on the client.
If refresh is defined and is false, then the page will not be refreshed after the delete. This is useful if you know that subsequent code will cause such a refresh. The default is to refresh.
If sync is defined and is true, the refresh of the group containing the deleted component will be executed synchronously. The default is asynchronous.
final clientmethod endModal() [ Language = javascript ]
End the current modal component; restore previous modal item or, if none, restore normal window behavior.
final clientmethod fireOnResizeEvent() [ Language = javascript ]
Client-side method: fire onresize event for page component.
final clientmethod fireOnUnloadEvent() [ Language = javascript ]
Client-side method: fire onunload event for every component that defines one.
If any component's onunload handler returns a string value, then that is used as the return value of the HTML page's onbeforeunload handler.
final clientmethod firePopupAction(action, value, close) [ Language = javascript ]
This client method will notify the parent window of this popup that a user action has ocurred. If action is not specified, then 'ok' is used as the action code. value is passed to the parent window as well.
If close is true (the default), then the popup window is closed after notifying the parent window.
It is only valid to call this method on a page that has been launched as a popup window.
final clientmethod getComponent(index) [ Language = javascript ]
Client-side method to find component by component index. index is typically the system-assigned index number of the the component.
For components within repeating groups, index may include a dot followed by a tuple number, (a 1-based number indicated the position of this component within the repeating group).
final clientmethod getComponentById(id, tuple) [ Language = javascript ]
Client-side method to find a component by user-assigned id value. For components within repeating groups, the optional tuple number indicates the position of this component within the repeating group).
clientmethod getOpener() [ Language = javascript ]
Helper method to get a reference to the window that launched this window. The helper is required to handle cases where this window has been opened as a soft modal.
final clientmethod gotoPage(url) [ Language = javascript ]
Set the location of the browser to a new url. Use this function to navigate to new pages within JavaScript to ensure that urls are encoded correctly. Please note this does not allow usage of Private pages. To make those links you must make a round trip to the Server and call ..Link()
clientmethod launchPopupWindow(url, pageName, features, parms, parent) [ Language = javascript ]
Open a popup window with given url url and page name pageName.
features is optional list of window features. If features does not include top,left,width, or height, defaults will be provided.
parms, if provided, is a JavaScript object whose properties are used to supply URL parameters for the popup window.
parent, if provided, is the Zen component that will be notified when the popup action fires (by calling its onPopupAction() method).
abstract clientmethod onServerMethodCall(method) [ Language = javascript ]
If implemented, this method is called just before a server method is invoked.
method is the name of the method invoked.
abstract clientmethod onServerMethodError(err, errObject) [ Language = javascript ]
If implemented, this method is called whenever a server method call returns an error from the server.
err is the error message. errObject is an object of type cspHyperEventError which has the following properties:
  • code - HTTP response code for the error, most likely 500 to indicate a server error, except when the user is no longer logged in, in which case it should be 401.
  • text - HTTP error message corresponding to the HTTP code
  • serverCode - the server side error status code, which may be null
  • serverText - the server side error text
  • exception - the Javascript exception which triggered the problem
  • arguments - the arguments to the function where the exception was caught
abstract clientmethod onServerMethodReturn(method) [ Language = javascript ]
If implemented, this method is called just after a server method is processed.
method is the name of the method invoked.
abstract clientmethod onkeydownHandler(evt) [ Language = javascript ]
This client event, if present, is fired when a keydown event occurs on the page.
abstract clientmethod onkeyupHandler(evt) [ Language = javascript ]
This client event, if present, is fired when a keyup event occurs on the page.
abstract clientmethod onlayoutHandler(load) [ Language = javascript ]
This client event, if present, is fired when the page is first loaded or whenever it is resized.
If this is called at load time, then load will be true.
clientmethod onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
abstract clientmethod onlogoutHandler() [ Language = javascript ]
This client method, if defined and the AUTOLOGOUT parameter for this page is true, is invoked when the logout timer for this page fires.
If this method return true then the normal page logout behavior will fire. That is, the page will be reloaded causing a login page to appear if the current session has ended.
clientmethod onoverlayHandler(index) [ Language = javascript ]
This client event, if present, is fired when a component with an overlay is clicked on.
index is index of the component.
This is used by page editing tools.
abstract clientmethod onresizeHandler() [ Language = javascript ]
This client event, if present, is fired when the page is resized.
final clientmethod popupActionHandler(parent, name, action, value) [ Language = javascript ]
Internal method.
This does the actual work of dispatching an action sent by a popup window. parent is the component index of the component that should be notified (or '').
final clientmethod setComponentId(obj, id) [ Language = javascript ]
Change id of given component.
final clientmethod setTraceOption(name, flag) [ Language = javascript ]
This client method lets you turn the various client-side tracing flags on or off.
name is the name of the tracing option:
'events' -- trace client events.
'js' -- display JavaScript returned from server.
'serialize' -- display object serializations.
flag is a boolean value that specifies whether the option should be on or off.
final clientmethod startModal(component) [ Language = javascript ]
Make the given component modal; That is all events outside of this component are captured. Also invokes the onStartModal callback for the component. By default, this makes the component visible, but it could be overrided by a component.

Inherited Members

Inherited Properties

Inherited Methods

Subclasses

FeedbackOpens in a new tab