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 (so-called JSON format).
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:
- You place an instance of the (invisible) jsonProvider component on your page.
- You supply a callback method, OnGetTargetObject,
that creates an object or set of objects and returns it. This can be an
instance of a specific class or classes or it can use the generic %ZEN.proxyObject.
- The jsonProvider converts the target object to a set of JavaScript objects
when the page is rendered (which you can see if you view the source of the
page as sent to the client).
- The jsonProvider has a client-side method, getContentObject,
which returns the client-side version of the target object. This is simply a
graph of generic JavaScript Object objects. These objects will have
the same properties and values as the target objects. If the target object refer
to other objects or have collections (literal or object-valued) then the
JavaScript object will have corresponding object or collection properties.
- The client can modify these client-side objects or replace them completely using
the getContentObject method.
- The client can ship its content objects back to the server for processing by
calling the submitContent. This converts the objects back into
server-side objects and invokes the callback method speficied by the
OnSubmitContent property.
- The OnSubmitContent property can modify the objects
shipped to it or return a completely different set of objects. This makes it
possible to use jsonProvider as a way to execute different types of server operations.
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:
- You can ship a set of objects, but the objects must form a graph from a "parent"
object down through levels of "children" (this is due to how JSON format data
is reconstituted on the client). You cannot have child objects refer to parents, siblings
or other objects outside of the graph.
- This approach uses late-binding so it is not as efficient as the code generated
approach used by Zen components.
- Not all object properties are supported: you cannot ship streams or binary
values. Only references to "child" objects are transported. Any user-defined javascript properties whose
name contains an _ (underscore) are not included in the content shipped back to the server.
• parameter DEFAULTVISIBLE = 0;
This component is not visible.
• parameter SYSMODULE = "json";
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 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:
This would result in the 2 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 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) and instance of the object
whose data is to be provided to the client in JSON format.
For example:
• 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 OnSubmitContent
as %ZEN.Datatype.delegator(FORMALSPEC="pCommand:%String,pProvider:%ZEN.Auxiliary.jsonProvider,pSubmitObject:%RegisteredObject,&pResponseObject:%RegisteredObject",RETURNTYPE="%Status");
This callback method is invoked the client submits an object to the
server by calling the submitContent method.
The callback is passed the submitted object 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.
If the callback method returns an object via the pResponse
argument, then this object is returned to the client and becomes the
new content of the JSON provider.
For example:
• 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 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 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 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 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.
• classmethod %ConvertJSONToObject(pContent As %String, pTargetClass As %String = "", Output pObject As %RegisteredObject)
as %Status
Utility method to allow direct use of JSON from a non-ZEN context (such as a CSP page).
pContent is a string containg 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.
• 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)
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 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.
For example:
#(##class(%ZEN.Auxiliary.jsonProvider).%WriteJSONFromArray("json",..%ClassName(1),"GetArray"))#
• classmethod %WriteJSONFromObject(pVar As %String = "", pClass As %String, pMethod As %String, ByRef pParms 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 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.
For example:
#(##class(%ZEN.Auxiliary.jsonProvider).%WriteJSONFromObject("json",..%ClassName(1),"GetObject"))#
• method getContentObject()
[ Language = javascript ]
Return the client-side JSON data as an object or null.
• method getContentType()
[ Language = javascript ]
Return the type of the data supplied by this provider: "object" or "array".
• method getData(d1, d2, d3)
[ Language = javascript ]
dataSet API
Return the data contained in the specified location.
Location is 0-based;
• final method 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).
• method getDataSourceCaption()
[ Language = javascript ]
Return a title to display for this data source.
This provides the title for a chart.
• method getDimSize(dim)
[ Language = javascript ]
Return the number of items in the specified dimension
(dim is 1,2, or 3).
• method getError()
[ Language = javascript ]
Get the current value of the error property.
This is set when a server-side method encounters an error.
• method getLabel(n, dim)
[ Language = javascript ]
Get the label at position n (0-based) in the given
dimension (1,2, or 3).
• method getPropertyName(n)
[ Language = javascript ]
Given a 0-based index, return the corresponding property name.
• method hasData()
[ Language = javascript ]
Return true if this controller currently contains data.
• method onloadHandler()
[ Language = javascript ]
This client event, if present, is fired when the page is loaded.
• method refreshContent()
[ Language = javascript ]
Deprecated: use reloadContents.
• method 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.
• method 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.
• method setContentObject(obj)
[ Language = javascript ]
Make obj the new target object for this provider.
• method setContentText(json)
[ Language = javascript ]
Set the content for this provider using the string json.
json is expected to contain object data in JSON format.
• method setContentType(type)
[ Language = javascript ]
Set the type of the data supplied by this provider: "object" or "array".
• method submitContent(command, targetClass)
[ 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 (visible 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.
