Scripting

Revision as of 15:54, 2 February 2016

Supported Scripting Languages

• V8Js
• NodeJs
• PHP

Where Scripts Can Be Used

• System Events Scripting
• Custom Scripted Services

Objects Available

DreamFactory passes in two additional objects for use in the scripts.

The Event Object

The event object contains the structured data about the event triggered (System Events Scripting) or from the API service call (Custom Scripted Services).

> Of all the variables provided to your script, only this event container object is writable.

Properties

The event object has the following properties:

|Property|Type|Description| |--------|-----------|----| | `event.request` | object | An object representing the inbound REST API call, i.e. the HTTP request. | | `event.response` | object | An object containing the response to an inbound REST API call, i.e. the HTTP response. | | `event.resource` | string | Any additional resource names typically represented as a replaceable part of the path, i.e. table name on a db/_table/{table_name} call. |

The `event.request` object contains all the components of the original HTTP request.

|Property|Type|Description| |--------|-----------|----| | `api_version` | string | The API version used for the request (i.e. 2.0). | | `method` | string | The HTTP method of the request (i.e. GET, POST, PUT). | | `parameters` | object | An array of query string parameters received with the request. | | `headers` | object | The HTTP headers from the request. | | `payload` | object | The body (POST body) of the request converted to an object, i.e. the `content` below presented as internally useable object. | | `content` | string | The body of the request in raw string format. | | `content_type` | string | The format type (i.e. json) of the raw `content` of the request. |

Any changes to this data will overwrite existing data in the response, before further listeners are called and/or the request completes.

In `event.response` object contains the data being sent back to the client from the request. > Note: This object is only available/relevant on post_process event scripts, and Custom Scripting service scripts.

|Property|Type|Description| |--------|-----------|----| | `api_version` | string | The API version used for the request (i.e. 2.0). | | `status_code` | integer | The HTTP status code of the response (i.e. 200, 404, 500, etc). | | `headers` | object | The HTTP headers from the request. | | `content` | mixed | The body of the request as an object if the `content_type` is not set, or in raw string format. | | `content_type` | string | The content type (i.e. json) of the raw `content` of the request. |

Just like `event.request`, any changes to `event.response` will overwrite existing data in the response, before it is sent back to the client.

The Platform Object

> Note: The `platform` object is only available in V8Js scripts currently.

This platform object may be used to access the REST API of your instance via inline calls. This make service requests directly without requiring an HTTP call. The platform object has the following properties:

| Field | Type | Description | |-------|------|-------------| | `platform.api` | object | An object that allows access to the instance's REST API | | `platform.config` | object | The current configuration of the instance | | `platform.session` | object | The current session information |

These `platform.api` object contains methods for instance API access. This object contains a method for each type of REST verb.

| Function | Description | |----------|-------------| | `platform.api.get` | GET a resource | | `platform.api.post` | POST a resource | | `platform.api.put` | PUT a resource | | `platform.api.patch` | PATCH a resource | | `platform.api.delete` | DELETE a resource |

They all accept the same arguments:

platform.api.get( "service[/resource[/resource_id]]"[, payload] );

* `service` is always required.
* `resource` and `resource_id` are optional and depend on your call.
* `payload` is optional, but must contain a valid object for the language of the script. 

You may also pass absolute URLs to these methods to retrieve external resources:

var _page = platform.api.get( "http://www.google.com" );

or

var _result = platform.api.get( "https://www.example.com/api/something_cool", {"cool":"very"} );

Calling internally however only requires the relative URL sans the `/api/v2/` portion:

// Retrieve all records from the 'Contacts' table in the 'db' database service
var _records = platform.api.get( "db/_table/Contacts" );

Adding headers or other cURL options to platform.api calls

You can include an optional third argument to add cURL options to the request. For example to add headers

var options = {
    "CURLOPT_HTTPHEADER": ["Content-type: application/json", "Some-Other-Header: blah"]
};
 
result = platform.api.post("http://localhost/rest/db/todo", JSON.stringify({"name":"test"}), options);

> Please note the double quotation marks around the `CURLOPT_*` constant names. Unlike PHP, this is required in Javascript.

You can also add multiple cURL options like this.

var options = {
    "CURLOPT_HTTPHEADER": ["Content-type: application/json", "Some-Other-Header: blah"],
    "CURLOPT_SOMEOTHEROPTION": "someothervalue"
};
 
result = platform.api.post("http://localhost/rest/db/todo", JSON.stringify({"name":"test"}), options);

For GET you can set the second argument, payload, to null to include the optional third argument for the cURL options.

var options = {
    "CURLOPT_HTTPHEADER": ["Content-type: application/json", "Some-Other-Header: blah"]
};
 
result = platform.api.get("http://localhost/rest/db/todo", null, options);