BCD-UI

Class: AutoModel

bcdui.core. AutoModel

An AutoModel is an easy way for loading data from a BindingSet in many cases. At minimum just provide the BindingSet id and a list of bRefs.

new bcdui.core.AutoModel(args)

core/autoModel.js, line 22
Name Type Description
args Object The parameter map contains the following properties. Most parameters only apply when using default wrq-stylesheet.
Name Type Default Description
bindingSetId string Id of BindingSet to read from.
bRefs string Space separated list of bRefs to be loaded.
filterBRefs string optional Space separated list of bRefs in $guiStatus f:Filter to be used as filters. TODO: add static
orderByBRefs string optional Space separated list of bRefs that will be used to order the data. This ordering has a higher priority over possible auto ordering by useCaptions or isDistinct. A minus(-) sign at the end indicates descending sorting.
initialFilterBRefs string optional Space separated list of bRefs in $guiStatus f:Filter to be used as filters for initial, very first request only. Unlike filterBRefs, these filter values are not monitored for changes.
mandatoryFilterBRefsSubset string optional Space separated subset of bRefs that needs to be set before the AutoModel gets data. Until available, no request will be run.
isDistinct boolean false optional If true, a group-by across all columns is generated. Parameter .groupByBRefs is ignored in this case.
useCaptions boolean false optional If true, @bRef+'_caption' will be used as bRef for the caption.
additionalFilterXPath modelXPath optional Allows using additional filters not part of $guiStatus f:Filter. These filters are monitored for changes. The given xPath needs to point to the filter expression itself, not to a parent.
additionalPassiveFilterXPath modelXPath optional Optional, allows using additional filters not part of $guiStatus f:Filter, unlike 'additionalFilterXPath', this xPath is not monitored for changes.
maxRows number optional Optional, limits the request to n rows. Use distinct if you need a certain order.
id string optional A globally unique id for use in declarative contexts
isAutoRefresh boolean false optional If true, will reload when any (other) filter regarding a bRefs or the additionalFilterXPath change.
reqDocParameters Object optional Optional parameters for a custom request document builder.
reqDocChain Array ['wrs/requestDocumentBuilder.xslt'] optional Optional custom chain for request document builder.
statusModel bcdui.core.DataProvider bcdui.wkModels.guiStatus optional the status model to resolve .filterBRefs against
statusModelEstablished bcdui.core.DataProvider optional the established status model to provide to ModelWrapper creating request document as 'statusModelEstablished' parameter
groupByBRefs string optional Space separated list of bRefs for grouping. Is not effective when using .isDistinct=true parameter.
filterElement DomDocument | DomElement | string optional custom filter element (f:And, f:Or, f:Not, f:Expression) in wrs-filter format, see filter-1.0.0.xsd or a string as required by bcdui.wrs.wrsUtil.parseFilterExpression or the result of it - note that the function allows filling in values without escaping issues if the filter is not fixed.
saveOptions Object optional An object, with the following elements
Name Type Default Description
saveChain chainDef optional The definition of the transformation chain
saveParameters Object optional An object, where each property holds a DataProvider, used as a transformation parameters.
reload boolean false optional Useful especially for models of type SimpleModel for refreshing from server after save
onSuccess function optional Callback after saving (and optionally reloading) was successfully finished
onFailure function optional Callback on failure, is called if error occurs
onWrsValidationFailure function optional Callback on serverside validate failure, if omitted the onFailure is used in case of validation failures
urlProvider bcdui.core.DataProvider optional DataProvider holding the request url (by default taken from the underlying simple model url)
Example
// Create a simple AutoModel, reading distinct bindingItems 'country', 'region' and 'city' from BindingSet 'md_geo'
var am = new bcdui.core.AutoModel({ bindingSetId: "md_geo", bRefs: "country region city", isDistinct: true, filterElement: "country='DE'" });

Extends

Members

constantidstring

A globally unique id of the object. DataProviders do also register themselves at bcdui.factory.objectRegistry when an id is provided to the constructor. This id is only needed in declarative contexts, like jsp or, when a DataProvider is accessed in a xPath like . If not provided in the constructor, a random id starting with 'bcd' is set, but the object is not automatically registered.

constantinitializedStatus

The model was created but no myModel.execute() was called explicitly or by a DataProvider or Renderer, having this as an input.

constantsavedStatus

Example
if( model.getStatus() === model.savedStatus )
  ...

constantsaveFailedStatus

constanttransformedStatus

Indicating the model is ready for access. Check via myModel.isReady()

Methods

inherited addStatusListener(args)

core/abstractExecutable.js, line 217
Listen for any status to be reached. For use cases with the ready status (by far the most common), see onReady() and onceReady() convenience functions.
Name Type Description
args function | StatusListener | AddStatusListenerParam Either a function executed on all status transitions or a parameter map AddStatusListenerParam

