Resource Row Events

A resource row event is a piece of JavaScript that gets executed every time Live API Creator retrieves a row from the database for a specific resource or sub-resource. This JavaScript code can then manipulate the row to delete it or add/drop attributes. Resource Row Events are powerful; use them with caution.

The JavaScript code can assume that it will have the following variables defined:

The row variable

row is the row the database just retrieved. You retrieve values from it just like any JavaScript object. You can change the values of the object, but the client will then see data that does not correspond to what is actually in the database. If you change the value of an attribute, you will not be able to update this object unless you override the checksum.

You can also add new values, like a computed value.

Example:

If you wanted only a specific customer to have an attribute named full_name, composed of the customer's first name and last name, you could add a filter to a resource called (say) Customers:

if (row.custnum === 1234) {
    row.full_name = row.first_name + ' ' + row.last_name;
}

The added attributes can also be a more complicated JavaScript object or array.
if (row.custnum === 1234) {
    row.name_info = {
      'First': row.first_name ,
      'Last' : row.last_name,
      'FullName': row.first_name+ ' ' + row.last_name;
    }
}

You can also filter out the row entirely, if you decide that it should not be sent to the client

if (row.username == 'DoNotShow') {
    row = null;
}

Individual items in a row can be suppressed from the output JSON.
if ('David' == row.username') {
   delete row.last_name;
}

Added attributes will be noted in the @metadata section as 'nonpersistent'. Removed atrtributes will be noted in the @metadata section as 'removedAttributes'.

The parentRow variable

If the resource is a subresource, and the user is accessing it via its containing resource (i.e. with a URL like /MyParent as opposed to accessing the subresource directly with a URL like /MyParent.MyChild), then the variable parentRow will be defined. It will contain the parent row. Do not change anything in this parent row. The parent row exists for reference only.

// parentRow may be null, need to check first
if (parentRow) {
    row.full_name = parentRow.name + '.' + row.name;
}

The resource variable

You can also use the resource definition, which is passed as the variable resource. This variable has the following methods:
  • getAttributes() returns a list of the attributes defined for this resource. Each attribute has a name, a columnName, and a format (if defined). 
  • getJoinCondition() returns a string, which contains the raw definition of the join to the parent resource, e.g. parent_ident = [ident]
  • getName() returns the name of the resource, e.g. MyChild
  • getNodalName() returns the full name of the resource, e.g. MyParent.MyChild
  • getTableName() returns the name of the table for which the resource was defined.
  • getTopResource() returns the top resource in the resource tree.
  • getParentResource() gets the parent resource (if any) of the resource.
var i;
for (i = 0; i < resource.getAttributes().length(); i++) {
    var attribute = resource.getAttributes().get(i);
}

The req variable

The req variable contains an object that describes the request being processed. It contains the following values:
  • apiKey is the API key object
  • baseURL is the base URL on which the current call was made

Example

The following example illustrates:
  • Skipping row, using aliased name
  • Accessing database row before aliasing
  • Adding properties to output json
  • Unicode usage
  • Erasing value (property set to null)
  • Using property name that is not valid with dot syntax
  • Nonpersistent attributes property added to @metadata section
Use a Customer Resource in the Demo sample as shown in the following image (note the column name alias):
Then paste in the following code as the Row Event:

if (row.myname === 'Alpha and Sons') {
    row = null;
}
else if (row.myname === 'Bravo Hardware') {
    row.foo = 'Hi there!';
    row["2xbalance"] = 2 * tableRow.balance;
    row.credit_limit = null;
}
else if (tableRow.name === 'Charlie\'s Construction') {
    // show some love
    row.myname = '\u2764 ' + tableRow.name + ' \u2764';
}
You can run this in the REST Lab, and observe the additional attributes and the @metadata changes.
ċ
Screen Shot 2014-03-25 at 11.27.25 AM | Mar 25, 2014.png
(172k)
Val Huber,
Feb 16, 2016, 2:22 PM
ċ
Screen Shot 2014-08-25 at 10.33.30 AM | Aug 25, 2014.png
(429k)
Val Huber,
Feb 16, 2016, 2:22 PM
ċ
Screen Shot 2014-08-25 at 10.33.32 AM | Aug 25, 2014.png
(182k)
Val Huber,
Feb 16, 2016, 2:22 PM
ċ
Screen Shot 2015-10-22 at 11.14.35 AM.png
(250k)
Val Huber,
Feb 16, 2016, 2:22 PM
Comments