SettingCollection Object (JavaScript API for Word)

Word 2016, Word for iPad, Word for Mac, Word Online

Contains the collection of setting objects.

Properties

Property Type Description Req. Set
items Setting A collection of setting objects. Read-only. 1.4

Relationships

None

Methods

Method Return Type Description Req. Set
deleteAll() void Deletes all settings in this add-in. 1.4
getCount() int Gets the count of settings. 1.4
getItem(key: string) Setting Gets a setting object by its key, which is case-sensitive. Throws if the setting does not exist. 1.4
getItemOrNullObject(key: string) Setting Gets a setting object by its key, which is case-sensitive. Returns a null object if the setting does not exist. 1.4
load(param: object) void Fills the proxy object created in JavaScript layer with property and object values specified in the parameter. 1.1
set(key: string, value: object) Setting Creates or sets a setting. 1.4

Method Details

deleteAll()

Deletes all settings in this add-in.

Syntax

settingCollectionObject.deleteAll();

Parameters

None

Returns

void

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Queue commands add a setting.
    var settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });

    // Queue a command to get the count of settings.
    var count = settings.getCount();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        console.log(count.value);

        // Queue a command to delete all settings.
        settings.deleteAll();

        // Queue a command to get the new count of settings.
        count = settings.getCount();
    })

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    .then(context.sync)
    .then(function () {
        console.log(count.value);
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getCount()

Gets the count of settings.

Syntax

settingCollectionObject.getCount();

Parameters

None

Returns

int

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Queue commands add a setting.
    var settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });

    // Queue a command to get the count of settings.
    var count = settings.getCount();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        console.log(count.value);

        // Queue a command to delete all settings.
        settings.deleteAll();

        // Queue a command to get the new count of settings.
        count = settings.getCount();
    })

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    .then(context.sync)
    .then(function () {
        console.log(count.value);
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getItem(key: string)

Gets a setting object by its key, which is case-sensitive. Throws if the setting does not exist.

Syntax

settingCollectionObject.getItem(key);

Parameters

Parameter Type Description  
key string The key that identifies the setting object.  

Returns

Setting

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Queue commands add a setting.
    var settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });

    // Queue a command to retrieve a setting.
    var startMonth = settings.getItem('startMonth');

    // Queue a command to load the setting.
    context.load(startMonth);

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        console.log(JSON.stringify(startMonth.value));
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Queue commands add a setting.
    var settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });
    
    // Queue commands to retrieve settings.
    var startMonth = settings.getItemOrNullObject('startMonth');
    var endMonth = settings.getItemOrNullObject('endMonth');

    // Queue commands to load settings.
    context.load(startMonth);
    context.load(endMonth);

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
       return context.sync().then(function () {
           if (startMonth.isNullObject) {
               console.log("No such setting.");
           }
           else {
               console.log(JSON.stringify(startMonth.value));
           }
            if (endMonth.isNullObject) {
               console.log("No such setting.");
           }
           else {
               console.log(JSON.stringify(endMonth.value));
           }
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getItemOrNullObject(key: string)

Gets a setting object by its key, which is case-sensitive. Returns a null object if the setting does not exist.

Syntax

settingCollectionObject.getItemOrNullObject(key);

Parameters

Parameter Type Description  
key string Required. The key that identifies the setting object.  

Returns

Setting

load(param: object)

Fills the proxy object created in JavaScript layer with property and object values specified in the parameter.

Syntax

object.load(param);

Parameters

Parameter Type Description  
param object Optional. Accepts parameter and relationship names as delimited string or an array. Or, provide loadOption object.  

Returns

void

set(key: string, value: object)

Creates or sets a setting.

Syntax

settingCollectionObject.set(key, value);

Parameters

Parameter Type Description  
key string Required. The setting's key, which is case-sensitive.  
value object Required. The setting's value.  

Returns

Setting