inherited debugIsWaitingFor(){string}

core/dataProvider.js, line 358
Returns:
Type Description
string Human readable message, which DataProviders, this DataProvider depends on, are not currently in ready state

inherited debugStatus(){string}

core/dataProvider.js, line 371
Returns:
Type Description
string Human readable message about the current state state

inherited execute(doesRefresh)

core/abstractExecutable.js, line 532
Executes the process implemented by the concrete sub-class.
Name Type Default Description
doesRefresh boolean true optional Set this parameter to "false" if this method should do nothing when the object is already in the ready status. The default is "true" meaning that the process is re-started when it is currently ready.

inherited fetchData(){Promise}

core/dataProvider.js, line 727
asynchronously fetch data for this data provider.
Returns:
Type Description
Promise resolving once data has been loaded, first argument is this instance
Example
new bcdui.core.SimpleModel("data.xml").fetchData().then((dp)=>{ console.info(dp.getData()); })

inherited fire()

core/dataProvider.js, line 304
This informs modification listeners, registered via onChange(args), that a change set was completed and data is consistent again.
Example
// Use of data modification events
var model = new bcdui.core.StaticModel({ data: { value: 3 } });
model.execute();
model.onChange( function(m) {
  console.log(m.getData().value);
});
model.getData().value ++;
model.fire(); // console prints '4'

inherited getFailedStatus(){Array}

core/simpleModel.js, line 382
Returns the list of status objects indicating that something has failed.
Returns:
Type Description
Array The array of failure bcdui.core.Status objects.

inherited getName(){string}

core/dataProvider.js, line 315
Getter for the name of the data provider. This name is for example used to set parameters names of a bcdui.core.TransformationChain.
Returns:
Type Description
string The name of the data provider. This name should be unique within the scope it is used and is usually not globally unique (as the id).

inherited getReadyStatus(){bcdui.core.Status}

core/simpleModel.js, line 373
The SimpleModel reaches its ready status when the XML document has been loaded from the URL and the optional model updates have run. The document can then be retrieved with the "getDataDoc" method.

The status transitions of the class are as follows:

  InitializedStatus All variables have been initialized.
  
Loading If it is not ready execute URL data provider (execute).
  
URLAvailable The URL data provider is ready, start loading data.
  
Loaded The data has been loaded from the URL.
  
RefreshingModelUpdaters ModelUpdaters are currently running.
  
 
 TransformedStatus All model updaters have run. (ready)
  
Saving The posting of data will start.
  
SavedStatus The data has been posted to the server.

Returns:
Type Description
bcdui.core.Status The ready state of the document.

inherited getStatus(){bcdui.core.Status}

core/abstractExecutable.js, line 376
Getter for the status of this object. See bcdui.core.status for possible return values.
Returns:
Type Description
bcdui.core.Status The current status.

inherited hasFailed(){boolean}

core/abstractExecutable.js, line 396
Tests if the object has reached a failure status. These status codes are returned by the "getFailedStatus" method.
Returns:
Type Description
boolean True, if the object's process has failed.

inherited isClean(){boolean}

core/dataProvider.js, line 709
True, if DataProvider is ready and there are no uncommitted write transactions, see isReady() and fire().
Returns:
Type Description
boolean

inherited isReady(){boolean}

core/abstractExecutable.js, line 386
Tests if the current state is the readyStatus. This status is the same status as returned by "getReadyStatus".
Returns:
Type Description
boolean True, if the object is ready.

inherited onceReady(listenerObject)

core/abstractExecutable.js, line 561
Name Type Description
listenerObject function | OnceReadyParam Either a function to be called on ready status (i.e. onSuccess) or a parameter map OnceReadyParam. To listen for other states see addStatusListener()
Example
myModel.onceReady({onSuccess: myCallback, executeIfNotReady: true})

inherited onChange(listenerObject, trackingXPath)

core/dataProvider.js, line 563
Name Type Description
listenerObject function | OnChangeParam Either a function to be called after changes or a parameter map OnChangeParam. Listeners can be removed with removeDataListener()
trackingXPath string optional xPath to monitor to monitor for changes

inherited onReady(listenerObject)

core/abstractExecutable.js, line 595
Name Type Description
listenerObject function | OnReadyParam Either a function to be called on ready status (i.e. onSuccess) or a parameter map OnReadyParam. To listen for other states see addStatusListener()
Example
myModel.onReady({onSuccess: function(){ console.log("ready") }, executeIfNotReady: true, onlyFuture: true})

inherited promptData()

core/dataProvider.js, line 334
Convenience method for debugging showing data in a prompt for copy-and-paste

