OneNote.Section class

Represents a OneNote section. Sections can contain pages.

[ API set: OneNoteApi 1.1 ]

Extends
OfficeExtension.ClientObject

Properties

clientUrl

The client url of the section. Read only

[ API set: OneNoteApi 1.1 ]

id

Gets the ID of the section. Read-only.

[ API set: OneNoteApi 1.1 ]

isEncrypted

True if this section is encrypted with a password. Read only

[ API set: OneNoteApi 1.2 ]

isLocked

True if this section is locked. Read only

[ API set: OneNoteApi 1.2 ]

name

Gets the name of the section. Read-only.

[ API set: OneNoteApi 1.1 ]

notebook

Gets the notebook that contains the section. Read-only.

[ API set: OneNoteApi 1.1 ]

pages

The collection of pages in the section. Read only

[ API set: OneNoteApi 1.1 ]

parentSectionGroup

Gets the section group that contains the section. Throws ItemNotFound if the section is a direct child of the notebook. Read-only.

[ API set: OneNoteApi 1.1 ]

parentSectionGroupOrNull

Gets the section group that contains the section. Returns null if the section is a direct child of the notebook. Read-only.

[ API set: OneNoteApi 1.1 ]

webUrl

The web url of the page. Read only

[ API set: OneNoteApi 1.1 ]

Methods

addPage(title)

Adds a new page to the end of the section.

[ API set: OneNoteApi 1.1 ]

copyToNotebook(destinationNotebook)

Copies this section to specified notebook.

[ API set: OneNoteApi 1.1 ]

copyToSectionGroup(destinationSectionGroup)

Copies this section to specified section group.

[ API set: OneNoteApi 1.1 ]

getRestApiId()

Gets the REST API ID.

[ API set: OneNoteApi 1.1 ]

insertSectionAsSibling(location, title)

Inserts a new section before or after the current section.

[ API set: OneNoteApi 1.1 ]

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

toJSON()
track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you are using this object across ".sync" calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you needed to have added the object to the tracked object collection when the object was first created.

untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You will need to call "context.sync()" before the memory release takes effect.

Property Details

clientUrl

The client url of the section. Read only

[ API set: OneNoteApi 1.1 ]

readonly clientUrl: string;
Property Value
string

id

Gets the ID of the section. Read-only.

[ API set: OneNoteApi 1.1 ]

readonly id: string;
Property Value
string

isEncrypted

True if this section is encrypted with a password. Read only

[ API set: OneNoteApi 1.2 ]

readonly isEncrypted: boolean;
Property Value
boolean

isLocked

True if this section is locked. Read only

[ API set: OneNoteApi 1.2 ]

readonly isLocked: boolean;
Property Value
boolean

name

Gets the name of the section. Read-only.

[ API set: OneNoteApi 1.1 ]

readonly name: string;
Property Value
string

notebook

Gets the notebook that contains the section. Read-only.

[ API set: OneNoteApi 1.1 ]

readonly notebook: OneNote.Notebook;
Property Value

pages

The collection of pages in the section. Read only

[ API set: OneNoteApi 1.1 ]

readonly pages: OneNote.PageCollection;
Property Value

parentSectionGroup

Gets the section group that contains the section. Throws ItemNotFound if the section is a direct child of the notebook. Read-only.

[ API set: OneNoteApi 1.1 ]

readonly parentSectionGroup: OneNote.SectionGroup;
Property Value

parentSectionGroupOrNull

Gets the section group that contains the section. Returns null if the section is a direct child of the notebook. Read-only.

[ API set: OneNoteApi 1.1 ]

readonly parentSectionGroupOrNull: OneNote.SectionGroup;
Property Value

webUrl

The web url of the page. Read only

[ API set: OneNoteApi 1.1 ]

readonly webUrl: string;
Property Value
string

Method Details

addPage(title)

Adds a new page to the end of the section.

[ API set: OneNoteApi 1.1 ]

addPage(title: string): OneNote.Page;
Parameters
title
string

The title of the new page.

Returns

Examples

