This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?


abstract class %ZEN.Auxiliary.abstractController extends %ZEN.Component.component

This is the base class for the various data controller components used to implement the Controller portion of the Zen Model-View-Controller mechanism.

Property Inventory (Including Private)

Method Inventory (Including Private)


parameter DEFAULTVISIBLE = 0;
This component is not visible.
parameter SYSMODULE = mvc;
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.


property alertOnError as %ZEN.Datatype.boolean [ Final , InitialExpression = 1 ];
If true (the default), then the dataController will display an alert box when it encounters errors invoking server-side functions (such as when saving or deleting).
Property methods: alertOnErrorDisplayToLogical(), alertOnErrorGet(), alertOnErrorIsValid(), alertOnErrorLogicalToDisplay(), alertOnErrorLogicalToOdbc(), alertOnErrorLogicalToXSD(), alertOnErrorNormalize(), alertOnErrorSet(), alertOnErrorXSDToLogical()
property autoRefresh as %ZEN.Datatype.integer (MINVAL = 0) [ Final ];
Setting this to a non-zero value will turn on autoRefresh mode for this dataController. The dataController will reload its data from the server at the periodic interval specified by this property (in milliseconds).
This is provided as a convenience for dataController used to drive dashboards or charts; it is of limited use for forms.
Setting this to 0 will disable autoRefresh mode.
Property methods: autoRefreshDisplayToLogical(), autoRefreshGet(), autoRefreshHandler(), autoRefreshIsValid(), autoRefreshLogicalToDisplay(), autoRefreshLogicalToOdbc(), autoRefreshNormalize(), autoRefreshSet()
property defaultSeries as %ZEN.Datatype.integer (MINVAL = 1) [ Final , InitialExpression = 1 ];
Optional. If a DataModel has multiple dataSeries, then this specifies which DataSeries (1-based) should be used to provide values to DataViews that can only display values from one data series (such as a form).
Property methods: defaultSeriesDisplayToLogical(), defaultSeriesGet(), defaultSeriesIsValid(), defaultSeriesLogicalToDisplay(), defaultSeriesLogicalToOdbc(), defaultSeriesNormalize(), defaultSeriesSet()
property modelError as %ZEN.Datatype.string (XMLPROJECTION = "none", ZENSETTING = 0) [ Final ];
Most recent error message reported by the DataModel object this dataController is connected to. This is set to a non-empty string after a save, load, or delete operation encounters an error.
Property methods: modelErrorDisplayToLogical(), modelErrorGet(), modelErrorIsValid(), modelErrorLogicalToDisplay(), modelErrorLogicalToOdbc(), modelErrorNormalize(), modelErrorSet()
property modelId as %ZEN.Datatype.string (ZENEXPRESSION = 1) [ Final ];
ID value passed to the DataModel class.
You can change this value using the client-side setModelId() method. This will cause a new object to be loaded into the controller.
Property methods: modelIdDisplayToLogical(), modelIdGet(), modelIdIsValid(), modelIdLogicalToDisplay(), modelIdLogicalToOdbc(), modelIdNormalize(), modelIdSet()
property oncreate as %ZEN.Datatype.eventHandler [ Final ];
oncreate event handler: This event is fired when the createNewObject() method is called.
Property methods: oncreateDisplayToLogical(), oncreateGet(), oncreateIsValid(), oncreateLogicalToDisplay(), oncreateLogicalToOdbc(), oncreateNormalize(), oncreateSet()
property ondelete as %ZEN.Datatype.eventHandler [ Final ];
ondelete event handler: This event is fired when the deleteId() method is called. The parameter, id is passed to the event handler and contains id of the deleted object.
Property methods: ondeleteDisplayToLogical(), ondeleteGet(), ondeleteIsValid(), ondeleteLogicalToDisplay(), ondeleteLogicalToOdbc(), ondeleteNormalize(), ondeleteSet()
property onerror as %ZEN.Datatype.eventHandler [ Final ];
onerror event handler: This event is fired when the dataController attempts to open an instance of a DataModel and encounters an error.
The error message can be found in modelError.
Property methods: onerrorDisplayToLogical(), onerrorGet(), onerrorIsValid(), onerrorLogicalToDisplay(), onerrorLogicalToOdbc(), onerrorNormalize(), onerrorSet()
property onnotifyController as %ZEN.Datatype.eventHandler [ Final ];
onnotifyController event handler: This event is fired when a dataView connected to this dataController raises an event.
Property methods: onnotifyControllerDisplayToLogical(), onnotifyControllerGet(), onnotifyControllerIsValid(), onnotifyControllerLogicalToDisplay(), onnotifyControllerLogicalToOdbc(), onnotifyControllerNormalize(), onnotifyControllerSet()
property onsave as %ZEN.Datatype.eventHandler [ Final ];
onsave event handler: This event is fired when the save() method is called. The parameter, id is passed to the event handler and contains the current model id.
Property methods: onsaveDisplayToLogical(), onsaveGet(), onsaveIsValid(), onsaveLogicalToDisplay(), onsaveLogicalToOdbc(), onsaveNormalize(), onsaveSet()
property readOnly as %ZEN.Datatype.boolean [ Final , InitialExpression = 0 ];
If true, this data controller is read only regardless of whether its corresponding data model is read only or not.
Property methods: readOnlyDisplayToLogical(), readOnlyGet(), readOnlyIsValid(), readOnlyLogicalToDisplay(), readOnlyLogicalToOdbc(), readOnlyLogicalToXSD(), readOnlyNormalize(), readOnlySet(), readOnlyXSDToLogical()


