Reading and Writing Persistent Data

This article is part five of a series and builds on exercises and concepts presented in parts one through four. If you have not already read the first four parts in this series, set up the Acrobat X Portfolio SDK and successfully built the MyCustomTheme project, please stop reading this article now and go to the Your First Navigator Project article.

Background:

One of the great new benefits of the Acrobat X Portfolio SDK over the Acrobat 9 Portfolio SDK is the ability tostore a small amount of data about the portfolio on the user’s machine outside of the Portfolio itself. This allows you to create user specific areas of the portfolio and still alow the user to send that Portfolio to others without that data going with it. The Acrobat 9 Portfolio SDK did not have this ability. One example of this issue blocking a project was the ESPN Ultimate Tourney Guide, in that project we needed to store a unique user id or GUID so that when a user opened the Portfolio, they’d see their specific March Madness bracket that they had set up on ESPN.com. We wanted this PDF Portfolio to "go viral" so needed a way for users to forward the file to their friends without the GUID going with it. Simply put, this just wasn’t possible with in Acrobat 9, we ended up creating an PDF file that had a variery of SWF files embedded – it wasn’t a PDF Portfolio – still very cool – but not a PDF Portfolio.

Now in Acrobat X, the Portfolio SDK allows you to do exactly what we couldn’t in Acrobat .9 It’s increadibly simple to implement so this is going to be a shorter article that you’ve seen in this series.

SessionData is information stored outside of the PDF Portfolio and is an array of key/value pairs. SessionData is stored on the local hard drive and while abfuscated (a little) text is stored in the clear so you’re should encrypt any strings that contain private information prior to writing them out.

Adding Session Data to a PDF Portfolio Layout

  1. Open the MyCustomTheme project that you completed in the previous article.
  2. Open Main.mxml.
  3. Copy the MXML snippet below and paste it just under components:NavPreview. This will add a TextInput box whose enter action will set the "userName" session data. This is just the first part though.
  4. <s:HGroup top="{header.height}" left="0" verticalAlign="middle
    <s:Label text="Welcome back:"/>
    <s:TextInput id="userName" width="250" enter="collectionManager.host.collection.setSessionData('userName', (userName.text == '') ? null : userName.text)"/ </s:HGroup>
  5. Now that we have a way to set the session data, we need to tell the Portfolio layout to read it back in, if present, when the Portfolio is opened. Add the ActionScript snippet below to the loadingComplete() function in Main.mxml.
  6. collectionManager.host.collection.getSessionData("userName",
    function (key:String, sessionData:*):void
    {
    if (sessionData != null) {
    userName.text = sessionData;
    }
    });
  7. Export your project to a .NAV file and test it in Acrobat. The Preview application does not have the ability to use session data.

Now a few words of warning. The PDF Portfolio session data leverages the Acrobat JavaScript Global Object. Persistent global data only applies to variables of type Boolean, Number, or String. Upon application exit, persistent global variables are stored in the glob.js file located in the user’s folder for folder-level scripts and re-loaded at application start. Only the file that set the session data, having the same path it had when the variable was set, can access the variable. For documents from URLs it means only the host which set it can access the variable. Additionally, there is a hard limit to the amount of data that can be stored for all global variables across all documents. You want to use this functionality very sparingly.