# Vendor Javascript

## Directory Location

```
sample-integration/
├── vendor/
|    └── google.js
```

## Summary

Vendor files are javascript files that are loaded alongside your integration. They can be used to inject third-party javascript libraries such as the google maps API.

You can specify vendor files by including them in the [`javascript` property of the configuration](https://docs.polarity.io/integrations/configuration-file#javascript).

When an integration is first started or reloaded, any javascript files specified by the `javascript` property in your config will be executed. This gives you an opportunity to load third party scripts.

## onSettingsChange(callback)

**optional |** *function*

| Parameter | Description                                                               |
| --------- | ------------------------------------------------------------------------- |
| callback  | Function to be called when the user updates settings for the integration. |

You can register a callback to the `onSettingsChange` event by passing a callback to the `onSettingsChange` method. This callback will be invoked anytime the user updates settings for the integration. The callback function being invoked will be passed three parameters.

### callback(integration, userConfig, userOptions)

**required |** *function*

| Parameter   | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| integration | the integration object passed into the `init` function                                    |
| userConfig  | a user configuration object which contains settings information for the integration       |
| userOptions | a user options object which contains the user's current option values for the integration |

#### integration

The `integration` variable contains all information about the integration including `userOptions` and `userConfig`.

```javascript
// Sample integrations object
{
    "type": "wikipedia",
    "name": "",
    "onChangeCallbacks": [],
    "config": {
        "name": "Wikipedia",
        "acronym": "Wiki",
        "title": "Wikipedia",
        "block": {
            "component": {
                "file": "./components/block.js",
                "content": ""
            },
            "template": {
                "file": "./template/block.hbs",
                "content": "",
                "compiled": ""
            }
        },
        "main": "./integration.js",
        "description": "Lookup pages in Wikipedia to find contextual information in summaries.",
        "version": "0.0.2",
        "private": true,
        "dependencies": {
            "request": "^2.75",
            "lodash": "^4.16",
            "async": "^2.0",
            "unirest": "^0.5.0"
        },
        "javascript": []
    },
    "userConfig": {},
    "userOptions": {},
    "uniqueId": 1486176346806,
    "summaryComponentName": "integrations/default-summary",
    "blockComponentName": "integrations/wikipedia-1486176346806-block"
}
```

#### userConfig

The `userConfig` object contains information about the integration such as whether or not the user is subscribed, the color chosen by the user, and cache options for this integration.

{% code title="" %}

```javascript
// Sample userConfig object
{
  "name":"Wikipedia",
  "acronym":"Wiki",
  "color":"rgb(200,200,200)",
  "status":"running",
  "starts":1,
  "subscribed":false,
  "path":"/app/polarity-server/integrations/wikipedia",
  "description":"Lookup pages in Wikipedia to find contextual information in summaries.",
  "cacheTtl":300,
  "cacheIsEnabled":true,
  "cacheIsPerUser":true,
  "cacheExpirationCron":null,
  "cacheCompressionEnabled":true,
  "cacheLookupMisses":true,
  "cacheStatus":"OK",
  "messagesReceived":3,
  "messagesSent":0,
  "integrationMetrics":"wikipedia"
}
```

{% endcode %}

#### userOptions

Contains the option values for the current user. For example, if you have an integration option called `apiKey` you could pass this `apiKey` to another API.  

```javascript
// Sample userOptions Object
{
  "apiKey": "klsjadio1j23oij3412oij4",
  "username": "ed",
  "lookupHashes": true
}
```

{% hint style="warning" %}
Options that are set to `admin-only` will not show up in the `userOptions` object as the user does not have access to these values on the client.
{% endhint %}

### Example

The following code provides an example of how you would setup your `vendor.js` file to take advantage of the `onSettingsChange` callback.

{% code title="vendor.js" %}

```javascript
'use strict';

function init(integration, userConfig, userOptions){
    // load some files here
}

// This will be called when integration settings are changed
// including the first time the integration is loaded
onSettingsChange(init);
```

{% endcode %}

If you want to run some javascript and ensure it runs only once, you can add a flag to indicate that the code has already run and then check the flag before running your code.

{% code title="vendor.js" %}

```javascript
'use strict';

let hasRun = false;

function init(integration, userConfig, userOptions){
    hasRun = true;
    if(hasRun === false){
       // do something here and it will only run one time    
    }
}

// This will be called when integration settings are changed
// including the first time the integration is loaded
onSettingsChange(init);
```

{% endcode %}