# JavaScript API

Placing the SheetView component on a Visualforce page globally exposes the `MsmxSheet` JavaScript object in the page. By making an API call from this object, it is possible to dynamically control Sheet's behavior and rendering.

## API Methods <a href="#api-methods" id="api-methods"></a>

### setApplicationParameter(params, options) <a href="#api-setapplicationparameter" id="api-setapplicationparameter"></a>

This API sets the application parameters for the Sheet application. Application parameters can be specified as references when specifying filter values. If the reference for the appropriate parameter is set in the filter, the reference is replaced with the value of the parameter and the sheet display is automatically refreshed.

In the filters for text type or ID type field, and advanced filters, the values of application parameters can be specified as reference and used as filter values. See ["Using Reference Value in Filter"](https://docs.mashmatrix.com/mashmatrix-sheet/functions_about_displaying_data/filter#using-reference-value-in-filter) for more information.

```javascript
// Pass application parameter names and its values in Key-Value pairs
MsmxSheet.setApplicationParameter({
  Name: 'Salesforce',
  Type: ['Partner', 'Customer'] // multiple parameters can be passed in array
});

// Unset "Type" parameter
MsmxSheet.setApplicationParameter({
  Name: 'Salesforce'
}, {
　forceLoad: true // refresh foreground sheet if no parameter changes
});
```

#### Parameters

* **params** - (required) Pass application parameter names and its values in Key-Value pairs.
* **options** - (optional) Option parameters. With the `forceLoad` option property you can force the data refresh

### updateApplicationParameter(params, options) <a href="#api-updateapplicationparameter" id="api-updateapplicationparameter"></a>

Update application parameter values set in the Sheet Application. The difference with `setApplicationParameter` is that it replaces only the value of specified parameters and others will be remained as previous.

```javascript
// First, parameters are all unset.
// => {}

MsmxSheet.updateApplicationParameter({
  Name: 'Mashmatrix'
});
// => { Name: 'Mashmatrix }

MsmxSheet.updateApplicationParameter({
  Type: ['Customer']
});
// => { Name: 'Mashmatrix, Type: ['Customer'] }

// If you want to unset/clear specified parameters, use "undefined".
MsmxSheet.updateApplicationParameter({
  Name: undefined
});
// => { Type: ['Customer'] }
```

#### Parameters

* **params** - (required) Pass application parameter names and its values in Key-Value pairs.
* **options** - (optional) Option parameters. With the `forceLoad` option property you can force the data refresh

### subscribeComponentEvent(compId, path, event, listener) <a href="#api-subscribecomponentevent" id="api-subscribecomponentevent"></a>

Set a listner function to subscribe events fired from the sheet in the component of `msmxSheet:SheetView`.

```
<msmxSheet:SheetView
  id="comp-01"
  bookId="a002800001O6vOpAAJ"
  sheetID="s1"
  width="100%" height="400px"
/>
```

```javascript
// Subscribe record load completion event of the sheet
MsmxSheet.subscribeComponentEvent(
  'comp-01',
  'a002800001O6vOpAAJ/s1',
  'loadComplete',
  function(res) {
    console.log(res.records); // List of records loaded
  }
);

// Subscribe record selection change event of the sheet
MsmxSheet.subscribeComponentEvent(
  'comp-01',
  'a002800001O6vOpAAJ/s1',
  'selectRecords',
  function(res) {
    console.log(res.records); // List of records selected in record selection checkbox
  }
);
```

#### Parameters

* **compId** - (required) Target component ID (specified in id attribute of `msmxSheet:SheetView` component tag)
* **path** - (required) Concatenation of Book ID and Sheet ID with "/"
* **event** - (required) Event name to subscribe
* **listener** - (required) Listener function which will be notified by the event

### unsubscribeComponentEvent(compId, path, event, listener) <a href="#api-unsubscribecomponentevent" id="api-unsubscribecomponentevent"></a>

Unset listener functions to unsubscribe events fired from the sheet in the component of `msmxSheet:SheetView`.

#### Parameters

* **compId** - (required) Target component ID (specified in id attribute of `msmxSheet:SheetView` component tag)
* **path** - (required) Concatenation of Book ID and Sheet ID with "/"
* **event** - (required) Event name to subscribe
* **listener** - (optional) Listener function registered in subscription. If omit this all listeneres for the event will be unsubscribed.

## Event Types <a href="#event-types" id="event-types"></a>

### selectRecords <a href="#event-selectrecords" id="event-selectrecords"></a>

Event which will be notified when the selection of records has changed.

#### Event Parameters

* **records** - List of records selected

### loadComplete <a href="#event-loadcomplete" id="event-loadcomplete"></a>

Event which will be notified when the records are loaded.

#### Event Parameters

* **records** - List of records loaded

### focusCell

Event which will be notified when a cell in the sheet is focused (for example by clicking).

#### Event Parameters

* **cell** - Stores information about the focused cell
  * **recordId** - The ID of the record shown in focused cell
  * **colIndex** - Column index position of the cell
  * **rowIndex** - Row index position of the cell (in all pages)
  * **value** - The raw value of the item displayed in the cell