OneNote: An In-Depth Look at the OneNoteImporter Managed Assembly (Part 1 of 5)
A while back I wrote a series of entries dealing with how you can use Donovan Lange's OneNoteImporter manage class to make importing content into OneNote 2003 SP1 even easier. To recap: Donovan's OneNoteImporter managed class assembly provides an object model interface for the programmability functionality added in OneNote 2003 SP 1. Both the Send to OneNote from Outlook and Send to OneNote from Internet Explorer PowerToy add-ins actually use the OneNoteImporter class in their source code.
You can download the OneNoteImporter class source code from Donovan's blog here.
You can read my initial series of blog entries about the OneNoteImporter class here: part one, and part two.
For the next week or so I'll be running a series of entries that examine the OneNoteImporter class in more detail, and really get 'under the hood' on how the class is structured and functions.
Introduction
The OneNoteImporter managed class assembly provides an object model interface for the programmability functionality added in OneNote 2003 Service Pack (SP) 1.
The classes in this assembly enable you to:
· Import content into OneNote SP1 using the SimpleImport.Import method without having to explicitly author the XML string this method takes as a parameter. The OneNote managed assembly does this for you.
You do not need to be familiar with the SimpleImporter class, or the XML schema used by its Import method, to use the OneNoteImporter managed assembly. However, for more information about the SimpleImporter class and its operation, see Importing Content into Microsoft Office OneNote 2003 SP1.
· Navigate to a specific page in OneNote using the SimpleImport.NavigateTo method.
This is also covered in the article referenced above.
· Use class methods to invoke some of the more popular command line switches you can use to customize how the OneNote application launches.
For more information on customizing OneNote 2003 using command line switches, see Customizing OneNote 2003 SP 1 Using New Command Line Switches.
This article presents a detailed discussion of the internal design and function of the OneNoteImporter classes, in case a developer wants to modify the classes, or just know more about how they operate internally. For a general discussion of how to use the public members of the OneNoteImporter managed assembly, see OneNote Import Managed Assembly: The Quick Rundown (part one and part two).
Source files for the assembly are available from Donovan Lange's blog here. Developers are encouraged to modify the OneNoteImporter assembly as they desire and redistribute it with their application.
Note To avoid compatibility issues with other versions of the assembly that might be loaded on the user’s computer, include the .dll in your application directory, rather than the system directory.
There are several basic steps in using the OneNoteImporter assembly to import content in to OneNote:
· Create the page onto which you want to import content
· Create and add the content to the page
· Import the page into the desired OneNote location
We’ll discuss the internal operation of the assembly classes during each of these steps.
The OneNoteImporter assembly also enables you to update and delete pages or specific content on them, as long as you know their unique identifier. This is discussed in detail later in this article.
It’s worth noting at this point that the OneNoteImporter assembly is designed to import a single OneNote page at a time. The OneNote.SimpleImporter class can take an XML string that includes content to be imported onto multiple pages. However, when using the OneNoteImporter assembly, you create a separate XML string for each page you want to import.
Examining the Classes
Before discussing how the classes in the assembly function internally, let’s briefly look at the abstract classes that form the basis of the assembly. There are four such classes, from which almost all of the other assembly classes derive: ImportNode, PageObject, OutlineContent, and Data.
The ImportNode Class
The ImportNode class is the base class for the entire assembly. Almost all the other classes inherit from it, including the other three abstract classes. As mentioned before, the SimpleImporter.Import method takes an XML string comprised of elements that detail the OneNote page and contents you want to import. The ImportNode represents a single node (or element) in this XML structure, such as a page, or an object on a page.
This class provides several important pieces of common functionality:
· Serialization: The ImportNode contains an abstract method, SerializeToXML, that classes derived from it must implement. This ensures that each derived class contains the means to serialize itself into XML for the XML string passed to the SimpleImport.Import method. We discuss how the various classes implement this method later in the article.
· Selection for importing: This class also contains an internal Boolean property, CommitPending, that denotes whether or not to include this object in the XML string passed to the SimpleImport.Import method. By default, all objects based on the ImportNode or its derived classes have their CommitPending property set to True when they are constructed. This denotes that the object has not yet been imported into OneNote. We also discuss how and when an object’s CommitPending property is changed later in this article.
The PageObject class
The abstract PageObject class represents an object that can be added, updated, or deleted from the specified OneNote notebook page. There are three classes derived from the PageObject class in the assembly:
· ImageObject, which represents an image, such as a jpeg or gif, on a OneNote page
· InkObject, which represents ink on a OneNote page
· OutlineObject, which represents an outline on a OneNote page. OutlineObject objects are actually comprised of other object, such as images, ink, and text described in html format.
The SerializeToXml method is implemented in the PageObject class. It serializes the properties common to all PageObject classes:
· Whether to delete the object
· The object’s unique identifier
· The object’s position on the page
It then calls the abstract PageObject method SerializedObjectToXml. All classes derived from PageObject must implement this method, which serializes the specific attributes of each derived class.
The OutlineContent class
The abstract OutlineContent class represents an object that is part of an outline. There are three classes derived from the OutlineContent class in the assembly:
· HtmlContent, which represents text on a OneNote page, described in html format.
· InkContent, which represent ink that is part of an outline.
· ImageContent, which represent an image that is part of an outline.
The SerializeToXml method is abstract in this class; each class derived from the OutlineContent class must implement the serialization process.
The Data class
The final abstract class, Data, represents the actual data of the object to be imported. For example, for an image, this would be either the path to the image file, or the base 64-encoded data of the image itself. There are three concrete derived classes for the different types of data content an object can represent:
· BinaryData, which represents ink or image data that is base-64 encoded.
· FileData, which represents the path to a source file.
· StringData, which represents HTML content.
The SerializeToXml method is abstract in this class; each class derived from the Data class must implement the serialization process.
In the next entry, we'll look at creating objects.