Skip to main content

%ZEN.Auxiliary.jsonProvider

class %ZEN.Auxiliary.jsonProvider extends %ZEN.Auxiliary.abstractController

The jsonProvider component provides a way to transport object data between a server and client (and vice versa) using JavaScript Object Notation (commonly abbreviated as JSON), as defined in RFC4627.
JSON format refers to a common JavaScript programming technique where you define a set of one or more objects using object literal syntax:
var obj = { "name": "Bill" };
The jsonProvider works as follows: Using the jsonProvider component as an object transport has advantages and disadvantages when compared with other mechanisms provided by Zen, such as the built-in transport provided for Zen components. The main advantage is that you can transport data without having to create or modify server classes — you can ship most any server-side object using this technique. The disadvantages are: The jsonProvider code may also be invoked from a non-Zen context by calling one of the following APIs:

Property Inventory

Method Inventory

Parameters

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

Properties

property %Format as %ZEN.Datatype.string [ InitialExpression = "aceloqtw" ];
Flags string consisting of character options that control output formatting.
JSON written out using the OnRenderJSON callback is not affected by this value. See the description of method %ObjectToJSON() for a list of options this value may include.
Property methods: %FormatDisplayToLogical(), %FormatGet(), %FormatIsValid(), %FormatLogicalToDisplay(), %FormatLogicalToOdbc(), %FormatNormalize(), %FormatSet()
property OnGetArray as %ZEN.Datatype.delegator (FORMALSPEC = "&pParameters:%String,*pMetaData,*pData", RETURNTYPE = "%Status");
Supply data for the JSON provider as a server-side array.
This callback method is invoked when the page containing this jsonProvider is rendered.
This callback provides an easy way to ship a set of identical objects to the client by filling in a multidimensional array. The callback method is expected to fill in two structures:
pMetaData is a $List containing the names of the properties of the objects in the order in which they will appear.
pData is an array containing the data. Each node in the array should be a $List containing values for properties. This should match the meta data provided in pMetaData. The array of data can use any subscript value its wants. It is possible to define a hierarchical array. In this case, children nodes are placed within a parent collection called children.
If this callback is defined, then the OnGetTargetObject callback will not be invoked. For example:
Method GetArray(
	ByRef pParameters As %String,
	Output pMetaData,
	Output pData) As %Status
{
  Set pMetaData = $LB("name","rank","serialNo")
  Set pData(1) = $LB("Smith","Captain","444-33-2222")
  Set pData(1,1) = $LB("Jones","Corporal","333-22-3333")
  Quit $$$OK
}
This would result in the two objects being shipped to the client (in JSON format):
var content = {
	"name": "Smith",
	"rank": "Captain",
	"serialNo": "444-33-2222",
	"children": [
		{
			"name": "Jones",
			"rank": "Corporal",
			"serialNo": "333-22-3333"
		}
	]
};
Property methods: OnGetArrayDisplayToLogical(), OnGetArrayGet(), OnGetArrayIsValid(), OnGetArrayLogicalToDisplay(), OnGetArrayLogicalToOdbc(), OnGetArrayNormalize(), OnGetArraySet()
property OnGetTargetObject as %ZEN.Datatype.delegator (FORMALSPEC = "&pParameters:%String,*pObject:%RegisteredObject", RETURNTYPE = "%Status");
Supply data for the JSON provider as a set of server objects.
This callback method is invoked when the page containing this jsonProvider is rendered. It is expected to return (by reference) an instance of the object whose data is to be provided to the client in JSON format.
For example:
Method GetTarget(
	ByRef pParameters As %String,
	Output pObject As %RegisteredObject) As %Status
{
  Set pObject = ##class(MyApp.MyClass).%New()
  Set pObject.Name = "Bob"
  Quit $$$OK 
}
Property methods: OnGetTargetObjectDisplayToLogical(), OnGetTargetObjectGet(), OnGetTargetObjectIsValid(), OnGetTargetObjectLogicalToDisplay(), OnGetTargetObjectLogicalToOdbc(), OnGetTargetObjectNormalize(), OnGetTargetObjectSet()
property OnRenderJSON as %ZEN.Datatype.delegator (FORMALSPEC = "&pParameters:%String", RETURNTYPE = "%Status");
Optional. If implemented this callback is expected to write out to the current device the contents of a set of related objects in JSON format.
If present, this overrides the default behavior of this component and the OnGetTargetObject callback is ignored.
Property methods: OnRenderJSONDisplayToLogical(), OnRenderJSONGet(), OnRenderJSONIsValid(), OnRenderJSONLogicalToDisplay(), OnRenderJSONLogicalToOdbc(), OnRenderJSONNormalize(), OnRenderJSONSet()
property OnSubmitContent as %ZEN.Datatype.delegator (FORMALSPEC = "pCommand:%String,pProvider:%ZEN.Auxiliary.jsonProvider,pSubmitObject:%RegisteredObject,&pResponseObject:%RegisteredObject", RETURNTYPE = "%Status");
This callback method is invoked when the client submits an object to the server by calling the submitContent()() method. The callback is passed the submitted object in pSubmitObject after it has been converted from JSON format back into an object instance. It is also passed the command string supplied to the submitContent()() method in pCommand.
If the callback method returns an object via the pResponseObject argument, then this object is returned to the client and becomes the new content of the JSON provider.
For example:
Method SubmitHandler(
	pCommand As %String,
	pProvider As %ZEN.Auxiliary.jsonProvider,
	pSubmitObject As %RegisteredObject,
	Output pResponseObject As %RegisteredObject) As %Status
{
  Set tSC = $$$OK
  If ($IsObject(pObject)) {
    Set tSC = pObject.%Save()
  }
  Quit tSC
}
Property methods: OnSubmitContentDisplayToLogical(), OnSubmitContentGet(), OnSubmitContentIsValid(), OnSubmitContentLogicalToDisplay(), OnSubmitContentLogicalToOdbc(), OnSubmitContentNormalize(), OnSubmitContentSet()
property documentId as %ZEN.Datatype.string;
Optional. If provided (and no other callbacks are defined), then this is the id of a document interface (subclass of %ZEN.DataModel.AbstractDocument) that is used to supply data to the provider.
A document id takes the form "docName/docInstance", where *docName* is the logical name of a data document and *docInstance* is a instance id.
Property methods: documentIdDisplayToLogical(), documentIdGet(), documentIdIsValid(), documentIdLogicalToDisplay(), documentIdLogicalToOdbc(), documentIdNormalize(), documentIdSet()
property error as %ZEN.Datatype.string (XMLPROJECTION = "none", ZENSETTING = 0);
Run-time value. Set to indicate an error within this component.
This is primarily used by controls. It is defined here for flexibility.
Property methods: errorDisplayToLogical(), errorGet(), errorIsValid(), errorLogicalToDisplay(), errorLogicalToOdbc(), errorNormalize(), errorSet()
property parameters as array of %ZEN.Auxiliary.parameter (XMLKEYNAME = "paramName", XMLNAME = "parameter", XMLPROJECTION = "ELEMENT");
User-defined set of parameters. These values are passed on to the user callback function that provides the contents of this view. Typically this is used to hold search parameters.
Property methods: parametersBuildValueArray(), parametersCollectionToDisplay(), parametersCollectionToOdbc(), parametersDisplayToCollection(), parametersGet(), parametersGetObject(), parametersGetObjectId(), parametersGetSwizzled(), parametersIsValid(), parametersOdbcToCollection(), parametersSet(), parametersSetObject(), parametersSetObjectId()
property propertyList as %ZEN.Datatype.csv;
Optional. If supplied this is an comma-delimited list of property names. These names are used to define the default ordering of properties supplied by this provider. If a property name is in the list but not in the content data, it is used but will have a value of ''. Properties in the content object but not in this list are listed at the end.
Property methods: propertyListDisplayToLogical(), propertyListGet(), propertyListIsValid(), propertyListLogicalToDisplay(), propertyListLogicalToOdbc(), propertyListNormalize(), propertyListSet()
property seriesNameProperty as %ZEN.Datatype.string [ InitialExpression = "caption" ];
Optional. When this provider is used as a data controller, this is the name of the property in the JSON data that provides the series names to view connected to the provider. The default is "caption".
Property methods: seriesNamePropertyDisplayToLogical(), seriesNamePropertyGet(), seriesNamePropertyIsValid(), seriesNamePropertyLogicalToDisplay(), seriesNamePropertyLogicalToOdbc(), seriesNamePropertyNormalize(), seriesNamePropertySet()
property targetClass as %ZEN.Datatype.className;
Class name of the target object expected to be served by this component. Setting the target object will also set this as a side effect.
Property methods: targetClassDisplayToLogical(), targetClassGet(), targetClassIsValid(), targetClassLogicalToDisplay(), targetClassLogicalToOdbc(), targetClassNormalize(), targetClassSet()

