Developing APIs‎ > ‎Extensibility‎ > ‎

Resource Row Events

A resource row event is a piece of JavaScript that gets executed every time 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.

Variables

You can define the following variables for the JavaScript code:

  • row
  • tableRow
  • parentRow
  • resource
  • req

The row Variable

The row variable 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 sees data that does not correspond to what is actually in the database. If you change the value of an attribute, you cannot update this object unless you override the checksum.

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

Examples:

If you want only a specific customer to have an attribute named full_name, composed of the customer's first name and last name, you can add a filter to a resource called Customers, for example:

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, for example:

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, for example:

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

You can suppress individual items in a row from the output JSON, for example:

if ('David' == row.username') {
   delete row.last_name;
}

Added attributes are noted in the @metadata section as 'nonpersistent'. Removed attributes are noted in the @metadata section as 'removedAttributes'.

The tableRow Variable

The tableRow variable is the row as read from the database and p
rovides access to the database record after security has been applied, changes ignored.

The parentRow Variable

If the resource is a subresource, and the user is accessing it by way of its containing resource (for example, with a URL like /MyParent as opposed to accessing the subresource directly with a URL like /MyParent.MyChild), then the variable parentRow is defined. It contains the parent row.

Important! Do not change anything in this parent row. The parent row exists for reference only.

Example:

You can check if the containing row is null, for example:

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

The resource Variable

The resource variable provides access to the resource object. The resource definition is passed as this variable. It 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, for example, parent_ident = [ident].
  • getName() returns the name of the resource, for example MyChild.
  • getNodalName() returns the full name of the resource, for example, 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.

Example:

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.
For more information about this variable, see The Request Object.

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. The following image shows this example on the Create, Resources, Attributes tab:

The Attribute name field is the column name alias.

Then, on the Create, Resources, Row Event tab, paste in the following code as the row event, and save your changes:

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.

For more information: