class %ZEN.Component.abstractPage
extends 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.
• 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";
Subclasses can set this to change default cellVAlign for a group.
• parameter DEFAULTGROUPCLASS = "page";
Subclasses can set this to change default css class for a group.
• parameter DEFAULTHEIGHT = "100%";
Subclasses can set this to change default height for a component.
• parameter DEFAULTLAYOUT = "vertical";
Subclasses can set this to change default layout for a group.
• parameter DEFAULTWIDTH = "100%";
Subclasses can set this to change default width for a component.
• parameter DOMAIN = "%ZEN";
Localization domain
• 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";
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";
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.
• 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 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 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 title
as %ZEN.Datatype.caption(ZENEXPRESSION=1) [ InitialExpression = ..#PAGETITLE ];
Title of this page.
• 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 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 0 (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.
• 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:
- 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.
- 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.
• 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()
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.
• final classmethod %GetLinks()
as %Status
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.
• final method %Link(link As %String, ByRef query As %String, addQ As %Boolean = 0)
as %String
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.
(default implementation is a simple expression).
• 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 0, but users may set the
^%ISC.ZEN.useSoftModals global to 1 to 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()
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 method 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.
• method 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 method 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 method 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 method 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 method endModal()
[ Language = javascript ]
End the current modal component; restore previous modal item
or, if none, restore normal window behavior.
• final method fireOnLoadEvent()
[ Language = javascript ]
Client-side method: fire onload event for every component that defines one.
This are fired in reverse order, so that the page's handler is called last.
• final method fireOnResizeEvent()
[ Language = javascript ]
Client-side method: fire onresize event for page component.
• final method 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 method 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 method 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 method 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).
• method 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 method 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()
• method 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 method 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 method 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 method 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 method onkeydownHandler(evt)
[ Language = javascript ]
This client event, if present, is fired when a keydown event occurs on the page.
• abstract method onkeyupHandler(evt)
[ Language = javascript ]
This client event, if present, is fired when a keyup event occurs on the page.
• abstract method 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.
• method onloadHandler()
[ Language = javascript ]
This client event, if present, is fired when the page is loaded.
• abstract method 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.
• method 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 method onresizeHandler()
[ Language = javascript ]
This client event, if present, is fired when the page is resized.
• final method 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 method setComponentId(obj, id)
[ Language = javascript ]
Change id of given component.
• final method 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 method 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.