Methods

classmethod %ArrayToJSON(ByRef pMetaData, ByRef pData, pFormat As %String = "tw") as %Status
Write out the contents of the local array pData to the current device using JSON notation pMetaData is a $List containing the names of the properties of the objects in the order in which they will appear.
pData is an array containing the data. Each node in the array should be a $List containing values for properties. This should match the meta data provided in pMetaData. The array of data can use any subscript value its wants. It is possible to define a hierarchical array. In this case, children nodes are placed within a parent collection called children.
pFormat is a flags string that controls output formatting options.
The following character option codes are supported:
1-9 : indent with this number of spaces (4 is the default with the 'i' format specifier)
b - line break before opening { of objects
i - indent with 4 spaces unless 't' or 1-9
n - newline (lf)
s - use strict JSON output - NOTE: special care should be taken when sending data to a browser, as using this flag may expose you to cross site scripting (XSS) vulnerabilities if the data is sent inside <script> tags. Zen uses this technique extensively, so this flag should NOT be specified for jsonProviders in Zen pages.
t - indent with tab character
u - output pre-converted to UTF-8 instead of in native internal format
w - Windows-style cr/lf newline
classmethod %ConvertJSONToObject(pContent As %String, pTargetClass As %String = "", Output pObject As %RegisteredObject, pIgnoreUnknownProps As %Boolean = 0) as %Status
Utility method to allow direct use of JSON from a non-ZEN context (such as a CSP page).
pContent is a string or a stream containing JSON notation.
pTargetClass is an optional class type for the resulting object; if not provided, %ZEN.proxyObject is used.
pObject is the object created from the the JSON. pIgnoreUnknownProps controls whether properties that are not defined in the object structure will be ignored or treated as an error condition. The default behaviour is to stop processing the incoming JSON.
classmethod %ObjectToJSON(pObject As %RegisteredObject, ByRef pVisited, pLevel As %Integer = 0, pFormat As %String = "aceloqtw") as %Status
Write out the contents of object instance pObject to the current device using JSON notation. pFormat is a flags string to control output formatting options.
The following character option codes are supported:
1-9 : indent with this number of spaces (4 is the default with the 'i' format specifier)
a - output null arrays/objects
b - line break before opening { of objects
c - output the Caché-specific "_class" and "_id" properties
d - output Caché numeric properties that have value "" as null
e - output empty object properties
i - indent with 4 spaces unless 't' or 1-9
l - output empty lists
n - newline (lf)
o - output empty arrays/objects
q - output numeric values unquoted even when they come from a non-numeric property
s - use strict JSON output - NOTE: special care should be taken when sending data to a browser, as using this flag may expose you to cross site scripting (XSS) vulnerabilities if the data is sent inside <script> tags. Zen uses this technique extensively, so this flag should NOT be specified for jsonProviders in Zen pages.
t - indent with tab character
u - output pre-converted to UTF-8 instead of in native internal format
w - Windows-style cr/lf newline
method %SetTargetObject(pObject As %RegisteredObject) as %Status
Set pObject as the target object for this provider.
Set targetClass to the target object class.
classmethod %WriteJSONFromArray(pVar As %String = "", pClass As %String = "", pArrayMethod As %String = "", ByRef pParms As %String, pReturnStatus As %Boolean = 0, pFormat As %String) as %String
Utility method to allow direct use of JSON from a non-ZEN context (such as a CSP page).
Calls the class method pArrayMethod within the class pClass and converts the resulting array to an array of objects in JSON format using the convention of the OnGetArray callback.
The JSON notation is written out to the current device.
pVar is the optional name of the client-side Javascript variable that refers to the JSON notation.
pParms is an optional array of parameter names and values that is passed to the callback method.
pReturnStatus is a flag to control whether the status code from the method should be returned to the caller. If pReturnStatus is 0, an alert will be raised via Javascript. If pReturnStatus is 1, the status code will be used as the return value from the method and an alert will NOT be raised.
pFormat is a flags string that controls output formatting options.
The following character option codes are supported:
1-9 : indent with this number of spaces (4 is the default with the 'i' format specifier)
a - output null arrays/objects
e - output empty object properties
i - indent with 4 spaces unless 't' or 1-9
l - output empty lists
n - newline (lf)
o - output empty arrays/objects
s - use strict JSON output - NOTE: special care should be taken when sending data to a browser, as using this flag may expose you to cross site scripting (XSS) vulnerabilities if the data is sent inside <script> tags. Zen uses this technique extensively, so this flag should NOT be specified for jsonProviders in Zen pages.
t - indent with tab character
u - output pre-converted to UTF-8 instead of in native internal format
w - Windows-style cr/lf newline
From a CSP page, you could invoke the method as follows:
#(##class(%ZEN.Auxiliary.jsonProvider).%WriteJSONFromArray("json",$classname(),"GetArray"))#
classmethod %WriteJSONFromObject(pVar As %String = "", pClass As %String = "", pMethod As %String = "", ByRef pParms As %String, pReturnStatus As %Boolean = 0, pFormat As %String) as %String
Utility method to allow direct use of JSON from a non-ZEN context (such as a CSP page).
Calls the class method pMethod within the class pClass and converts the resulting object to JSON format using the convention of the OnGetTargetObject callback.
The JSON notation is written out to the current device.
pVar is the optional name of the client-side Javascript variable that refers to the JSON notation.
pParms is an optional array of parameter names and values that is passed to the callback method.
pReturnStatus is a flag to control whether the status code from the method should be returned to the caller. If pReturnStatus is 0, an alert will be raised via Javascript. If pReturnStatus is 1, the status code will be used as the return value from the method and an alert will NOT be raised.
pFormat is a flags string that controls output formatting options.
The following character option codes are supported:
1-9 : indent with this number of spaces (4 is the default with the 'i' format specifier)
a - output null arrays/objects
b - line break before opening { of objects
c - output the Caché-specific "_class" and "_id" properties
d - output Caché numeric properties that have value "" as null
e - output empty object properties
i - indent with 4 spaces unless 't' or 1-9
l - output empty lists
n - newline (lf)
o - output empty arrays/objects
q - output numeric values unquoted even when they come from a non-numeric property
s - use strict JSON output - NOTE: special care should be taken when sending data to a browser, as using this flag may expose you to cross site scripting (XSS) vulnerabilities if the data is sent inside <script> tags. Zen uses this technique extensively, so this flag should NOT be specified for jsonProviders in Zen pages.
t - indent with tab character
u - output pre-converted to UTF-8 instead of in native internal format
w - Windows-style cr/lf newline
From a CSP page, you could invoke the method as follows:
#(##class(%ZEN.Auxiliary.jsonProvider).%WriteJSONFromObject("json",$classname(),"GetObject"))#
classmethod %WriteJSONStreamFromArray(pStream As %Stream.Object, pClass As %String, pArrayMethod As %String, ByRef pParms As %String, pRewindStream As %Boolean = 0, pFormat As %String) as %Status
Utility method to allow JSON output to be written to a stream from a general non-ZEN context.
Calls the class method pArrayMethod within the class pClass and converts the resulting array to an array of objects in JSON format using the convention of the OnGetArray callback.
The JSON notation is written out to the stream supplied in pStream.
pParms is an optional array of parameter names and values that is passed to the callback method.
pRewindStream is a flag to control whether the stream should be rewound after the data is written to it.
pFormat is a flags string to control output formatting options.
The following character option codes are supported:
1-9 : indent with this number of spaces (4 is the default with the 'i' format specifier)
a - output null arrays/objects
e - output empty object properties
i - indent with 4 spaces unless 't' or 1-9
l - output empty lists
n - newline (lf)
o - output empty arrays/objects
s - use strict JSON output - NOTE: special care should be taken when sending data to a browser, as using this flag may expose you to cross site scripting (XSS) vulnerabilities if the data is sent inside <script> tags. Zen uses this technique extensively, so this flag should NOT be specified for jsonProviders in Zen pages.
t - indent with tab character
u - output pre-converted to UTF-8 instead of in native internal format
w - Windows-style cr/lf newline
classmethod %WriteJSONStreamFromObject(pStream As %Stream.Object, pObject As %String, pMethod As %String, ByRef pParms As %String, pRewindStream As %Boolean = 0, pFormat As %String) as %Status
Utility method to allow JSON output to be written to a stream from a general non-ZEN context.
Calls the class method pMethod within the class pClass and converts the resulting object to JSON format using the convention of the OnGetTargetObject callback. However, if an object is supplied in pClass, then the supplied object will be used as the source object.
The JSON notation is written out to the stream supplied in pStream.
pParms is an optional array of parameter names and values that is passed to the callback method. If pClass is an object, these parameters will be ignored.
pRewindStream is a flag to control whether the stream should be rewound after the data is written to it.
pFormat is a flags string to control output formatting options.
The following character option codes are supported:
1-9 : indent with this number of spaces (4 is the default with the 'i' format specifier)
a - output null arrays/objects
b - line break before opening { of objects
c - output the Caché-specific "_class" and "_id" properties
d - output Caché numeric properties that have value "" as null
e - output empty object properties
i - indent with 4 spaces unless 't' or 1-9
l - output empty lists
n - newline (lf)
o - output empty arrays/objects
q - output numeric values unquoted even when they come from a non-numeric property
s - use strict JSON output - NOTE: special care should be taken when sending data to a browser, as using this flag may expose you to cross site scripting (XSS) vulnerabilities if the data is sent inside <script> tags. Zen uses this technique extensively, so this flag should NOT be specified for jsonProviders in Zen pages.
t - indent with tab character
u - output pre-converted to UTF-8 instead of in native internal format
w - Windows-style cr/lf newline
clientmethod getContentObject() [ Language = javascript ]
Return the client-side JSON data as an object or null.
clientmethod getContentType() [ Language = javascript ]
Return the type of the data supplied by this provider: "object" or "array".
clientmethod getData(d1, d2, d3) [ Language = javascript ]
dataSet API
Return the data contained in the specified location. Location is 0-based.
final clientmethod getDataAsArrays() [ Language = javascript ]
This is a specialized variant of getData()() that returns the data in this controller as an array of arrays (used by charts).
clientmethod getDataSourceCaption(which, text) [ Language = javascript ]
Return a title to display for this data source. This provides the title for a chart.
which indicates which type of caption: "title", "subtitle",etc. text is the original text for the caption.
clientmethod getDimSize(dim) [ Language = javascript ]
Return the number of items in the specified dimension (dim is 1,2, or 3).
clientmethod getError() [ Language = javascript ]
Get the current value of the error property. This is set when a server-side method encounters an error.
clientmethod getLabel(n, dim) [ Language = javascript ]
Get the label at position n (0-based) in the given dimension (1,2, or 3).
clientmethod getPropertyName(n) [ Language = javascript ]
Given a 0-based index, return the corresponding property name.
clientmethod hasData() [ Language = javascript ]
Return true if this controller currently contains data.
clientmethod onloadHandler() [ Language = javascript ]
This client event, if present, is fired when the page is loaded.
clientmethod refreshContent() [ Language = javascript ]
Deprecated: use reloadContents()().
clientmethod reloadContents() [ Language = javascript ]
Reload the contents of the provider with data from the server.
Unlike the submitContent()() method, this does not send data to the server.
This is typically used in conjunction with the OnGetArray callback — this method will call the server and the server, in turn, will invoke the OnGetArray callback to create new content to ship back to the client.
clientmethod reloadContentsAsynch(notify, time) [ Language = javascript ]
Reload the contents of the json provider asynchronously; invoke the function notify when complete. If time is defined, then raise the notify function every time ms until the task is complete.
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 setContentObject(obj) [ Language = javascript ]
Make obj the new target object for this provider.
clientmethod setContentText(json) [ Language = javascript ]
Set the content for this provider using the string json. json is expected to contain object data in JSON format.
clientmethod setContentType(type) [ Language = javascript ]
Set the type of the data supplied by this provider: "object" or "array".
clientmethod submitContent(command, targetClass, notify, time) [ Language = javascript ]
Send the current target object for this provider to the server for processing. This will recreate the object on the server and invoke the OnSubmitContent callback.
This method will return true if successful and false otherwise. If the method fails, an error string is placed in this object's error property (accessible via the getError()() method).
command is an optional string that is passed on to the server callback method to allow for different behaviors in the server logic.
targetClass is an optional argument that, if specified, should be the name of the server-class that you wish to have instantiated on the server. This has the same effect as setting the targetClass property. This makes it possible to submit content for different object classes. If the server cannot create an instance of the specified class, it will return an error.
Normally the submit operation is synchronous. If the optional notify parameter is a function, then the operation will be invoked asynchronously and notify will be invoked when the operation is complete. Note that only one asynchronous operation can be handled at a time.
If time is defined, then raise the notify function every time milliseconds until the task is complete.

Inherited Members

Inherited Properties

Inherited Methods

Subclasses

FeedbackOpens in a new tab