Binding


Selecting a range from the prompt will bind to that range */
Bind to the matrix in the document from prompt

Office.context.document.bindings.addFromPromptAsync(Office.BindingType.Matrix, 
                                                   { id: "MyMatrixBinding" },
                                                   function (asyncResult) {
if (asyncResult.status == "failed") {
showMessage("Action failed with error: " + asyncResult.error.message);
}
else {
showMessage("Added new binding with type: " + asyncResult.value.type +
      " and id: " + asyncResult.value.id);
}
});

The next step is to bind to the range (matrix). Binding to a region in a document establishes a link between that region and the app that can be referenced later on. After a Binding object is created, you can retrieve it at any time, read and write data to the region of the document associated with it, and handle selection and data change events. This example demonstrates binding by displaying a prompt using the addFromPromptAsync method, which prompts the user to make a selection in the document and binds to that selection. Be aware that bindings can also be created based on current user selection (without displaying a prompt) and from existing named items in the document or spreadsheet. The example also shows how a binding ID can be specified when you create the binding. The binding ID, 'MyMatrixBinding', can then be used to retrieve the binding. The callback function returns an asyncResult object containing the binding object, which can be accessed by using the asyncResult.value property.



Click Run Code to add an event handler to the Matrix binding.
Then select different cells in the Matrix to trigger the event and read the current selected cell.
Get the binding and add an event handler to detect selection change events

Office.select("bindings#MyMatrixBinding", onBindingNotFound). 
  addHandlerAsync(Office.EventType.BindingSelectionChanged,
                  onBindingSelectionChanged,
                  function(AsyncResult){
showMessage("Event handler was added successfully!"+
    " Change the matrix current selection to trigger the event");
});

//Trigger on selection change, get partial data from the matrix
function onBindingSelectionChanged(eventArgs) {
  eventArgs.binding.getDataAsync({CoercionType: "matrix",
                                  startRow:eventArgs.startRow,
                                  startColumn:eventArgs.startColumn,
                                  rowCount:1, columnCount:1},
                                  function(asyncResult) {
      if (asyncResult.status == "failed") {
        showMessage("Action failed with error: " + asyncResult.error.message);
      }
      else{
        showMessage(asyncResult.value[0].toString());
      }
  });
}

//Show error message in case the binding object wasn"t found
function onBindingNotFound(){
showMessage("The binding object was not found."+
  " Please return to previous step to create the binding");
}

After binding to the matrix, the next step is to detect when a user changes selection in that range and then read the selected cell coordinates. This can be done by adding an event handler function to the binding to detect selection change events. Once the event is triggered, the event handler function, onBindingSelectionChanged(), is called and gets data from the binding using the Binding.getDataAsync method. By default, the getDataAsync method returns all the data contained in a text, matrix, or table binding. However, it is possible to get a partial set of the data by specifying the startRow, startColumn, rowCount and columnCount parameters of the method. The data is then returned by the asyncResult object and can be accessed through the value property.





© 2017 Better Solutions Limited. All Rights Reserved. © 2017 Better Solutions Limited

PrevNext