Resource Row Events

Resource Row Events
lac40
Row events include JavaScript code that API Creator executes each time it retrieves a resource row from the database. You can create row events that delete rows, that add or drop attributes from the row, or that compute data.
In this article:
Create a Resource Row Event
Prerequisite:
The resource to which you want to add a row event exists.
  1. With your API open, in the Create section, click 
    Resources
    .
    A list of resources display.
  2. Select the resource for which you want to add a row event from the resource list, and then click the 
    Row Event
    tab.
    The row event page appears.
  3. Enter JavaScript code in the code editor. You can access and insert JavaScript code examples into the row event code editor.
    For more information about the code examples that are available for row events, see Code Examples.
Variables That are Available in your JavaScript Code
The following variables are available in your JavaScript code:
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 customers filter to a resource, for example:
if (row.custnum === 1234) {
  row.full_name = row.first_name + ' ' + row.last_name;
}
You can also use a more complicated JavaScript object or array to add the attributes, for example:
if (row.custnum === 1234) {
  row.name_info = {
    'First': row.first_name ,
    'Last' : row.last_name,
    'FullName': row.first_name+ ' ' + row.last_name;
  }
}
In most cases, we recommend that you use non-persistent attributes.
You can also filter out the row, 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
.
Deleting rows/columns is useful in some applications, but we recommend using row/column security.
The tableRow Variable
The
tableRow
variable is the row as read from the database and provides 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 such as 
/MyParent
instead of accessing the subresource directly with a URL such as
/MyParent.MyChild
), then the
parentRow
 variable is defined. It contains the parent row.
Do not alter the content in the 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 is available to all rules and event handlers as the
req
object. This object describes the request being processed.
The
req
 object contains the following values:
  • apiKey
    is the API key used to authenticate the request.
  • baseURL
    is the base URL on which the current call was made.
For more information about the
req
object, see The req Object.
Example of Row Event Usage
 The following example illustrates:
  • Skipping row
  • 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.
    For more information about complex transaction processing, including how to use metadata action tags, see Complex Transaction Processing.
Use a customer resource in the Demo API sample.
Follow these steps:
  1. Open the Demo API.
  2. In the Create section, click
    Resources
    .
    A list of resources display.
  3. Select the
    CustomerBusinessObject
     resource from the list, and then click the 
    Row Event
    tab.
    The row event page appears.
  4. Enter the following code as the row event into the code editor:
    if (row.name === 'Alpha and Sons') {
      // skipping a row 
      row = null;
    }
    else if (row.name === 'Bravo Hardware') {
      // Adding properties to output JSON 
      // Erasing value (property set to null).
      row.foo = 'Hi there!';
      row["2xbalance"] = 2 * tableRow.balance;
      row.credit_limit = null;
    }
    else if (tableRow.name === 'Charlie\'s Construction') {
      // show some love
      row.name = '\u2764 ' + tableRow.name + ' \u2764';
    }
  5. Test this resource row event in the REST Lab by clicking 
    Test
    .
  6. Observe the additional attributes and the
    @metadata
    changes for those affected rows.
For more information about how to test resource row events in the REST Lab, see Test your API Using the REST Lab.