classmethod %DeleteModelInstance(pClass As %String, pID As %String) as %Status
Delete an instance of a DataModel object.
method %GetDataByName(pProperty As %String)
Get a data value, by property name, from this dataController.
method %GetModelPropertyList(Output pSC As %Status) as %String
Return a comma-delimited list of the properties contained in the current DataModel class.
A property in the list may include type and label information in the form:
method %GetTypeByName(pProperty As %String)
Get a data type, by property name, from this dataController.
private method %OnNew(initvalue As %CacheString) as %Status
Inherited description: Constructor for Zen objects.
If subclasses override %OnNew, they should make sure to invoke this using #super.
method %SetDataByName(pProperty As %String, pValue As %String)
Set a data value, by property name, into this dataController.
clientmethod createNewObject() [ Language = javascript ]
Ask our associated dataModel to create a new (unsaved) instance.
clientmethod deleteId(id) [ Language = javascript ]
Ask our associated dataModel to delete the item with the given id. Returns true if the delete was successful. If the dataModel is readOnly, then the delete will not happen.
clientmethod getData(d1, d2, d3) [ Language = javascript ]
dataSet API Return the data contained in the specified location. Location is 0-based;
clientmethod getDataAsArrays() [ Language = javascript ]
This is a specialized variant of getData() that return the data in this controller as an array of arrays (used by charts).
clientmethod getDataAsObject(series) [ Language = javascript ]
This is a specialized variant of getData() that returns the data in this controller as a zenProxy object (associative array).
The return value of this object is a zenProxy object with properties that correspond to the properties of the current Data Model object. The value of each property in the returned object corresponds to the value in the Data Model object.
If the Data Model supports more than one data series, then the series parameter (0-based) specifies which series to use (the default is series 0).
Refer to the %ZEN.proxyObject for more details.
clientmethod getDataByName(property, series) [ Language = javascript ]
dataBag API Get a data value, by property name, from this dataController.
clientmethod getDimSize(dim) [ Language = javascript ]
dataSet API Return the number of items in the specified dimension (dim is 1,2, or 3).
clientmethod getDimensions() [ Language = javascript ]
dataSet API Return number of dimensions within the dataModel. There are 2 dimensions: The first is the set of properties, the second has a typical size of 1.
The second dimension may be larger than 1 in cases where the model serves multiple series for a given model instance. (Such as when providing mulitple data series for charts).
clientmethod getError() [ Language = javascript ]
Return the latest error message encountered by this data controller. Call this after a save, load, or delete operation to test if an error occurred.
This will return '' if there is no current error.
clientmethod getLabel(n, dim) [ Language = javascript ]
dataSet API Get the label at position n (0-based) in the given dimension (1,2, or 3).
clientmethod getModelId() [ Language = javascript ]
Return the current model id associated with this dataController.
clientmethod getPropertyName(n) [ Language = javascript ]
Given a 0-based index, return the corresponding property name.
clientmethod getTypeByName(property) [ Language = javascript ]
Get the type code for a property given its name.
clientmethod hasData() [ Language = javascript ]
Return true if this controller currently contains data loaded from a DataModel.
clientmethod invokeAction(action, data) [ Language = javascript ]
Invoke a named action on our associated dataModel. An action is an arbitrary operation that is defined by a specific dataModel class. data is an arbitary value passed along with the action.
clientmethod isModelReadOnly() [ Language = javascript ]
Test if the current data model is read-only.
clientmethod isPropertyValid(property, value) [ Language = javascript ]
Test if a given value for a property is valid.
clientmethod onDelete() [ Language = javascript ]
This client method, if present, is called when this component is removed from the page.
clientmethod onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
clientmethod raiseDataChange() [ Language = javascript ]
Send notification to listeners that the data associated with this dataController has changed.
Any dataController methods that change data should call this to notify listeners.
clientmethod save() [ Language = javascript ]
Save data from this dataController back to the DataModel on the server. Return the id with which the model was saved or '' if it was not saved.
clientmethod sendEventToViews(reason, source, data1, data2, data3) [ Language = javascript ]
Send an event to all listeners (dataViews) connected to this dataController. reason is the name of the event.
source, if not null, if the dataView that raised the event.
data1,data2, and data3 contain event-specific data passed along with the event.
clientmethod setData(value, d1, d2, d3) [ Language = javascript ]
dataSet API Set the data contained in the specified location. Location is 0-based;
clientmethod setDataByName(property, value, series) [ Language = javascript ]
dataBag API Set a data value, by property name, into this dataController.
If property is "%id", then change the id of this controller.
If property is "%series", then change the defaultSeries of this controller.
clientmethod setModelId(id) [ Language = javascript ]
Set the value of the modelId property for this controller. This will cause new data to be loaded and any views connected to this controller to refresh.
This is equivalent to calling setProperty('modelId',id) and is defined for convenience.
clientmethod setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
clientmethod update() [ Language = javascript ]
Reload the data in the dataController from the server.

Inherited Members

Inherited Properties (Including Private)

Inherited Methods (Including Private)