Prerequisite knowledge
 
This article requires that the reader have an understanding of Web Content overlays in DPS. In addition, CSS styling and HTML coding is required to extend or customize the solution.
 
User level:
 
Beginner
 
Required Adobe products
 
Additional required other products
 
 
Sample files

notes-html.zip
 
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
Note: If you have questions about this article, use the comments feature at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 

 
Introduction

One of the many uses of DPS is as a delivery system for training material. When coupled with Direct Entitlement, DPS can be a robust platform for eLearning. In that use case, many customers require that their learners be able to take notes while reading. This article provides a flexible, easy to deploy HTML-based note taking system.
 

 
Note-taking Strategies

At the current time, DPS does not provide a mechanism for persistent data storage. It does permit the use of HTML5 Local Storage, however, but device manufacturers reserve the right to clear that out at any time when device resources become scarce. Nevertheless, the HTML5 localStorage[] array offers a convenient place to store notes. Each note is stored in a key-value pair called localStorage[folioArticlePath()] in the localStorage[]. In addition, another key-value pair called localStorage[folio()+".noteList"] stores the list of all of the keys, so that we have an index of the notes and can keep track of them. So long as the device OS doesn’t clear out the localStorage[] array, our notes will remain in memory, even if we close the folio we are reading, shut down the app or even force quit the app.
 
There are a number of strategies to make note-taking work with DPS, and many resort to brute-force methods that use hard-coding of every overlay to ensure that note storage does not collide with other stored data. The method presented here leverages techniques found in another article on determining Content Context in DPS to ensure conflict-free storage with no hard-coding for variables. In addition, it uses form elements and a button-based control interface to allow the user to reset the current note, reset all notes in the folio, and to email all of the notes as one email message.
 
 
Conflict Resolution
The sample files include four html files and one JavaScript file. Each HTML file represents one note to be used in a Web Content Overlay in any DPS article. On its own, it will automatically determine its context using the functions from the Content Context article. It will use this information to store the note in localStorage[] using the folio name, article name, HTML enclosing folder and the name of the HTML file as keys. This means that you can use the same HTML file in multiple articles, and the notes will not overwrite each other. In addition, since the JavaScript will do automatic context discovery, you do not need to hard code any variables. The only possibility for conflict is if you try to use the same HTML file in the same article more than once. This is common if you have a multi-page article and want to take notes on each page. In that case, make as many copies of the HTML file as you need for one article, and ensure that you use each of the HTML files only once in each article. Using this method, you can re-use each HTML file over and over in different articles in your folio without needing to hard code any variables.
 

 
The Note-taking System in Action

Consider an article with four pages. On each page, you want to allow the reader to take notes. Note placement is a design decision, and customers have chosen to put notes in a scrollable frame, in a slide show, or directly on the page. For this example, we are allowing note taking on a page under an image of a PowerPoint slide, so let’s put the notes directly on the page. Start with a portrait layout and place the PowerPoint slides (saved as a .png or .pdf) onto the top half of each page. Under each slide, draw a box and in the Folio Overlays panel, choose Web Content. Select one of the Notes.x.html files (Notes.1.html for slide one, Notes.2.html for slide two and so on), and set the Overlay to Auto Play and Allow User Interaction. Repeat as many times as necessary for the article, and then preview your article on an iPad. This is critical, as the desktop preview won’t provide the proper responses to the content context JavaScript functions.
 
Figure 1. Web Content Overlay settings for the note Overlay.

Figure 1. Web Content Overlay settings for the note Overlay.

 

So long as you do not re-use any of the HTML files in the same article, you now have an article with separate, persistent notes on each page. The beauty of this system is that you do not need to put anything into the folio or article’s HTMLResources folder in order for it to work. You can re-use the HTML files as many times as you want in as many articles in the same folio as you want, too, so long as you don’t re-use the same HTML file in any given article. Of course, if you want to have shared notes on every page in an article, then go ahead and use the same HTML file over and over in that article. I have provided the note page with a simple form field and basic buttons. In practice, you would likely re-skin the HTML to match your branding. If you do that, then edit Notes.1.html and then copy it as many times as you need it. You do not need to customize all of the note pages, unless there is a specific design requirement.
 
 
What does the note-taking system do, now that it’s in my article?
Figure 2. The “out of the box” note panel on an iPad. Type in the text area, and tap the buttons to email all notes, clear the current note or clear all notes.

Figure 2. The “out of the box” note panel on an iPad. Type in the text area, and tap the buttons to email all notes, clear the current note or clear all notes.

 

Figure 3. Text entry on an iPad

Figure 3. Text entry on an iPad

 

Figure 4. A confirmation dialog pops up when you tap Clear All Notes

Figure 4. A confirmation dialog pops up when you tap Clear All Notes

 

The note-taking system has four basic functions. The first is to allow the reader to type notes onto the form field. This is obvious. Under the hood, though, whenever the form field changes, the record keeping function called addNote() fires. addNote() does two things: it keeps an index of all of the notes in the folio, and it stores the note that has just changed. This uses an entry keyed to the folio to store a list of each note that’s in the folio. This index enables two other functions, sendMail() and clearAllNotes() to work. sendMail() will gather up all of the notes in the folio, attach them to an email message as the message body, and open up Mail on the iPad. clearNote() resets the current note and clears its contents, and clearAllNotes() deletes the contents of all of the notes in the folio.
 
 
What else can this system do?
As delivered, the system consists of the four functions: addNote, sendMail, clearNote, and clearAllNotes(). Feel free to throw away the sample form and make your own. For some projects, we have used editable DIVs rather than form fields. This gives the designers access to rich CSS styling for the note field, and it gives the note taker access to some text formatting options (bold, italic and underline) and lets them paste images into the note field. The drawback is that there is no onChange() event on the DIV to trigger the addNote() function, so you need to use something like onKeyUp(), which is not as responsive.
 

 
Where to go from here

This note-taking system provides a flexible framework that can be used as is or extended to meet multiple business and design requirements. The four basic functions deliver persistence and indexing for multiple notes, insofar as the device will maintain localStorage[] in times of resource constraint. To learn more about using HTML5 and options available for extending this note-taking system, see the HTML5, CSS3 and JavaScript section of the Adobe Developer Connection.
 
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.