Create pages with absolutely positioned elements with the OneNote API

Learn how to create a OneNote page that contains multiple div, img, and object elements that can be positioned independently.

Last modified: January 22, 2016

Applies to: OneNote service

In this article
Create a page that has multiple absolutely positioned elements
Supported CSS style attributes
Permission scope
Response information

Note Note

See this topic on our new documentation site for consumer and enterprise OneNote APIs.

The body of a OneNote page can contain multiple direct child elements of type div, img, or object. These child elements can be positioned independently anywhere on the page.

To create a page with multiple absolutely positioned elements by using the OneNote API, the body element in the input HTML must specify data-absolute-enabled="true".

Any div, img, or object elements that you want to render as absolutely positioned elements must be direct children of the body element, and they must specify style="position:absolute".

The following example creates a page that contains one absolutely positioned div and one absolutely positioned image.

HTML
Copy 
<html>
    <head>
        <title>Page Title</title>
    </head>
    <body data-absolute-enabled="true">
        <div style="position:absolute;width:280px;top:120px;left:68px">
            <p>Some text</p>
            <img style="width:120px" src="http://officeimg.vo.msecnd.net/en-us/files/018/949/ZA103278226.png" />
            <div>
                <p>More text inside a regular, nested div</p>
            </div>
        </div>
        <img style="position:absolute;width:360px;top:350px;left:300px" src="http://officeimg.vo.msecnd.net/en-us/files/018/949/ZA103278226.png" />
    </body>
</html>

The OneNote API evaluates the input HTML and preserves all semantic content and any structural information that is supported by OneNote. The resulting page renders as shown in the following image (but without the visible borders for the div and image). Notice the changes to the non-contributing, nested div from the input HTML. The API preserves the div's content but discards the <div> tags because the div doesn't define semantic information (such as data-id).

Multi-outline page with floating elements

Input HTML requirements and positioning behavior for absolutely positioned elements

  • The body element must specify data-absolute-enabled="true". If omitted or set to false, all body content is rendered inside a _default absolutely positioned div that the API creates, and all position settings are ignored.

  • Only div, img, and object elements can be absolutely positioned elements. Absolutely positioned images can use the data-render-src or src attribute.

  • Absolutely positioned elements must specify style="position:absolute".

  • Absolutely positioned elements must be direct children of the body element. Any direct children of the body that aren't absolutely positioned div, img, or object elements are rendered as static content inside the absolutely positioned _default div, as shown in the following examples.

    Input HTML with a direct p child, an absolutely positioned div, and a non-absolutely positioned div.

    Copy 
    <body data-absolute-enabled="true">
    <p>This content appears in the _default div.</p>
    <div style="position:absolute;top:175px;left:100px" data-id="div1">
      <p>This content appears in an absolutely positioned div.</p>
    </div>
    <div>
        <p>This content also appears in the _default div.</p>
    </div>
</body>

    Output HTML with the non-absolutely positioned div rendered in the default div. The original <div> tags are discarded because they do not define any semantic information (such as data-id).

    Copy 
    <body data-absolute-enabled="true" style="font-family:Calibri;font-size:11pt">
    <div data-id="_default" style="position:absolute;left:48px;top:120px;width:624px">
        <p>This content appears in the _default div.</p>
        <p>This content also appears in the _default div.</p>
    </div>
    <div data-id="div1" style="position:absolute;left:99px;top:174px;width:624px">
        <p>This content appears in an absolutely positioned div.</p>
    </div>
</body>

  • Absolutely positioned elements are positioned at their specified top and left coordinates, relative to the 0:0 starting position at the absolute top, left corner of the page (above the title area).

  • If an absolutely positioned element omits the top or left coordinate, the missing coordinate is set to its default value: top:120px or left:48px. These default coordinates specify a position just below the title area. Be aware that omitting coordinates can result in elements that are stacked on top of each other.

  • Absolutely positioned elements cannot be nested or contain positioned elements. The API ignores any position settings specified on nested elements inside an absolutely positioned div, renders the nested content inside the absolutely positioned parent div, and returns a warning in the api.diagnostics property in the response.

For more information about how the OneNote API handles input and output HTML, see Input and output HTML for OneNote pages.

All absolutely positioned elements can specify top and left positions. Divs and images can specify width, and images can also specify height. For example:

    <img style="position:absolute;top:140px;left:95px;width:480px;height:665px" src="..." />

Supported attribute

Description

top

The y-axis coordinate of the div, img, or object element's top border, in pixels only. Default is 120 pixels.

Example: top:140px

left

The x-axis coordinate of the div, img, or object element's left border, in pixels only. Default is 48 pixels.

Example: left:95px

width

The width of the div or img element, in pixels only.

Example: width:480px

height

The height of the img element, in pixels only. For div elements, height is calculated at runtime and any specified height value is ignored.

Example: height:665px

Other position attributes, such as z-index, are ignored.

To create page content, you’ll need to pass the following permission level when you authenticate the user:

  • office.onenote_create

See OneNote permission scopes for more information about how permission scopes work.

The OneNote API returns the following information in the response.

Response values

Description

Success code

If the create request is successful, the OneNote API returns a 201 HTTP status code.

Page object

If the request succeeds, the API returns page metadata in the response body. Page metadata includes the page ID, the link to get the page's HTML content, and a links object that contains links to open the page in the native and online OneNote clients.

Warnings

You'll receive a warning in the api.diagnostics property of the response for any of the following conditions:

20146
The style="position:absolute" attribute is specified on an element, but the body element does not specify data-absolute-enabled="true", which is required to support positioning. All position settings are ignored.

20147
The style="position:absolute" attribute is specified on an element that is not a direct child of the body element, which is not supported. If the element is a div, img, or object, make it a direct child of the body; otherwise the position settings will be ignored and its content will render inside an absolutely positioned div.

20148
The style="position:absolute" attribute is specified on an element type that does not support it. Only div, img, and object elements support positioning.

X-CorrelationId

An X-header with a GUID that uniquely identifies the request. You can use this value along with the value of the Date header to troubleshoot problems with Microsoft support.
Show: