Scripting

Revision as of 18:11, 29 October 2015

1. 1. Support Scripting Languages

 * [V8Js](Scripting/V8Js)
 * [Node.js](Scripting/Nodejs)
 * [PHP](Scripting/PHP)

1. 1. Where Scripts Can Be Used

 * [System Events Scripting](Scripting/Events)
 * [Custom Scripted Services](Scripting/Services)

1. 1. Objects Available

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

1. 1. 1. The Event Object

The `event` object contains the structured data about the event triggered ([Event Scripting](Scripting/Events)) or from the API service call ([Custom Scripting Service](Scripting/Services)).

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

1. 1. 1. 1. Properties

The `event` object has the following properties:

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

In `event.request` you will find 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 | | `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. The layout/format of the response varies by call.

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

1. 1. 1. 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 DSP's REST API | | `platform.config` | object | The current configuration of the DSP | | `platform.session` | object | The current session information |

1. 1. 1. 1. The `platform.api` Object

These methods for DSP access are all contained inside the `platform.api` object. 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.delete` | DELETE a resource | | `platform.api.patch` | PATCH a resource |

They all accept the same arguments:

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

 * `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:

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

or

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

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

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

##### 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

<pre>
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);

<\pre>

> 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.

<pre>
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);
<\pre>

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

<pre>
var options = {
    "CURLOPT_HTTPHEADER": ["Content-type: application/json", "Some-Other-Header: blah"]
};

result = platform.api.get("http://localhost/rest/db/todo", null, options);
<\pre>