inherited query(xPath, fillParams)

core/dataProvider.js, line 487
Reads a single node from a given xPath
Name Type Description
xPath string xPath to query
fillParams Object optional array or object holding the values for the dot placeholders in the xpath. Values with "'" get 'escaped' with a concat operation to avoid bad xpath expressions
Returns:
single node or null if query fails

inherited queryNodes(xPath, fillParams)

core/dataProvider.js, line 499
Get node list from a given xPath
Name Type Description
xPath string xPath to query
fillParams Object optional array or object holding the values for the dot placeholders in the xpath. Values with "'" get 'escaped' with a concat operation to avoid bad xpath expressions
Returns:
node list or empty list if query fails

inherited read(xPath, fillParams, defaultValue)

core/dataProvider.js, line 418
Reads the string value from a given xPath (or optionally return default value).
Name Type Description
xPath string xPath pointing to value (can include dot template placeholders which get filled with the given fillParams)
fillParams Object optional array or object holding the values for the dot placeholders in the xpath. Values with "'" get 'escaped' with a concat operation to avoid bad xpath expressions
defaultValue string optional default value in case xPath value does not exist
Returns:
text value stored at xPath (or null if no text was found and no defaultValue supplied)

inherited remove(xPath, fillParams, fire)

core/dataProvider.js, line 469
Deletes data at a given xPath from the model
Name Type Default Description
xPath string xPath pointing to the value
fillParams Object optional array or object holding the values for the dot placeholders in the xpath. Values with "'" get 'escaped' with a concat operation to avoid bad xpath expressions
fire boolean false optional if true a fire is triggered to notify data modification listener

inherited removeDataListener(listenerObject)

core/dataProvider.js, line 525
Name Type Description
listenerObject string | function | RemoveDataListenerParam Either a listener function or id or a parameter map RemoveDataListenerParam. Listeners are added with onChange()

inherited removeStatusListener(args)

core/abstractExecutable.js, line 239
Name Type Description
args function | StatusListener | RemoveStatusListenerParam The listener to be removed. This can either be a function or a StatusListener or a parameter map RemoveStatusListenerParam.

inherited sendData()

core/dataProvider.js, line 158
Sends the current data to the original URL

inherited serialize()

core/dataProvider.js, line 509
Serialize dataprovider's data if available
Returns:
String containing the serialized data

inherited setStatus(args)

core/dataProvider.js, line 693
Name Type Description
args Status

inherited toString(){string}

core/simpleModel.js, line 411
Debugging function showing a text for this model.
Returns:
Type Description
string A summary of the model.

inherited write(xPath, fillParams, value, fire)

core/dataProvider.js, line 445
Set a value to on a certain xPath and create the xPath where necessary. This combines Element.evaluate() for a single node with creating the path where necessary. It will prefer extending an existing start-part over creating a second one. After the operation the xPath (with the optional value) is guaranteed to exist (pre-existing or created or extended) and the addressed node is returned.
Name Type Default Description
xPath string xPath pointing to the node which is set to the value value or plain xPath to be created if not there. It tries to reuse all matching parts that are already there. If you provide for example "/n:Root/n:MyElem/@attr2" and there is already "/n:Root/n:MyElem/@attr1", then "/n:Root/n:MyElem" will be "re-used" and get an additional attribute attr2. Many expressions are allowed, for example "/n:Root/n:MyElem[@attr1='attr1Value']/n:SubElem" is also ok. By nature, some xPath expressions are not allowed, for example using '//' or "/n:Root/n:MyElem/[@attr1 or @attr2]/n:SubElem" is obviously not unambiguous enough and will throw an error. This method is Wrs aware, use for example '/wrs:Wrs/wrs:Data/wrs:*[2]/wrs:C[3]' as xPath and it will turn wrs:R[wrs:C] into wrs:M[wrs:C and wrs:O], see Wrs format. (can include dot template placeholders which get filled with the given fillParams)
fillParams Object optional array or object holding the values for the dot placeholders in the xpath. Values with "'" get 'escaped' with a concat operation to avoid bad xpath expressions Example: bcdui.wkModels.guiStatus.write("/guiStatus:Status/guiStatus:ClientSettings/guiStatus:Test[@caption='{{=it[0]}}' and @caption2='{{=it[1]}}']", ["china's republic", "drag\"n drop"])
value string optional Optional value which should be written, for example to "/n:Root/n:MyElem/@attr" or with "/n:Root/n:MyElem" as the element's text content. If not provided, the xPath contains all values like in "/n:Root/n:MyElem[@attr='a' and @attr1='b']" or needs none like "/n:Root/n:MyElem"
fire boolean false optional If true a fire is triggered to inform data modification listeners
Returns:
The xPath's node or null if dataProvider isn't ready