Script mappers

From Dreamtsoft Wiki
Jump to: navigation, search

For more information on how to use script mappers visit our Youtube: https://www.youtube.com/watch?v=NL0aHAYFyGU&amp=&feature=youtu.be

/**
* This is the base class for any scripted mappers
* 
* To create a ScriptMapper, extend this class and implement any of the bucket methods that you need to support. 
* 
* 		var MyNewScriptMapper = BaseMapper.create({
*
*				... put your script mapper code here ...
*
*		});
*
*			// Export your Mapper so it is available as a module
*			module.exports = MyNewScriptMapper;
*
*
* The following class variables are available to your ScriptMapper class:
* 
* 
* 		this.bucketName - (string) name of the bucket
* 		this.bucketAttributes - ({}) the attributes for the bucket
* 
*/


/**
* Search a bucket
* 
* @param searchParams
*            object containing the SlotSearch information
* 
* 	  {
*				full_row: "true|false",
*				full_count: "true|false",
*				query: [
*						[
*							{
*								name: FIELD,
*								oper: OPERATOR,
*								value: VALUE
*							}
*						]
*					],
*					resolve_references: "true|false",
*					limit: NUMBER,
*					need_metadata: "true|false",
*					page: NUMBER
*					order: [
*						{
*							name: FIELD,
*							descending: "true|false"
*						}
*					]
*			  }
*
* 
* @return Array of objects (one per row) containing fieldname/value pairs or an object of fieldname/value pairs if
*         returning a single row
*/
search: function(searchParams)

/**
* Invoke an API off a bucket
* 
* @param apiName
*            Name of API
* @param data
*            Data to be passed to API
* 
* @return Array of objects (one per row) containing fieldname/value pairs or an object of fieldname/value pairs if
*         returning a single row
*/
api: function(apiName, data)

/**
* Insert a row into a bucket
* 
* @param newValues
*            object containing the field values to insert
* 
* @return id of inserted row or null if no row inserted
*/
insert: function(newValues)

/**
* Update an existing row in a bucket
* 
* @param updateValues
*            object containing the field values to update to
* @param previousValues
*            object containing the field values before the update
* @param searchParams
*            search parameters object (see 'search' for details on the format)
* 
* @return count of updated rows (0 or 1)
*/
update: function(updateValues, previousValues, searchParams)

/**
* Delete rows from a bucket
* 
* @param deleteParams
*            search parameters object (see 'search' for details on the format)
* 
* @return count of deleted rows (0 if no rows deleted, 1 if one row deleted, etc.)
*/
del: function(deleteParams)

/**
* Add info message that will be returned with the dataservice response
* 
* @param message (String) text of message
*/
addInfoMessage: function(message)

/**
* Add warning message that will be returned with the dataservice response
* 
* @param message (String) text of message
*/
addWarningMessage: function(message)

/**
* Add error message that will be returned with the dataservice response
* 
* @param message (String) text of message
*/
addErrorMessage: function(message)

/**
* Add event that will be returned with the dataservice response
* 
* @param eventName (String) name of the event
* @param data (String) event data
*/
addEvent: function(eventName, data)

/**
* Search a bucket
* 
* @param bucketName (String) bucket to search
* @param search ([]) search group array
* 
* @returns [] of matching rows with each row returned as {} of slot/value pairs
*/
bucketSearch: function(bucketName, search)

/**
* Call API method of a bucket
*
* @param bucketName (String) bucket to search
* @param apiAction (String) the API to call
* @param data (Object) the data to pass to the API, this is where you'd put a "record" property if the API expects one
* 
* @returns [] of rows returned by the API method
*/
bucketApi: function(bucketName, apiAction, data)

/**
* Convert a string from an Character set
* 
* @param s String to convert
* @param encoding character set the string is to be converted from
* @param encoding character set the string is to be converted to
* 
* @return converted String (returned as java Unicode string)
*/
convertString: function(s, fromEncoding, toEncoding)

