Paragraph Object (JavaScript API for OneNote)

Applies to: OneNote Online

A container for the visible content on a page. A Paragraph can contain any one ParagraphType type of content.

To provide feedback on this API, you can file an issue in GitHub.

Properties

Property Type Description
id string Gets the ID of the Paragraph object. Read-only.
type string Gets the type of the Paragraph object. Read-only. Possible values are RichText, Image, Table, Other.

See property access examples.

Relationships

Relationship Type Description
image Image Gets the Image object in the Paragraph. Throws an exception if ParagraphType is not Image. Read-only.
inkWords InkWordCollection Gets the Ink collection in the Paragraph. Throws an exception if ParagraphType is not Ink. Read-only.
outline Outline Gets the Outline object that contains the Paragraph. Read-only.
paragraphs ParagraphCollection The collection of paragraphs under this paragraph. Read-only.
parentParagraph Paragraph Gets the parent paragraph object. Throws an exception if a parent paragraph does not exist. Read-only.
parentParagraphOrNull Paragraph Gets the parent paragraph object. Returns null if a parent paragraph does not exist. Read-only.
parentTableCell TableCell Gets the TableCell object that contains the Paragraph if one exists. If parent is not a TableCell, throws ItemNotFound. Read-only.
parentTableCellOrNull TableCell Gets the TableCell object that contains the Paragraph if one exists. If parent is not a TableCell, returns null. Read-only.
richText RichText Gets the RichText object in the Paragraph. Throws an exception if ParagraphType is not RichText. Read-only.
table Table Gets the Table object in the Paragraph. Throws an exception if ParagraphType is not Table. Read-only.

Methods

Method Return Type Description
delete() void Deletes the paragraph.
insertHtmlAsSibling(insertLocation: string, html: string) void Inserts the specified HTML content.
insertImageAsSibling(insertLocation: string, base64EncodedImage: string, width: double, height: double) Image Inserts the image at the specified insert location.
insertRichTextAsSibling(insertLocation: string, paragraphText: string) RichText Inserts the paragraph text at the specified insert location.
insertTableAsSibling(insertLocation: string, rowCount: number, columnCount: number, values: string[][]) Table Adds a table with the specified number of rows and columns before or after the current paragraph.
load(param: object) void Fills the proxy object created in the JavaScript layer with property and object values specified in the parameter.

Method details

delete()

Deletes the paragraph.

Syntax

paragraphObject.delete();

Parameters

None

Returns

Void

Examples

OneNote.run(function (context) {

    // Get the collection of pageContent items from the page.
    var pageContents = context.application.getActivePage().contents;

    // Get the first PageContent on the page
    // Assuming its an outline, get the outline's paragraphs.
    var pageContent = pageContents.getItemAt(0);
    
    var paragraphs = pageContent.outline.paragraphs;
    
    var firstParagraph = paragraphs.getItemAt(0);
    
    // Queue a command to load the id and type of the first paragraph
    firstParagraph.load("id,type");

    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {
            
            // Queue a command to delete the first paragraph                 
            firstParagraph.delete();
            
            // Run the command to delete it
            return context.sync();
        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});


insertHtmlAsSibling(insertLocation: string, html: string)

Inserts the specified HTML content.

Syntax

paragraphObject.insertHtmlAsSibling(insertLocation, html);

Parameters

Parameter Type Description
insertLocation string The location of new contents relative to the current Paragraph. Possible values are Before, After.
html string An HTML string that describes the visual presentation of the content. See supported HTML for the OneNote add-ins JavaScript API.

Returns

Void

Examples

OneNote.run(function (context) {

    // Get the collection of pageContent items from the page.
    var pageContents = context.application.getActivePage().contents;

    // Get the first PageContent on the page
    // Assuming its an outline, get the outline's paragraphs.
    var pageContent = pageContents.getItemAt(0);
    var paragraphs = pageContent.outline.paragraphs;
    var firstParagraph = paragraphs.getItemAt(0);

    // Queue a command to load the id and type of the first paragraph
    firstParagraph.load("id,type");

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

            // Queue commands to insert before and after the first paragraph
            firstParagraph.insertHtmlAsSibling("Before", "<p>ContentBeforeFirstParagraph</p>");
            firstParagraph.insertHtmlAsSibling("After", "<p>ContentAfterFirstParagraph</p>");
            
            // Run the command to run inserts
            return context.sync();
        });
))
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});


insertImageAsSibling(insertLocation: string, base64EncodedImage: string, width: double, height: double)

Inserts the image at the specified insert location.

Syntax

paragraphObject.insertImageAsSibling(insertLocation, base64EncodedImage, width, height);

Parameters

Parameter Type Description
insertLocation string The location of the table relative to the current Paragraph. Possible values are Before, After.
base64EncodedImage string HTML string to append.
width double Optional. Width in the unit of Points. The default value is null, and image width will be respected.
height double Optional. Height in the unit of Points. The default value is null, and image height will be respected.

Returns

Image

Examples

