Skip to main content

%ZEN.Component.object

class %ZEN.Component.object extends %Library.RegisteredObject, %XML.Adaptor

Base class for all ZEN components. An object, by itself, can be used to create objects that can be shared between a server and a browser client environment. All visual component, are derived from component, which is a subclass of object.

Property Inventory

Method Inventory

Parameters

parameter DEFAULTVISIBLE = 0;
Subclasses can set this to change default visibilty for a component.
parameter INCLUDEFILES;
CSV list of additional include files (either .js or .css) that should be included when this component is used on a page.
By default, the file extension (.js or .css) is used to determine whether an item in the list is a script include or a style include. You can override this behavior by adding the terms "script:" or "style:" to the beginning of the file name or names. This prefix is not used as part of the include filename.
parameter MODULE;
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.
parameter NAMESPACE = http://www.intersystems.com/zen;
This is the XML namespace used for library components.
parameter POSTCOMPILEACTIONS = schema,HTML;
This is a comma-delimited list of which post-compile actions this component is registered for. If this value is defined, then certain actions are carried out after this class is compiled.
The available choices are:
  • "schema" - update the schema used by Studio Assist when editing page definitions.
  • "HTML" - Regenerate any JS or CSS files associated with this class.
  • "SVG" - Regenerate any JS or SVG CSS files associated with this class.