/**
* Set this to true to have the ScriptMapper sort the returned records.  This is used when
* the script does not handle sorting, so you want the ScriptMapper do it for you.
*/
setNeedSort: function(flag)

/**
* Set this to true to have the ScriptMapper use the search query to filter the returned records.  This is used when
* the script does not handle search/query, so you want the ScriptMapper do it for you.
*/
setNeedSearch: function(flag)

/**
* Set the total number of rows that match the query when only one page of records is being returned by the 'search'
* 
* To support paging, the data service needs to know the full count of rows.  This method is used to specify
* the full count when only a single page of rows is being returned.  When this value is set, the total number
* of rows returned by the Script Mapper will be limited by the 'query.limit' value to ensure that no more than
* the requested number of records is returned.  It is the responsibility of the Script Mapper to return rows starting
* at the first record of the requested page.
* 
* For example, if the query passed to the 'search' api contains the following:
* 
*     query = {
*       limit: 20,
*       page: 1
*     }
* 
* then the script mapper should do the following if there are 50 available records matching the query:
*
*    - call setFullCount(50);
*    - return [] of rows from record 21-40
*/
setFullCount: function(fullCount)


/**
* Start running async by disconnecting from the connection so that this ScriptMapper can continue to execute without
* blocking the UI. Any communications with the UI after calling startAsync() must be done using the broadcast()
* method.
* 
* @param {Array} rows (optional) if specified, the rows returned to the caller before disconnecting and starting to run async 
*/
startAsync: function(rows)

/**
* Stop running async and close down the ScriptMapper - we are all done
*/
stopAsync: function()

/**
* Set an interval to call the ScriptMapper's onInterval() function every 'x' milliseconds
*/
setInterval: function(ms)

/**
* Send a broadcast message to a UI websocket
* 
* @param {String}
*        source websocket to send this message to (all clients subscribed to this source will receive the message)
* @param {Object}
*        data javascript object sent with the websocket message
*/
broadcast: function(source, data)
/**
 * @return the id of the logged in user's record
 *
 * Note: available as of v0.8
 */
getUserRecordId: function()
/**
 * @return the user_id of the logged in user
 *
 * Note: available as of v0.8
 */
getUserId: function()
/**
* Get the value of a session attribute
*
* @param {String} name session attribute to get
*
* @returns {String} session attribute value
*/
getSessionAttribute: function (name)
/**
* Set the value of a session attribute
*
* @param {String} name session attribute to set
* @param {String} session attribute value
*/
setSessionAttribute: function (name, value)

I have added support for forcing a logout from a Script Mapper, which will result in a login dialog being displayed in the UI before continuing with the current operation. When this situation is encountered as a result of an Ajax call (almost all cases) the login dialog is displayed and after the user successfully logs in again, the dialog is dismissed and the Ajax request is repeated so that things pick up where they left off.

To support this, a new method is available to the Script Mappers:

/**
 * Tell the UI that a login is required for the session
 *
 * The UI, in response to this occurring, will display a Login Dialog asking the user to login in again before continuing.
 *
 * Notes: 
 *   - This method has no effect when the ScriptMapper is in async mode
 *   - This API is available starting with v0.8.0
 */
setLoginRequired: function()
/**
 * Add a resolved reference value to our return information so that the reference display value does not have
 * to be looked up again
 */
addResolvedReference: function(bucketName, id, displayValue)
/**
 * Get the slot definitions for a bucket
 * 
 * @param bucketName - name of bucket to get slot definitions for
 * 
 * @return Array of slot definitions or empty array if not found
 */
getSlotDefinitions: function(bucketName)
/**
 * Get the slot definition for a slot within a bucket
 *
 * @param bucketName - name of bucket to get slot definition for
 * @param slotName - name of slot to get definition for
 *
 * @return SlotDefinition for specified slot or null if not found
 */
getSlotDefinition: function(bucketName, slotName)

link title