context.load

The load() method can be used to load all scalar and complex properties of an object.
You only need to load the items that you need to read and use.
The relationships are not loaded by default
There are actually two different ways you can load your properties.
The following two lines are equivalent, although the last one is the most popular.

context.load(object, properties); 
object.load(properties);

Using Methods

You can return object properties using object methods.
These methods are usually prefixed with "get" and require an intermediate variable.
These always return a new object.
In this snippet you cannot use the following "_workbook.getSelectedRange().load("address");"

var _range = _workbook.getSelectedRange(); 
range.load("address"); // get the date
context.sync();
console.log(range.address); // displaying the data

Using Properties

You can return object properties using object properties.
No intermediate value is required.
In this snippet we do not need an intermediate variable for the 'title' object.

var _chart = _sheet.charts.getItemAt(0); 
_chart.title.load("text");
context.sync();
console.log(_chart.title.text);

Comma Delimited List of Properties

You can specify the properties of an object as a comma delimited string.
You can load multiple properties at one time.

var _range = _worksheet.getRange('A1');  
//The next two lines are equivalent
context.load(_range, "address, values, numberFormat");
_range.load("address, values, numberFormat");

Array of Properties

You can specify the properties of an object as an array

var _range = _worksheet.getRange('A1');  
//The next two lines are equivalent
context.load(_range, ["format/fill", "format/borders", "format/font" ]);
_range.load(["format/fill", "format/borders", "format/font" ]);

Object Containing Properties

You can also specify the properties inside an object.
They are all optional.
select - (object) comma delimited list or array of parameter / relationship names
expand - (object) comma delimited list or array of relationship names
top - (int) specifies the maximum number of collection items that you want included
skip - (int) specifies the number of items in the collection that are to be skipped.


You can load a table in Word

context.load(_table, {expand : 'rows/items/cells/items/body' });  
var _table = context.document.body.tables.getFirstOrNullObject()

Empty Load

If you write a load statement with no property names all the scalar properties will be loaded.
This is called an empty load and should be avoided.

var _range = _worksheet.getRange('A1');  
context.load(_range)
_range.load()

All Properties underneath

//this will get all the properties under format 
var _range = _worksheet.getRange('A1');
context.load(_range, ['format/*'])
_range.load(['format/*']);

Loading Collections

Pass in the names of the 'child' properties.
You must always include the items portion when accessing loaded items as a collection.

var _sheets = context.workbook.worksheets; 
_sheets.load("items/name");
_sheets.load("name"); //these are equivalent
context.sync();

for (var I = 0; I < _sheets.items.length; i++) {
   console.log(sheets.items[i].name;
}

Loading Mutiple Levels

You can load more than one level deep on a collection.

Excel.run( function (context) { 
   workbook.load(worksheets/items/tables/items/columns/items/name");
   workbook.load(worksheets/tables/columns/name"); //these are equivalent
   context.sync();

   var tableColumn = workbook.worksheets.items[1].tables.items[0].columns.items[1];

Loading Mutiple Times

This snippet will copy the fill color from one cell and apply that color to another cell.

var rangeCopy = worksheet.getRange("A1"); 
var rangePaste = worksheet.getRange("A2");
rangeCopy.format.fill.load("color");
context.sync();
rangePaste.format.fill.color = rangeCopy.format.fill.color;

OfficeExtension.ClientResult Exception

This type of object contains exactly one property called "value".
These are usually string values that are very large.
These are represented as methods (preceeded with get) that require additional parameters.
A ClientResult is typically the result of a method call that returns a primitive data type (string, number etc).
For example
(1) on a Word paragraph object, paragraph.getHtml()
(2) on a Word paragraph object, paragraph.getOoxml()
(3) on an Excel chart object, chart.getImage() - that takes desired width, height, fitting mode
For all 3 their return type is string but if you look at their intellisense they are actually listed as ClientResult<string>.
So they are actually objects that wrap a value property that is a string.


Important

The load method will never throw an exception.
If you pass in an invalid property name or a property name that has been mistypes it will just be ignored.


© 2019 Better Solutions Limited. All Rights Reserved. © 2019 Better Solutions Limited TopPrevNext