parameter USECOMMONDIRECTORY = 0;
If true, then the include files generated for this component, are placed in the common /csp/broker directory and not the local /csp/*namespace* directory.
This is intended for use with packages that are mapped so as to be visible to every namespace.
All Zen classes within the same package must have the same value for this parameter. It is the developer's responsibility to ensure this.
parameter XMLFORMAT = Literal;
If XMLFORMAT="Literal", then only support for literal format import and export is generated.
parameter XMLIGNOREINVALIDATTRIBUTE = 0;
By setting this to 0, we disallow use of invalid attribute names in Zen XML documents.
parameter XMLIGNORENULL = 1;
Inherited description: XMLIGNORENULL allows the programmer to override the default XML handling of empty strings for properties of type %String. By default (XMLIGNORENULL = 0), empty strings in the XML input are stored as $c(0) and $c(0) is written to XML as an empty tag. A missing tag in the XML input is always stored as "" and "" is always output to XML as no tag.

If XMLIGNORENULL is set = 1, then both missing tags in the XML and empty strings are input as "", and both "" and $c(0) are output as empty tags (i.e. <tag></tag>).

If XMLIGNORENULL is set = "inputonly", then both missing tags in the XML and empty strings are input as "". Output of "" and $c(0) are for XMLIGNORENULL = 0: $c(0) is output as an empty tag (i.e. <tag></tag>) and "" is output as no tag.

If XMLIGNORENULL = "runtime" (runtime is not case sensitive), then the behavior of XMLIGNORENULL is determined by the format parameter of XMLExport, XMLImport and %XML.Reader.OpenFile. The default behavior for XMLIGNORENULL="runtime is the same as XMLIGNORENULL=0. Adding "ignorenull" to the format argument changes the behavior to that of XMLIGNORENULL=1. "ignorenull" shoud be separated by a comma from literal/encoded part of the format. Example values for format are "", ",ignorenull", "literal,ignorenull" and "encoded,ignorenull". Note that "inputonly" is equivalent to using ,ignorenull for XMLExport and not for %XML.Reader.

Properties

property %condition as %ZEN.Datatype.expression (XMLNAME = "condition");
Server-side expression that determines if this component should be added to the set of page components.
This property is not available on the client.
Property methods: %conditionDisplayToLogical(), %conditionGet(), %conditionIsValid(), %conditionLogicalToDisplay(), %conditionLogicalToOdbc(), %conditionNormalize(), %conditionSet()
property %import as %ZEN.Datatype.string (MAXLEN = 1000, XMLNAME = "import");
CSV list of additional component classes that this components needs to have defined on the client. Use this for cases where the client will need classes that are not directly used in the original object tree. This property is not available on the client.
Property methods: %importDisplayToLogical(), %importGet(), %importIsValid(), %importLogicalToDisplay(), %importLogicalToOdbc(), %importNormalize(), %importSet()
property %includeFiles as %ZEN.Datatype.string (MAXLEN = 1000, XMLPROJECTION = "none") [ InitialExpression = ..#INCLUDEFILES ];
CSV list of additional include files (either .js or .css) that should be included when this component is used on a page.
This property is not available on the client.
Property methods: %includeFilesDisplayToLogical(), %includeFilesGet(), %includeFilesIsValid(), %includeFilesLogicalToDisplay(), %includeFilesLogicalToOdbc(), %includeFilesNormalize(), %includeFilesSet()
property %page as %ZEN.Component.page (XMLPROJECTION = "none") [ Final ];
Link back to page that contains this component.
Applications should not set this property.
Property methods: %pageGet(), %pageGetSwizzled(), %pageIsValid(), %pageNewObject(), %pageSet()
property %resource as %ZEN.Datatype.resource (XMLNAME = "resource");
Resource name that determines if this component should be added to the set of page components. If specified, current user must hold USE privilege on this resource or the component will not be added to the set of page components.
This property is not available on the client.
Property methods: %resourceDisplayToLogical(), %resourceGet(), %resourceIsValid(), %resourceLogicalToDisplay(), %resourceLogicalToOdbc(), %resourceNormalize(), %resourceSet()
property aux as %ZEN.Datatype.string [ Final ];
This is an auxiliary property that is provided as a place to hold additional user-defined values for components. This property is not used by the ZEN framework.
Property methods: auxDisplayToLogical(), auxGet(), auxIsValid(), auxLogicalToDisplay(), auxLogicalToOdbc(), auxNormalize(), auxSet()
property composite as %ZEN.Component.group (XMLPROJECTION = "none", ZENSETTING = 0) [ Final ];
For components that are created as part of a composite component, this is a link to the composite that contains this object. Applications should not set this property.
Property methods: compositeGet(), compositeGetSwizzled(), compositeIsValid(), compositeNewObject(), compositeSet()
property id as %ZEN.Datatype.id [ Final ];
This is a unique identifier that is used to distinguish this object from other objects within the same Zen page.
Every object within a Zen page must have a unique id value. You can find an object with a given id value using the page object's getComponentById() method.
Property methods: idDisplayToLogical(), idGet(), idIsValid(), idLogicalToDisplay(), idLogicalToOdbc(), idNormalize(), idSet()
property index as %Integer (XMLPROJECTION = "none", ZENSETTING = 0) [ Final ];
System-assigned index number used internally to identify this component.
Applications can use but should not set this property.
Property methods: indexDisplayToLogical(), indexGet(), indexIsValid(), indexLogicalToDisplay(), indexNormalize(), indexSet(), indexXSDToLogical()
property name as %ZEN.Datatype.name [ Final ];
Name of this object.
This is primarily used to specify the name used for identifying a control within a form. It is also used to identify values that are submitted by controls on a form.
It is defined here for convenience.
Property methods: nameDisplayToLogical(), nameGet(), nameIsValid(), nameLogicalToDisplay(), nameLogicalToOdbc(), nameNormalize(), nameSet()
property onupdate as %ZEN.Datatype.eventHandler;
onupdate event handler: This event is fired after the properties of the object have been updated from the server.
Property methods: onupdateDisplayToLogical(), onupdateGet(), onupdateIsValid(), onupdateLogicalToDisplay(), onupdateLogicalToOdbc(), onupdateNormalize(), onupdateSet()
property parent as %ZEN.Component.object (XMLPROJECTION = "none", ZENSETTING = 0) [ Final ];
Link to the component that contains this object or somehow caused this component to be placed on the page.
For visual components, this is typically set to the group that contains the component.
For auxiliary components, this is set to the object that referred to this component in the page definition.
Applications should not set this property.
Property methods: parentGet(), parentGetSwizzled(), parentIsValid(), parentNewObject(), parentSet()
property tuple as %ZEN.Datatype.string (XMLPROJECTION = "none", ZENSETTING = 0) [ Final ];
Special property indicating which tuple of a repeating group is rendering this component. This property only has meaning when a component is part of a repeating group. Applications should not set this property.
Property methods: tupleDisplayToLogical(), tupleGet(), tupleIsValid(), tupleLogicalToDisplay(), tupleLogicalToOdbc(), tupleNormalize(), tupleSet()
property visible as %Boolean (XMLPROJECTION = "none", ZENSETTING = 0) [ InitialExpression = ..#DEFAULTVISIBLE ];
This property indicates whether a component is visible and thus layed out. This is a class-wide property set by the object constructor.
Applications should not set this property; Sub-classes can set this via the DEFAULTVISIBLE.
Property methods: visibleDisplayToLogical(), visibleGet(), visibleIsValid(), visibleLogicalToDisplay(), visibleLogicalToXSD(), visibleNormalize(), visibleSet(), visibleXSDToLogical()
property window as %ZEN.Datatype.string (XMLPROJECTION = "none", ZENCLIENTONLY = 1, ZENSETTING = 0) [ Final ];
This is a client-only property that refers to the JavaScript Window object on which this object was created.
Applications should not set this property.
Property methods: windowDisplayToLogical(), windowGet(), windowIsValid(), windowLogicalToDisplay(), windowLogicalToOdbc(), windowNormalize(), windowSet()

Methods

method %AddToSaveSet(depth As %Integer = 3, refresh As %Integer = 0, norecurseon As %String = "") as %Status
Inherited description:

This method adds the current object to the SaveSet containing objects that are part of the current %Save() for persistent classes or %GetSwizzleObject for serial classes. A queue of objects to be saved or serialized is also constructed. Only modified objects are included in the save queue. The value (OID or serial value in OID form) of each object is also placed in the SaveSet.

This method will invoke the %OnAddToSaveSet method if it is implemented. See that method for more information.

%AddToSaveSet should not ever be invoked directly except from %OnAddToSaveSet().

This method takes these parameters: depth, with these values:

1: Include this object in the SaveSet and, if it has not been serialized put it in the save queue and invoke %AddToSaveSet on any objects referenced by this object to the SaveSet with a depth of 1.
2: Include this object in the SaveSet and save queue. Also invoke %AddToSaveSet on any referenced objects in the SaveSet with a depth of 1.
3: Include this object in the SaveSet and, if modified, the save queue. Also invoke %AddToSaveSet on any referenced objects in the SaveSet with a depth of 3.
refresh, with these values:
0: Add this object to the save set only if it isn't already included.
1: Add this object to the SaveSet even if it already exists. This causes object dependencies to be rebuilt. Typically, this value is only passed by %OnAddToSaveSet when it modifies objects other than the current one.

Note: Swizzled serial objects always have an empty serial value and will always be placed in the save queue and the SaveSet. the value of depth simply gets passed on to its referenced objects.

final method %Attr(pName As %String, pValue As %String) as %String
Utility method used when writing out HTML attribute values. Given an attribute name and value, this returns the string attr=""value"" with value HTML escaped. If value is "", then "" is returned.
method %BindExport(dev As %String, ByRef Seen As %String, RegisterOref As %Boolean, AllowedDepth As %Integer, AllowedCapacity As %Integer) as %Status
Inherited description: This method is used by Language Binding Engine to send the whole object and all objects it referes to to the client.
method %ConstructClone(deep As %Boolean = 0, ByRef cloned As %String, location As %String) as %RegisteredObject
Inherited description: Clone the current object to a new object. If deep is 1 then this does a deep copy which will also copy any subobjects and if deep is 0 then it will create another reference to any subobjects and increment the reference count appropriately. It returns the new cloned object.

Note that even if deep=0 when you clone a parent object in a parent child relationship or a one object of a one to many relationship then it will construct clones of all the child/many objects. This is because a child/many object can only point at a single parent and so if we did not create a clone of these then you would have a relationship with zero items in it. If you really just want to clone the object without these child/many objects then pass deep=-1 to this method.

After the clone is constructed it will call %OnConstructClone(object,deep,.cloned) on the clone if it is defined so that you can perform any additional steps e.g. taking out a lock. This works just the same way as %OnNew() does.

The object is the oref of the original object that was cloned. The cloned array is just used internally when doing a deep clone to prevent recursive loops, do not pass anything in at all for this parameter on the initial call. If you write a %OnConstructClone and from here you wish to call %ConstructClone on another object pass in the cloned array, e.g. 'Do oref.%ConstructClone(1,.cloned)' so that it can prevent recursive loops.

The location is used internally to pass the new location for stream objects.

method %DrawHTML()
Static HTML display method: draw the BODY of this component as HTML.
Subclasses implement this in order to render the static HTML contents of a component.
classmethod %DrawJSStrings(ByRef pVisited As %String) as %Status
Render list of localized javascript strings for this object.
method %Eval(pExpr As %String, pEscape As %String = "") as %String
Utility method; takes a property value containing a #()# expression and evaluates it. This is called by the $$$ZENVAL macro.
classmethod %EvalC(pExpr As %String, pEscape As %String = "") as %String
final method %ForceClientRender()
Call this method to force the client to call this object's renderContents() if it has one.
method %GetEventHandlers(ByRef pIgnore) as %String
This helper method returns a string of HTML/XML attributes that will define all event handler properties defined for a control.
pIgnore is an array of names of events that should be ignored.
If the properties W3CEVENT parameter is set to 0, then it will be ignored.
final classmethod %GetXMLName(Output pNamespace As %String, Output pName As %String) as %Integer
Return the XML namespace and element name for this component. These are return via the parameters pNamespace and pName respectively.
method %MakeId(pSubID As %String) as %String
Server-side utility method that constructs a component-specific id value for use in assigning ids to HTML/XML elements. If we are part of a repeating group, the tuple number is included in the id as well.
method %NormalizeObject() as %Status
Inherited description: Normalizes all of an object's property values by invoking the data type Normalize methods. Many data types may allow many different representations of the same value. Normalization converts a value to its cannonical, or normalized, form.
abstract method %OnAddToPageAfter() as %Status
If implemented, this callback method is called at page render-time after this component has been added to a page and after any of its children have been created but before the %DrawHTML methods are called.
abstract method %OnAddToPageBefore() as %Status
If implemented, this callback method is called at page render-time when this component is added to a page but before any of its children have been created.
abstract method %OnDrawObjectProperties()
If defined, this callback is invoked by the %DrawObjectProperties() method.
abstract method %OnObjectSynch() as %Status
If defined, this callback is invoked by the %ObjectSynch() method.
abstract method %OnZENDeserialize() as %Status
If defined, this callback is invoked by the %ZENDeserialize() method.
classmethod %QuoteValue(pValue As %String)
Take a value string and return a quoted string.
classmethod %QuoteValueL10N(pValue As %String)
Take a value string and return a quoted string wrapped within a $$$Text macro.
If value starts and ends with #( )#, then return an expression
method %RemoveFromSaveSet() as %Status
Inherited description:

This method removes the current object from the SaveSet. If this object is also in the save queue it is removed from there as well.

method %Self() as %String
Return a JS expression that will evaluate to *this* component. This is used when rendering HTML for a component and that HTML needs to refer back to *this* component for a JS expression (such as an event handler):
onclick="#(..%Self())#.someMethod();"
method %ValidateObject(force As %Library.Integer = 0, checkserial As %Library.Boolean = 1) as %Status
Inherited description: This method validates an object. The %Save method of a persistent class calls it before filing any objects in the database. The %ValidateObject method of a referencing object can call it. You can also call it explicitly at any time.

%ValidateObject() does the following:

  1. It tests if any required property values are missing.
  2. If the PROPERTYVALIDATION class parameter is set to ValidateOnSave, it validates each non-null property value by calling the property method IsValid on each literal property and the object's %ValidateObject method for object-valued properties.
  3. If present, it will call a user-supplied %OnValidateObject() method.

If any of these tests fail, %ValidateObject() immediately returns an error value. It is up to the caller of %ValidateObject to process the error value.

Returns a %Status value indicating success or failure.

classmethod XMLDTD(top As %String, format As %String, input As %Boolean, ByRef dtdlist) as %Status
Inherited description: Write the DTD to the current device for this XML enabled class serialized as an XML document.

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type. DTDs may only be generated for the default "literal" format.

input=true means that the DTD for the input XML will be generated, otherwise the DTD for the output XML will be generated. The default is input=false. Normally, this argument is not relevant since the all properties of a class participate in input and output.

The dtdlist argument is used internally to track DTD generation for referenced objects.

method XMLExport(top As %Library.String, format As %Library.String, namespaces As %XML.Namespaces, attrs As %Library.String, createId As %Library.String, typeAttr As %Library.String, ByRef oreflist As %Library.String, ByRef idlist As %Library.String, initialIndent As %Library.String, local As %Library.Boolean, mimeAttachments As %Net.MIMEPart) as %Status
Inherited description: Serialize an XML enabled class as an XML document and write it to the current device.

IMPORTANT: The XMLExport method does not directly support many of the XML parameters. If you want control of the format of the export, do not use this method. Instead create an instance of %XML.Writer and use its OutputToDevice() method.

The supported arguments for XMLExport are:

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique Cache encoding in the future.

**********
**********
All the following arguments are for internal use only and may change
**********
**********
namespaces is the %XML.Namespaces class instance for this XML document. Instead of namespaces typesPrefix is still supported for compatability and is the optional namespace prefix to be used for all element tags and Cache types.

attrs is a multidimensional array of extra attributes for the top node:
attrs is number of attributes
attrs(i) is name of ith attribute
attrs(i,0) is value of the ith attribute

If the createId is not "", then an id field with this id value is created.

If the typeAttr is not "", then add a type attribute to the top element if the this class's name is not typeAttr.

The idlist and oreflist arguments are used internally to track deferred object export and should normally not be specified.

initialIndent is the initial indentation for use when the format is indent.

local specifies if the element is treated as a local element. A global element is specified by a false value of local which can be either 0 to represent a global element in the namespace specified by the namespace argument or a string which is the namespace to which the global element belongs. The default for local is 0.

If the class is to be exported as an XOP package for use by SOAP MTOM, mimeAttachments is the MIME part which contains the list of MIME parts for all the attachments in the XOP package.

method XMLExportToStream(ByRef export As %Stream.Object, top As %String, format As %String, namespaces As %XML.Namespaces, attrs, createId As %String, typeAttr As %String, ByRef oreflist, ByRef idlist, initialIndent As %String) as %Status
Inherited description: Serialize an XML enabled class as an XML document and appends it to a stream.

IMPORTANT: The XMLExportToStream method does not directly support many of the XML parameters. If you want control of the format of the export, do not use this method. Instead create an instance of %XML.Writer and use its OutputToStream() method.

The supported arguments for XMLExportToStream are:

export is the exported stream. If export is the oref of a stream, the XML document will be written to this existing stream at the current position. If export is "", then a new %FileCharacterStream will be created to contain the XML document and its oref returned. In this case, export must be passed by reference.

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique Cache encoding in the future.

**********
**********
All the following arguments are for internal use only and may change

**********
**********
namespaces is the %XML.Namespaces class instance for this XML document. Instead of namespaces typesPrefix is still supported for compatability and is the optional namespace prefix to be used for all element tags and Cache types.

attrs is a multidimensional array of extra attributes for the top node:
attrs is number of attributes
attrs(i) is name of ith attribute
attrs(i,0) is value of the ith attribute

If the createId is not "", then an id field with this id value is created.

If the typeAttr is not "", then add a type attribute to the top element if the this class's name is not typeAttr.

The idlist and oreflist arguments are used internally to track deferred object export and should normally not be specified.

initialIndent is the initial indentation for use when the format is indent.

method XMLExportToString(ByRef export As %String, top As %String, format As %String, namespaces As %XML.Namespaces, attrs, createId As %String, typeAttr As %String, ByRef oreflist, ByRef idlist, initialIndent As %String) as %Status
Inherited description: Serialize an XML enabled class as an XML document and write it to a string.

IMPORTANT: The XMLExportToString method does not directly support many of the XML parameters. If you want control of the format of the export, do not use this method. Instead create an instance of %XML.Writer and use its OutputToString() method.

The supported arguments for XMLExportToString are:

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique Cache encoding in the future.

**********
**********
All the following arguments are for internal use only and may change
**********
**********
namespaces is the %XML.Namespaces class instance for this XML document. Instead of namespaces typesPrefix is still supported for compatability and is the optional namespace prefix to be used for all element tags and Cache types.

attrs is a multidimensional array of extra attributes for the top node:
attrs is number of attributes
attrs(i) is name of ith attribute
attrs(i,0) is value of the ith attribute

If the createId is not "", then an id field with this id value is created.

If the typeAttr is not "", then add a type attribute to the top element if the this class's name is not typeAttr.

The idlist and oreflist arguments are used internally to track deferred object export and should normally not be specified.

initialIndent is the initial indentation for use when the format is indent.

local specifies if the element is treated as a local element. Default is 0 (false).

final clientmethod findElement(subid) [ Language = javascript ]
Client-side utility method that finds an HTML element with a component-specific id.
clientmethod fireOnUpdateEvent() [ Language = javascript ]
This is called when an object is updated from the server. It will invoke the class-defined and user-defined onupdate event if defined.
clientmethod getProperty(property, key) as %String [ Language = javascript ]
Return the value of a named property (i.e. a setting).
Returns null if this is not a property of this object.
key is an optional argument used for properties (such as collections) that may need a key to find a specific value.
final clientmethod getSettings(settings) [ Language = javascript ]
Client-side method that returns a list of this component's run-time settable properties. These are the properties that the page designer Inspector allows a user to edit.
This list is returned by inserting the property names in the associative array (object) settings. Note: this method is automatically generated by DrawClassDefinition.
final clientmethod getType() [ Language = javascript ]
Returns the component type of this object (e.g. "form", or "control").
clientmethod invokeSuper(method, args) [ Language = javascript ]
Invoke the superclass method method of the current object with arguments args.
final clientmethod isOfType(type) [ Language = javascript ]
Returns true if this object is of the given component type or is subclassed from the given component type. (e.g. "form", or "control")
clientmethod makeId(subid) [ Language = javascript ]
client-side utility method that constructs a component-specific id value for use in assigning ids to HTML elements.
This is simply a client-side version of %MakeId().
abstract clientmethod onCreate() [ Language = javascript ]
This client method, if present, is called when this component is instantiated. This allows for any additional client-side initialization for this object.
Note that this must be a client-side method.
abstract clientmethod onDelete() [ Language = javascript ]
This client method, if present, is called when this component is removed from the page. This allows for any additional client-side clean up for this object.
Note that this must be a client-side method.
abstract clientmethod onSerialize() [ Language = javascript ]
This client event, if present, is fired before a component is serialized. This gives the component a chance to make sure that its client-side variables are up-to-date.
abstract clientmethod onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
abstract clientmethod onunloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is unloaded. If this method returns a string value, then that is used as the return value of the HTML page's onbeforeunload handler (if more than one component returns a string, the first one encountered is used).
abstract clientmethod onupdateHandler() [ Language = javascript ]
This client method, if present, is fired when the object is updated from the server.
final clientmethod render() [ Language = javascript ]
abstract clientmethod renderContents() [ Language = javascript ]
This method, if present, is called when this component is placed on a client page.
This is used by components that render themselves using client-side, dynamic content (i.e., instead of using the %DrawHTML() method).
clientmethod renderSVG(document, parent) [ Language = javascript ]
This method is only needed for SVG components. It is defined here so that we can detect if HTML components are used within an SVG context and throw an error.
clientmethod setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property (i.e., a setting).
Subclasses override this for cases where setting a property requires some additional side effect to happen.
The optional value2 argument is used in cases, such as collections, where a key and a value are needed. In this case value is used as a key and value2 is the value.
Return true if the property was explicitly handled and false for the default behavior (setting the property directly).

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab