BCD-UI

Namespace: wrsUtil

bcdui.wrs. wrsUtil

Utility functions for working with wrs:Wrs documents from JavaScript. These are mainly JavaScript wrappers around XML library found a bcdui/xslt

Methods

staticbcdui.wrs.wrsUtil.applyScale(wrsDoc)

wrs/wrsUtilPackage.js, line 1443
applies number rounding at defined wrs:Header/wrs:Columns/wrs:C/@scale
Name Type Description
wrsDoc DomDocument the Wrs document to apply changes on
Returns:
wrsDoc

staticbcdui.wrs.wrsUtil.copy(args)

wrs/wrsUtilPackage.js, line 255
Copy (copies selected cells to clipboard, not changes source model)
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer Restore rows from
rowEndPos integer rowStartPos optional Restore rows including to.
colStartPos integer 1 optional Restore cols from
colEndPos integer colStartPos optional Restore cols including to.
fn function optional Callback function called after operation

staticbcdui.wrs.wrsUtil.copyAllRows2CSV(args)

wrs/wrsUtilPackage.js, line 504
Copy all rows to CVS
Name Type Description
args Object Parameter object with the following properties
Name Type Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
fn function optional Callback function called after operation

staticbcdui.wrs.wrsUtil.deleteColumns(wrs, colIdArray)

wrs/wrsUtilPackage.js, line 1125
Phsyically drops columns from Wrs
Name Type Description
wrs DomElement WRSRootNode: Pointing to wrs:Wrs
colIdArray Array.<string> Array of column-ids to remove

staticbcdui.wrs.wrsUtil.deleteRow(model, rowId, propagateUpdate)

wrs/wrsUtilPackage.js, line 1187
Deletes a row identified by id, also see deleteWrsRow()
Name Type Default Description
model string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowId string Id of row to be deleted
propagateUpdate boolean false optional If true, fire after change
Returns:
true if given row has been modified and converted to wrs:D or false

staticbcdui.wrs.wrsUtil.deleteRowByColumnValue(wrs, colIdOrPos, values)

wrs/wrsUtilPackage.js, line 1215
delete rows identified by the column value(s)
Name Type Description
wrs DomDocument | DomElement the Wrs document
colIdOrPos number | string column id or position
values array array of string values to lookup

staticbcdui.wrs.wrsUtil.deleteRows(args)

wrs/wrsUtilPackage.js, line 122
Deleting rows (operation will change source model). See restore() on how the change history is maintained.
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer Delete rows from
rowEndPos integer rowStartPos optional Delete rows including to. By default is equal rowStartPos
fn function optional Callback function called after operation
propagateUpdate boolean true optional If false, model is not fired

staticbcdui.wrs.wrsUtil.duplicateRow(model, row, propagateUpdate, fn)

wrs/wrsUtilPackage.js, line 448
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
row DomElement | string Row element or row-id to be duplicated
propagateUpdate boolean true optional If false, model is not fired
fn function optional Callback function called after operation

staticbcdui.wrs.wrsUtil.duplicateRows(args)

wrs/wrsUtilPackage.js, line 465
Duplicate rows in Wrs. Fires fire
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer optional First row to be duplicated
rowEndPos integer rowStartPos optional Last row to be duplicated
fn function optional Callback function called after operation
insertBeforeSelection boolean true optional
propagateUpdate boolean true optional If false, model is not fired

staticbcdui.wrs.wrsUtil.generateWrsHeaderMeta(wrsDoc){object}

wrs/wrsUtilPackage.js, line 799
Generates metadata JS object from a Wrs document
Name Type Description
wrsDoc DomDocument WRS Document to build a header from
Returns:
Type Description
object with { [column-id] : {object-with-attrs from wrs:Column/wrs:C} }

staticbcdui.wrs.wrsUtil.getCellValue(wrs, rowId, columnId){string}

wrs/wrsUtilPackage.js, line 992
Get cell value
Name Type Description
wrs string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowId string | number The row-id or 1-based position of row
columnId string | number ID or 1-based position of column
Returns:
Type Description
string Current cell value or null

staticbcdui.wrs.wrsUtil.getColPosById(wrs, id){integer}

wrs/wrsUtilPackage.js, line 964
get column position by id
Name Type Description
wrs string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
id string The column-id wrs:C/@id
Returns:
Type Description
integer 1-based column position from the header/pos attribute, 0 if no such column was found

staticbcdui.wrs.wrsUtil.getNextIdentifier(args)

wrs/wrsUtilPackage.js, line 1387
Retrieves next identifier from the server (async)
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
scope string The scope requested
onSuccessCb function The callback, receives following args
  • scope {string} - Requested scope
  • isRange {boolean} - false if blockSize = 1, true otherwise
  • forEach: {function} - Helper iterating function, executing a passed function for each identifier; follows forEach() JS API spec;
  • nextIdentifier {integer} - The next identifier; ONLY defined if isRange = false; otherwise undefined
  • firstIdentifier {integer} - First identifier; ONLY defined if isRange = true; otherwise undefined
  • lastIdentifier {integer} - Last identifier; ONLY defined if isRange = true; otherwise undefined