OneNote.run(function (context) {

    // Queue a command to add a page to the current section.
    var page = context.application.getActiveSection().addPage("Wish list");

    // Queue a command to load the id and title of the new page. 
    // This example loads the new page so it can read its properties later.           
    page.load('id,title');

    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {

            // Display the properties.       
            console.log("Page name: " + page.title);
            console.log("Page ID: " + page.id);

        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

copyToNotebook(destinationNotebook)

Copies this section to specified notebook.

[ API set: OneNoteApi 1.1 ]

copyToNotebook(destinationNotebook: OneNote.Notebook): OneNote.Section;
Parameters
destinationNotebook
OneNote.Notebook

The notebook to copy this section to.

Returns

Examples

OneNote.run(function (context) {
    var app = context.application;

    // Gets the active Notebook.
    var notebook = app.getActiveNotebook();

    // Gets the active Section.
    var section = app.getActiveSection();

    var newSection;

    return context.sync()
        .then(function() {
            newSection = section.copyToNotebook(notebook);
            newSection.load('id');
            return context.sync();
        })
        .then(function() {
            console.log(newSection.id);
        });
})
.catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

copyToSectionGroup(destinationSectionGroup)

Copies this section to specified section group.

[ API set: OneNoteApi 1.1 ]

copyToSectionGroup(destinationSectionGroup: OneNote.SectionGroup): OneNote.Section;
Parameters
destinationSectionGroup
OneNote.SectionGroup

The section group to copy this section to.

Returns

Examples

OneNote.run(function (ctx) {
    var app = ctx.application;

    // Gets the active Notebook.
    var notebook = app.getActiveNotebook();

    // Gets the active Section.
    var section = app.getActiveSection();

    var newSection;

    return ctx.sync()
        .then(function() {
            var firstSectionGroup = notebook.sectionGroups.items[0];
            newSection = section.copyToSectionGroup(firstSectionGroup);
            newSection.load('id');
            return ctx.sync();
        })
        .then(function() {
            console.log(newSection.id);
        });
})
.catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

getRestApiId()

Gets the REST API ID.

[ API set: OneNoteApi 1.1 ]

getRestApiId(): OfficeExtension.ClientResult<string>;
Returns
OfficeExtension.ClientResult<string>

Examples

OneNote.run(function(ctx){
    // Get the current section.         
    var section = ctx.application.getActiveSection();
    var restApiId = section.getRestApiId();

    return ctx.sync().
        then(function(){
            console.log("The REST API ID is " + restApiId.value);
            // Note that the REST API ID isn't all you need to interact with the OneNote REST API. 
            // This is only required for SharePoint notebooks. baseUrl will be null for OneDrive notebooks.
            // For SharePoint notebooks, the notebook baseUrl should be used to talk to the 
            // OneNote REST API according to the OneNote Development Blog.
            // https://blogs.msdn.microsoft.com/onenotedev/2015/06/11/and-sharepoint-makes-three/
        });
});

insertSectionAsSibling(location, title)

Inserts a new section before or after the current section.

[ API set: OneNoteApi 1.1 ]

insertSectionAsSibling(location: OneNote.InsertLocation, title: string): OneNote.Section;
Parameters
location
OneNote.InsertLocation

The location of the new section relative to the current section.

title
string

The name of the new section.

Returns

Examples

OneNote.run(function (context) {

    // Queue a command to insert a section after the current section.
    var section = context.application.getActiveSection().insertSectionAsSibling("After", "New section");

    // Queue a command to load the id and name of the new section. 
    // This example loads the new section so it can read its properties later.           
    section.load('id,name');

    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {

            // Display the properties.       
            console.log("Section name: " + section.name);
            console.log("Section ID: " + section.id);
        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: string | string[]): OneNote.Section;
Parameters
option
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns
Remarks

In addition to this signature, this method has the following signatures:

load(option?: { select?: string; expand?: string; }): OneNote.Section - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): OneNote.Section - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

Examples

OneNote.run(function (context) {

    // Get the current section.
    var section = context.application.getActiveSection();

    // Queue a command to load the section. 
    // For best performance, request specific properties.           
    section.load("id");

    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {
            console.log("Section ID: " + section.id);
        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});
OneNote.run(function (context) {

    // Get the current section.
    var section = context.application.getActiveSection();

    // Queue a command to load the section with the specified properties. 
    section.load("name,notebook/name");

    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {
            console.log("Section name: " + section.name);
            console.log("Parent notebook name: " + section.notebook.name);
        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});
OneNote.run(function (context) {
    // Queue a command to add a page to the current section.
    var section = context.application.getActiveSection();
    section.load('clientUrl,notebook');
    var sectionGroup = section.parentSectionGroupOrNull;

    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {
            if(sectionGroup.isNull === false)
            {
                // If a parent section group exists, queue a command to add a section in it!
                sectionGroup.addSection("NewSectionInSectionGroup");
            }
            return context.sync();
        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

toJSON()

toJSON(): OneNote.Interfaces.SectionData;
Returns

track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you are using this object across ".sync" calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you needed to have added the object to the tracked object collection when the object was first created.

track(): OneNote.Section;
Returns

untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You will need to call "context.sync()" before the memory release takes effect.

untrack(): OneNote.Section;
Returns