Resource Row Events

Resource Row Events
lac31
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. You can compute data and add new attributes using row events.
In this article:
Create a Resource Row Event
  1. In API Creator, with your API open, in the Create section, click 
    Resources
    .
    A list of resources display.
  2. Complete one of the following:
    • Select an existing resource for which you want to add a row event from the resource list.
    • Create a new resource associated to the row event you want to create by clicking 
      New Resource
      .
  3. Click the 
    Row Event
     tab.
    The resource row event page appears.
  4. Enter JavaScript code in the code editor. You can access and insert JavaScript code examples into the code editor.
    For more information about the variables you can define in JavaScript code, see the "Variables that you can Define in JavaScript Code" section.
Variables that you can Define in JavaScript Code
You can define the following variables in 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 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;
  }
}
In most cases, we recommend using 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.
For more information about row/column security, see Role-Based Endpoint Access.
The tableRow Variable
The
tableRow
variable is the row as read from the database. This variable provides access to the database record after security has been applied and the changes have been 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 
parentRow
variable is defined. It contains the parent row.
Do not alter the content in the parent row. The parent row exists only for reference.
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.
 The
resource
object 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:
The following code snippet shows an example of the resource variable:
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 includes 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
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.
    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.
  1. Open the Demo API.
  2. In the Create section, click
    Resources
    .
    The list of resources defined for this API are displayed.
  3. Click the 
    CustomerBusinessObject
    resource to expand the list.
  4. Click the
    Orders
    resource.
  5. Click the
    Attributes
    tab.
    The resource attributes page appears. The columns for the Orders resource display.
    The following image shows this example in the Demo API:
    The
    Attribute name
    field is the column name alias.
  6. Click the
    Row Event
    tab.
    The resource row event page appears.
  7. Paste in the following code as the row event into the code editor, and then 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 test this resource row event in the REST Lab and observe the additional attributes and the
@metadata
changes.
For more information about the REST Lab, see REST Lab.