blockSize integer 1 optional Number of identifiers to be retrieved
onErrorCb function optional An error callback

staticbcdui.wrs.wrsUtil.getRowPositionByRowId(args){integer}

wrs/wrsUtilPackage.js, line 76
1-based position of a row which is identified by its row-id
Name Type Description
args Object Parameter object with the following properties
Name Type Description
model string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowId string Row id of which to get the position
Returns:
Type Description
integer Either position of a row in the document or -1 if no such row was found

staticbcdui.wrs.wrsUtil.getValidationErrorCount(wrs)

wrs/wrsUtilPackage.js, line 820
Convenience method to return error count in current document (possibly validated by validateWrs.xml)
Name Type Description
wrs string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
Returns:
-2: if no validation has been performed, -1: if the data provider is not ready yet, otherwise the number of errors found is returned

staticbcdui.wrs.wrsUtil.getValidationResult(wrs, validationId, doCreate){Node}

wrs/wrsUtilPackage.js, line 1016
get wrs:ValidationResult/wrs:Wrs element for given Wrs (optionally creates an empty one)
Name Type Description
wrs string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
validationId string validationId
doCreate boolean optional, in case no wrs:ValidationResult/wrs:Wrs exists, create one (empty)
Returns:
Type Description
Node wrs:ValidationResult/wrs:Wrs or NULL if none exists and doCreate=false

staticbcdui.wrs.wrsUtil.insertRow(args)

wrs/wrsUtilPackage.js, line 545
Inserting rows
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer 1 optional Start
rowEndPos integer rowStartPos optional End
fn function optional Callback function called after operation
insertBeforeSelection boolean true optional
propagateUpdate boolean true optional If false, model is not fired

staticbcdui.wrs.wrsUtil.parseFilterExpression(expression, params){DomDocument}

wrs/wrsUtilPackage.js, line 1487
Name Type Description
expression string the expression to parse
params object the expression to parse
Returns:
Type Description
DomDocument containing parsed expression
Example
bcdui.wrs.wrsUtil.parseFilterExpression("country = :country or (revenue >= :revenue or today = :today and allow='true' or string='a and b')",{
    country:"DE",
    revenue:1000,
    today:"2018-12-09"
  });
  
  // yields following result document
  <f:And xmlns:f="http://www.businesscode.de/schema/bcdui/filter-1.0.0">
   <f:Or>
     <f:Expression bRef="country" op="=" value="DE"/>
     <f:Or>
       <f:Or>
         <f:Expression bRef="revenue" op=">=" value="1000"/>
         <f:And>
           <f:Expression bRef="today" op="=" value="2018-12-09"/>
           <f:Expression bRef="allow" op="=" value="true"/>
         </f:And>
       </f:Or>
       <f:Expression bRef="string" op="=" value="a and b"/>
     </f:Or>
   </f:Or>
  </f:And>

staticbcdui.wrs.wrsUtil.paste(args)

wrs/wrsUtilPackage.js, line 298
paste (Paste data from clipboard. Changes source model)
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer Restore rows from
rowEndPos integer rowStartPos optional Restore rows including to.
colStartPos integer 1 optional Restore cols from
colEndPos integer 1 optional Restore cols including to.
fn function optional Callback function called after operation
propagateUpdate boolean true optional If false, model is not fired

staticbcdui.wrs.wrsUtil.pasteAsNewRows(args)

wrs/wrsUtilPackage.js, line 348
Paste data from clipboard as new rows. Changes source model
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer Restore rows from
rowEndPos integer rowStartPos optional Restore rows including to.
colStartPos integer 1 optional Restore cols from
colEndPos integer 1 optional Restore cols including to.
fn function optional Callback function called after operation
propagateUpdate boolean true optional If false, model is not fired

staticbcdui.wrs.wrsUtil.postWrs(args)

wrs/wrsUtilPackage.js, line 1314
Name Type Description
args PostWrsParam | XMLDocument | Array.<XMLDocument> | bcdui.core.DataProvider | Array.<bcdui.core.DataProvider> DataProvider(s), Document(s) or a parameter object

staticbcdui.wrs.wrsUtil.read(doc, xPath, params, defaultValue)

wrs/wrsUtilPackage.js, line 1505
Reads the string value from a given xPath (or optionally return default value).
Name Type Description
doc Document the document to operate on
xPath string xPath pointing to value (can include dot template placeholders which get filled with the given params)
params 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)

staticbcdui.wrs.wrsUtil.replaceValidationResult(wrsRootNode, validationResultNode, validationId)

