Scripting

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.

1. 1. 1. event.response

> **Note:** This object is only available/relevant on **post_process** event scripts. The layout/format of the response varies by call.

In `event.response` object contains the data being sent back to the client from 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.

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 DSP 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. The `platform` Object

Access to your DSP's API and scripts are exposed to your server-side scripts via the `platform` object. This object contains methods to facilitate the access and is passed to your scripts as a global.

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 | | `platform.api.merge` | MERGE 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 `/rest/` portion:

``` // Retrieve all contacts from the Contacts database var _records = platform.api.get( "db/Contacts" );

// Uppercase each name... _.each( _records.record, function( record ) { record.name = record.name.toUpperCase(); }); ```

Data returned from external and internal calls will return the results as they are received. No additional processing is provided for this data.

Of course, any changes to the `event.record` or `event.payload` elements will be reflected back to the original client call.

1. 1. 1. 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); ```