OneNote.run(function (context) {

    // Get the collection of pageContent items from the page.
    var pageContents = context.application.getActivePage().contents;

    // Get the first PageContent on the page
    // Assuming its an outline, get the outline's paragraphs.
    var pageContent = pageContents.getItemAt(0);
    var paragraphs = pageContent.outline.paragraphs;
    var firstParagraph = paragraphs.getItemAt(0);

    // Queue a command to load the id and type of the first paragraph
    firstParagraph.load("id,type");

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

            // Queue commands to insert before and after the first paragraph
            firstParagraph.insertImageAsSibling("Before", "R0lGODlhDwAPAKECAAAAzMzM/////wAAACwAAAAADwAPAAACIISPeQHsrZ5ModrLlN48CXF8m2iQ3YmmKqVlRtW4MLwWACH+H09wdGltaXplZCBieSBVbGVhZCBTbWFydFNhdmVyIQAAOw==");
            firstParagraph.insertImageAsSibling("After", "R0lGODlhDwAPAKECAAAAzMzM/////wAAACwAAAAADwAPAAACIISPeQHsrZ5ModrLlN48CXF8m2iQ3YmmKqVlRtW4MLwWACH+H09wdGltaXplZCBieSBVbGVhZCBTbWFydFNhdmVyIQAAOw==");
            
            // Run the command to insert images
            return context.sync();
        });
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});


insertRichTextAsSibling(insertLocation: string, paragraphText: string)

Inserts the paragraph text at the specified insert location.

Syntax

paragraphObject.insertRichTextAsSibling(insertLocation, paragraphText);

Parameters

Parameter Type Description
insertLocation string The location of the table relative to the current Paragraph. Possible values are Before, After.
paragraphText string HTML string to append.

Returns

RichText

Examples

OneNote.run(function (context) {

    // Get the collection of pageContent items from the page.
    var pageContents = context.application.getActivePage().contents;

    // Get the first PageContent on the page
    // Assuming its an outline, get the outline's paragraphs.
    var pageContent = pageContents.getItemAt(0);
    var paragraphs = pageContent.outline.paragraphs;
    var firstParagraph = paragraphs.getItemAt(0);

    // Queue a command to load the id and type of the first paragraph
    firstParagraph.load("id,type");

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

            // Queue commands to insert before and after the first paragraph
            firstParagraph.insertRichTextAsSibling("Before", "Text Appears Before Paragraph");
            firstParagraph.insertRichTextAsSibling("After", "Text Appears After Paragraph");
            
            // Run the command to insert text contents
            return context.sync();
        });
})  
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
}); 


insertTableAsSibling(insertLocation: string, rowCount: number, columnCount: number, values: string[][])

Adds a table with the specified number of rows and columns before or after the current paragraph.

Syntax

paragraphObject.insertTableAsSibling(insertLocation, rowCount, columnCount, values);

Parameters

Parameter Type Description
insertLocation string The location of the table relative to the current Paragraph. Possible values are Before, After.
rowCount number The number of rows in the table.
columnCount number The number of columns in the table.
values string[][] Optional. Optional 2D array. Cells are filled if the corresponding strings are specified in the array.

Returns

Table


load(param: object)

Fills the proxy object created in the 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 a delimited string or an array. Or, provide loadOption object.

Returns

Void


Property access examples

id and type

OneNote.run(function (context) {

    // Get the collection of pageContent items from the page.
    var pageContents = context.application.getActivePage().contents;
    
    // Queue a command to load the outline property of each pageContent.
    pageContents.load("outline");
        
    // Get the first PageContent on the page, and then get its Outline.
    var pageContent = pageContents._GetItem(0);
    var paragraphs = pageContent.outline.paragraphs;
            
    // Queue a command to load the id and type of each paragraph.
    paragraphs.load("id,type");
            
    // Run the queued commands, and return a promise to indicate task completion.
    return context.sync()
        .then(function () {
            
            // Write the text.                  
            $.each(paragraphs.items, function(index, paragraph) {
                console.log("Paragraph type: " + paragraph.type);
                console.log("Paragraph ID: " + paragraph.id);
            });
        });
})      
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
}); 


paragraphs

OneNote.run(function(context) {
    var app = context.application;
    
    // Gets the active outline
    var outline = app.getActiveOutline();
    
    // load nested paragraphs and their types.
    outline.load("paragraphs/type");
    
    return context.sync().then(function () {
        var paragraphs = outline.paragraphs.items;
        
        var promise;
        // for each nested paragraphs, load tables only
        for (var i = 0; i < paragraphs.length; i++) {
            var paragraph = paragraphs[i];
            if (paragraph.type == "Table") {
                paragraph.load("table/id");
                promise =  context.sync().then(function() {
                    console.log(paragraph.table.id);
                });
            }
        }
        return promise;
    })
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});


n of pageContent items from the page. var pageContents = context.application.getActivePage().contents; // Queue a command to load the outline property of each pageContent. pageContents.load("outline"); // Get the first PageContent on the page, and then get its Outline. var pageContent = pageContents._GetItem(0); var paragraphs = pageContent.outline.paragraphs; // Queue a command to load the id and type of each paragraph. paragraphs.load("id,type"); // Run the queued commands, and return a promise to indicate task completion. return context.sync() .then(function () { // Write the text. $.each(paragraphs.items, function(index, paragraph) { console.log("Paragraph type: " + paragraph.type); console.log("Paragraph ID: " + paragraph.id); }); }); }) .catch(function(error) { console.log("Error: " + error); if (error instanceof OfficeExtension.Error) { console.log("Debug info: " + JSON.stringify(error.debugInfo)); } });

paragraphs

OneNote.run(function(context) {
    var app = context.application;
    
    // Gets the active outline
    var outline = app.getActiveOutline();
    
    // load nested paragraphs and their types.
    outline.load("paragraphs/type");
    
    return context.sync().then(function () {
        var paragraphs = outline.paragraphs.items;
        
        var promise;
        // for each nested paragraphs, load tables only
        for (var i = 0; i < paragraphs.length; i++) {
            var paragraph = paragraphs[i];
            if (paragraph.type == "Table") {
                paragraph.load("table/id");
                promise =  context.sync().then(function() {
                    console.log(paragraph.table.id);
                });
            }
        }
        return promise;
    })
})
.catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});
v>