Share via

An Update to Page Update

  • Article

A few months ago we announced the Page Update API beta. Thanks to feedback, we've made a few changes to give you greater precision when making updates to pages. Read on for details.

As before, the PATCH endpoint, /api/beta/pages/{page-id}/content, allows you to add, remove, and update content on a OneNote page.

What's Different

The two major change are the addition of includeIDs, which allows you to precisely target elements on the page and the introduction of the data-id parameter.

 

Everything else about constructing PATCH requests is the same as before – don't worry: if this is new to you, we've got a recap at the end of the post.

 

includeIDs

The OneNote API generates IDs for all elements on a page that can be updated. To get generated IDs, include the query parameter ?includeIDs=true in your request to get page content: GET …/api/beta/pages/{page-id}/content?includeIDs=true

Elements that can be used as a target for updates will include an id attribute:

 

<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>

 

<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />

To target an element via its id property, use the following syntax:

 

"target": "img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}"

 

data-id

Rather than using the id attribute to attach a fixed identifier to elements, you must now use the data-id attribute:

<img id='corgi' src='//placecorgi.com/300'/> should now be <img data-id='corgi' src='//placecorgi.com/300'/>

 

Any element can have a data-id, but to use the 'replace' action, you must use the id attribute generated by includeIDs.

 

Update Objects: Recap

A request to the Page Update API consists of a PATCH request to the /pages/:id/content route. The body of the request should be a JSON array of PATCH actions, e.g.

[{

  "target": "body",

  "action": "append",

  "position": "before",

  "content": "<img src='placecorgi.com/300' id='corgi'/>"

}]

Let's break down that PATCH Action:

  • target: The element the action will target. Valid targets are body, object and img tags with data-id, any element with an id attribute created via includeIDs

    This uses the CSS selector syntax you know and love. For example, you would target an element such as <img data-id='foo' src="…"/> with "target": "#foo"
    Likewise, an element with id would use "target": "img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}"

  • action: The operation that will be carried out on the target. Valid actions are:

    • replace: Excise the element and all children from the HTML DOM, replace it with the content specified in content
    • append: Insert the HTML supplied in content as the last child of target
    • insert: Insert the HTML supplied in content as the following sibling of target

  • content: A string of Well-formed HTML to be inserted into the page as specified by the corresponding action.

  • position: Usable only with insert and append actions.

 

This directive reverses the positioning sense of the append or insert actions.  For append, it switches the insert to place the content as the first child of target.  For insert, it switches the insert to place the content as a preceding sibling of target.

 

A PATCH request must consist of at least one valid PATCH action. Multiple actions can be sent in a single request, like so:

 

[{

   "target": "body",

   "action": "append",

   "position": "before",

   "content": "<img src='placecorgi.com/300' id='corgi'/>"

 },

 {

   "target": "body",

   "action": "append",

   "content": "<p>Text at the bottom of the page</p>"

 }]

 

Go forth and PATCH

That should get you going with the updated Page Update API. We look forward to seeing what you do with it!

- Nick, on behalf of the OneNote API Team

Comments

  • Anonymous
    April 04, 2015
    Generating IDs for each element is great. Thanks. Please show me an example of replacing a data-tag with another? (using element ID)

  • Anonymous
    April 04, 2015
    Hi Ponnuchamy, To replace a data-tag with another I would use the 'replace' in a format kind of like this:

var document = OneNoteAPIClient.getPage(pageId, includeIDs=true)
var toUpdate = document.getElementByDataId(dataIdToReplace)
if(!toUpdate == null) {
 &nbsp;var replaceAction = {
 &nbsp; &nbsp;action: &#39;replace&#39;,
 &nbsp; &nbsp;target: toUpdate[&#39;id&#39;],
 &nbsp; &nbsp;content: toUpdate.merge({&#39;data-tag&#39;: &#39;to-do:complete&#39;})
 &nbsp;}
 &nbsp;OneNoteAPIClient.updatePage(pageId, [replaceAtion])
}

Does that make sense?

  • Anonymous
    May 27, 2015
    Thanks for the post. was so helpful. I would like to ask something else in related to Page-Update . I can update page. I would like to learn, how to embed a PDF without creating a new Page and within a selected Page. In other words, I want to update page with an embedded pdf. With PATCH i get "Bad Request Error". With POST, a new Page within a default section is created. P:S PATCH with JSON, POST with HTML Thanks in advance

  • Anonymous
    May 31, 2015
    Hi Burak. You can add an embedded file with a PATCH request. We put an example request for that here: dev.onenote.com/docs. Please let us know if you have any issues. You can also post on stackoverflow (tagged #onenote). Thanks, Diane