wrs/wrsUtilPackage.js, line 1056
Replaces validationResult/Wrs document in the Wrs, the validationDoc can be provided as NULL to remove the validationResult Wrs from previous validation; the validationId is mandatory to provide to uniquelly identify the subject of validation.
Name Type Description
wrsRootNode DomElement | DomDocument Wrs itself or an element containing Wrs (i.e. Wrs document) where to replace the validation result in
validationResultNode DomElement | DomDocument wrs:ValidationResult (or container with it) containing wrs:Wrs element(s) (which obligatory is tagged with bcdValidationId attribute) if NULL, then the possible existing validationResult is effectively removed from wrs document
validationId string the validationId of the validation result Wrs to replace

staticbcdui.wrs.wrsUtil.restore(args)

wrs/wrsUtilPackage.js, line 164
Restore (operation will change source model). Client side operations on Wrs keep a history, wrs:R turns into wrs:M for modified rows and wrs:D for deleted. Changed columns change from wrs:C to wrs:O. This allows undoing such a change till the data is send to the server.
Name Type Description
args Object Parameter object with the following properties
Name Type Default Description
model bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowStartPos integer Restore rows from
rowEndPos integer rowStartPos optional Restore rows including to.
colStartPos integer 1 optional Restore cols from
colEndPos integer colStartPos optional Restore cols including to.
fn function optional Callback function called after operation
propagateUpdate boolean true optional If false, model is not fired

staticbcdui.wrs.wrsUtil.restoreRow(model, rowId, propagateUpdate)

wrs/wrsUtilPackage.js, line 1251
Restores a wrs:D, wrs:M identified by id, also see restore()
Name Type Default Description
model string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowId string Id of row to be deleted
propagateUpdate boolean false optional If true, fire after change
Returns:
true if given row has been restored or false if row is not wrs:M nor wrs:D

staticbcdui.wrs.wrsUtil.saveModel(args)

wrs/wrsUtilPackage.js, line 100
Save Wrs data of a bcdui.core.DataProvider
Name Type Description
args Object Parameter object with the following properties:
Name Type Default Description
model string | bcdui.core.DataProvider DataProvider (or its id), holding the Wrs with wrs:R|I|M|D row and wrs:C|O column nodesto be saved
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

staticbcdui.wrs.wrsUtil.setCellValue(wrs, rowId, columnIdOrPos, value)

wrs/wrsUtilPackage.js, line 1095
Sets cell value, both, the row and cell MUST exist in target model This also changes wrs:R to wrs:M and clones wrs:C to wrs:O values.
Name Type Default Description
wrs string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
rowId string | number The row-id or 1-based position of row
columnIdOrPos string | number ID or 1-based position of column
value string null optional If NULL then wrs:null node is appended to column
Returns:
true if value has been set, false otherwise

staticbcdui.wrs.wrsUtil.transposeGrouping(input){DomDocument}

wrs/wrsUtilPackage.js, line 843
This transposes the inner-most @dim column column of a WRS from rows to columns. This is faster using the XLST with the same name except for Webkit, where this is faster
Name Type Description
input string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
Returns:
Type Description
DomDocument The transposed document

staticbcdui.wrs.wrsUtil.validateModel(args, validationId)

wrs/wrsUtilPackage.js, line 633
runs validation xslt against given model, you can access the result via returned trafo, see return section. for one-time validation you can supply the callback function (fn parameter)
Name Type Default Description
args Object Parameter object with the following properties
validationId string 'bcdValidationId' attribute in ValidationResult/Wrs yields this value
args.model string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
args.stylesheetUrl url defauldValidation optional URL to validation stylesheet, defaults to 'xslt/validate/validateWrs.xslt'
args.dataProviders Array.<bcdui.core.DataProvider> additional data providers as parameters
args.fn function optional callback function called after validation done, gets object as parameter, containig properties: validationResult: the wrs:ValidationResult node of resulting transformation, may be null
Returns:
created transformation chain for the validation, it can be reused via bcdui.core.reExecute(_validatorTrafo, callBackFn); the data can be accessed via _validatorTrafo.getData() which returns wrs:ValidationResult or null or ValidationResult with empty wrs:Data

staticbcdui.wrs.wrsUtil.write(doc, xPath, params, value){Node}

wrs/wrsUtilPackage.js, line 1530
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 Description
doc Document the document to operate on
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 params)
params 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"
Returns:
Type Description
Node the resulting element (either newly created or existing one)

staticbcdui.wrs.wrsUtil.wrsValidation(args)

wrs/wrsUtilPackage.js, line 693
Wrs validation which validates selected wrs:C against provided validation function parameters:
Name Type Description
args Object Parameter object with the following properties
Name Type Description
validationId string the ID of this validator
model string | bcdui.core.DataProvider Id of a DataProvider or the DataProvider itself (dp must be ready)
cellValidation.func function function taking args object with: 'wrsC' - the wrs:C element to validate 'wrsHeaderC' - the wrs:Header/wrs:Columns/wrs:C meta info element returns either NULL (valid) or { validationMessage:String }
cellValidation.bRefSelector function function taking wrs:Header element and returns node-set of wrs:Columns/wrs:C to get validated
Returns:
wrsDoc