Prerequisite knowledge
 
  • This article requires that the readers have an understanding of Web Content overlays in DPS. In addition, CSS styling and HTML coding are required to extend or customize the solution.
User level: All
 
Required Adobe products (retail)
 
Additional required other products (third-party/labs/open source)
 
Sample files
 
By downloading software from the Adobe website you agree to the terms of our license agreement. Please read it before downloading.
 

 

Note: If you have questions about this article, use the DPS forum. Please don’t contact technical support with questions about Adobe Developer Connection articles.

 


 
Introduction

The ability to take notes in a folio is an important requirement for many educational and corporate use cases. Customers have implemented many different solutions, two of which are already documented on the DPS Developer Center: Derek Lu’sAdd note-taking functionality to a folio” article and this author’s “A Flexible Note-taking System for use in DPS Folios” article. This new system seeks to further simplify note-taking overlays by extending the functions documented in “A Flexible Note-taking System for use in DPS Folios” to include the folioDataService methods available with the DPS Reading SDK. folioDataServce provides access to the current page number as well as other metadata about the folio and its articles.
 
In addition, this new note-taking system consists of a single HTML file with supporting JavaScript, CSS and assets that can be used on a master page in InDesign to provide note-taking for every page in every article in a folio, with no configuration and no custom coding.
 
(If you have my DPS Examples app installed on your iPad, and you're reading this blog on your iPad, then tap here to see an example of a notes overlay in my DPS Examples app.)    
 

 
Improved Reader Context

In this author’s earlier note-taking example, we used the Content Context JavaScript functions to determine the folio, article and HTML file that was currently being displayed to the reader. At the time when that article was written, there was no way to programmatically determine the current page that was currently being displayed. DPS Release 30 introduced a new set of methods called the folioDataService, which gives Web Overlays access to much more information about the folio while it’s being read.
 
folioDataService has several methods that can be used to determine folio and article metadata as well as the current reading position. You can learn more and see a detailed example at Derek Lu’s article about the R30 APIs. Brian Hinkelman uses these same APIs for his “Customizing DPS Navigation with the Reading API” article. Both of these provide detailed instructions and example code showing how to use the R30 Reading SDK.
 
The new note-taking overlay uses folioDataService to gather the following information about the current reader’s context and uses it in the note-taking system:
 
  • Current folio title (which appears in the Library)
  • Current article title (which appears in the Table of Contents)
  • Current page of the current article
These three items along with the existing Content Context JavaScript comprise the indexing components of the new overlay. Since we can now programmatically determine which page any given occurrence of the overlay is on, we can use that information to index our notes. Access to the the page number as well as the folio, article, and HTML file to index our notes, allows us to use one HTML file as the common overlay for all notes within a folio.
 
The overlay consists of the following components:
 
  • index.html: the html file that renders the overlay
  • styles.css: the CSS that styles the overlay
  • notes.js: the JavaScript that comprises the note-taking functionality
  • AdobeReadingAPI.min.js: the DPS Reading API libraries
  • images folder: contains the two states of the note icon in the overlay (add.png and edit.png)
A common strategy is to place the note-taking overlay on a Master page in InDesign. The Web Content Overlay that will display the note-taking system needs to be at the top of all other content, so it is best to create a layer called “notes” at the top of the layer stack in your InDesign document and to place the overlay on this layer. It is best to make the Web Content Overlay fill the entire screen, as it contains a semitransparent background that will cover the page content when it is active. The overlay needs to be set to AutoPlay with 0 or .125 sec delay; it needs to be transparent; it needs to allow user interaction; and it needs access to Entitlement Information. This last requirement is critical, because without access to Entitlement information, folioDataService will not work.
 
Figure 1. In this example, the note-taking system has been placed on a Master Page. It completely fills the page, and it will appear on all pages that use this Master Page.

Figure 1. In this example, the note-taking system has been placed on a Master Page. It completely fills the page, and it will appear on all pages that use this Master Page.

 

Once you have created your overlay, you can lock the “notes” layer. In order to display the note-taking overlay in your layout, simply apply this master page to any page of your article on which you want to allow readers to take notes.
 

 
Using the note-taking system

To use the note-taking system, all a reader needs to do is to tap the icon in the lower right hand corner of the screen, and the note-taking interface will appear. The icon will change depending on whether there is a note stored for the current page. If there is no note, then the icon has a green “plus” sign on it, and if there is a note, then it has a yellow pencil on it. The icon is semitransparent, and since it is just a .png, you can adjust the icon to meet your style and branding requirements.
 
Figure 2. The overlay appears as an icon in the lower right hand corner of the page. Its appearance depends on whether there is a note on the page. In this instance, there is no note on the page.

Figure 2. The overlay appears as an icon in the lower right hand corner of the page. Its appearance depends on whether there is a note on the page. In this instance, there is no note on the page.

 

Figure 3. In this instance, there is a note on the page, so the icon changes to include a pencil.

Figure 3. In this instance, there is a note on the page, so the icon changes to include a pencil.

 

The note overlay itself consists of a text entry area and five controls. In the upper right hand corner of the overlay is the close box. Along the bottom of the overlay are four actions: Email all of the notes; Email this note; Delete this note; Delete all notes. Tapping on either of the Email buttons will format an email message and send it to the Mail app on the tablet. While the overlay works well on iOS, you will likely need to adjust the message format for Android and Windows to accommodate their mail applications.
 
Figure 4. When the reader taps the icon, the note overlay appears. The controls are self-explanatory.

Figure 4. When the reader taps the icon, the note overlay appears. The controls are self-explanatory.

 

The email message now reports the following information:
 
  • The Folio Title of the folio to which the notes refer
  • The Article Title (if available) of the article to which the notes refer
  • The page number of the article
  • The note content
Figure 5. Format of a single note when the user taps the “Email This Note” button

Figure 5. Format of a single note when the user taps the “Email This Note” button

 

If the user emails all the notes, then the notes are listed with page number and article detail as well as the folio title for reference.
 
Figure 6. Format of the notes list when the user taps the “Email All Notes” button

Figure 6. Format of the notes list when the user taps the “Email All Notes” button

 

The other two buttons delete either the current note or all of the notes, respectively. The user will see a dialog asking for confirmation, so they will have a chance to decline if they tap the button by mistake.
 

 
Where to go from here

While this system offers an easy to manage note-taking solution for many use cases, it is likely that customers will want to extend the content of the notes to include other functions and a more customized experience for the reader. With CSS treatment, it is possible to brand the sample code to match most requirements. One interesting possibility is to include snapshots of the pages in which the notes appear. At the present time, there is no way to pass an image or any other attachment to the mail application, so it will be necessary to provide an online service to host the page images and then link to them in the body of the email message. If a regular naming convention is followed, then it is easy to determine the file name of the appropriate image, since the system knows the folio, article and page number for each note.
 

Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.