Implementing separate library and store functionality using custom slot templates with new DPS APIs

This article provides two templates that enable you to implement two separate custom tabs in the viewer using version 2 of the library and store API. One tab functions as a library and only displays folios that a user has downloaded and the other tab functions as a store and is designed to sell folios to your customers. This functionality is available to all enterprise customers of the Adobe Digital Publishing Suite through the use of custom navigation slots. Using r22, you can replace the default library using your own implementation. These custom slots are implemented using HTML, CSS, and JavaScript. Using code, you can access APIs that allow you to duplicate functionality found in the default library and customize it to fit your project.

Begin by downloading the sample files that are provided at the beginning of this article. The sample files folder contains a template for a library and another template for a store that you can use to create a custom user experience. Figures 1-7 show the various views of the template in a real-world DPS project.

The first page of the marquee offers a subscription if a user doesn't already have a subscription. The next two subsequent pages display the two most recent folios.

The Subscribe button is only displayed if the following conditions are true:

• Subscriptions are available
• The user does not already own the most recent folio
• The user does not already have an active subscription

The Subscriber Login button is for entitlement viewers and will be displayed if a flag, isEntitlementViewer, is set to true in the JavaScript source code.

The library view only shows folios that the user has downloaded and does not contain any store functionality, such as purchases or login interfaces. Users can click the Edit button to remove folios.

Note: If auto archiving is not enabled for the viewer then the button to view the menu is not displayed.

To use the provided library and store templates you must have some folios published as public.

Where does the data come from?

The template uses the new library and store APIs to display folio data and images. All other images are hosted on your server.

Download and uncompress the sample files folder to see the contents. Currently, Viewer Builder does not allow nested folders in HTMLResources. Because of this limitation, the template does not organize the files into folders.

Since this template uses two custom slots, the files for each slot are split apart in the library and store folders. Some of the files are the same, however since custom slots don't share assets the files are separated and duplicated.

When setting up your custom slots, there are two locations for files. Two sets of files are embedded with your viewer by uploading two separate ZIP files to the Viewer Builder, one for each slot. For the store, another set of files is uploaded to your server. Since the library must function when it is offline, there aren’t any files uploaded to a server, rather all of the library files are packaged with the viewer. The separation of these files enables you to make changes to the custom slots without requiring users to download a new version of your viewer. The section below titled Modifying the template for your DPS projects includes a description of files that are uploaded to your server (step 3) and a list of files that are zipped for Viewer Builder (step 4).

The css and images folders contain the css files and image assets used by this template. They should not be included in the zip file for the store custom slot. You should upload them to your server.

Development considerations

The store/assets/src folder contains the JavaScript files for the store custom slot. Since the JavaScript files for the store custom slot are loaded remotely, the files in store/assets/src are combined into store.js for production. The files in store/assets/src are for development only and should not be included in your ZIP or uploaded to the server for production. The files are combined into store.js by running build.xml in Eclipse.

During development, it is a best practice to build and test your content on the desktop using Safari. When testing on the desktop, the API file is not available so data is loaded from the Adobe fulfillment XML feed. Using Safari allows local files to access data across domains, which is required when testing your project on the desktop.

For the store custom slot, use the index_dev.html file to test on the desktop, rather than using the index.html that is packaged with the viewer. The difference between the two is that index_dev.html loads each JavaScript file in the src folder and the css file locally, whereas index.html loads store.js which aggregates all of the JavaScript and css files, so there is only one request from a server. For the library custom slot, use index.html for testing.

While testing on the desktop, be sure to remove the include for AdobeLibraryAPI.js —otherwise you will be unable to view the files in your desktop browser. When testing on the desktop, if nothing is displayed open the debugger to check if there are any file paths that can't be resolved.

To enable the Develop menu option, select Safari > Preferences > Advanced and then choose Show Develop menu in menu bar. Once the Develop menu is displayed, select Develop > Start Debugging JavaScript and then click Console to see if there are any errors. After you've confirmed that your store is running as expected on the desktop, always test the store again on your device.

The following list contains descriptions of the key files for the custom library slot.

• HTMLResources.zip – The file that is uploaded to Viewer Builder. It is included as an example. This file can be uploaded to Viewer Builder as-is for testing purposes.
• assets/AdobeLibraryAPI.js – The file that contains the library and store APIs.
• assets/backbone-min.js – An open source application framework.
• assets/index.html — The HTML file used to display the custom slot.
• assets/jquery-1.7.2.min.js — The jQuery library.
• assets/library.css – the styles for the template.
• assets/main.js — The main JavaScript file that starts the application.
• assets/underscore-min.js — JavaScript library used by Backbone.
• assets/.png – the images for the template.
• assets/.js – the JavaScript files for the template.

Note: Files in the “assets” directory should be included in the custom slot Zip file you upload to Viewer Builder.

The following list contains descriptions of the key files for the custom store slot.

• HTMLResources.zip – The file that is uploaded to Viewer Builder. It is included as an example. This file can be uploaded to Viewer Builder as-is for testing purposes.
• assets/AdobeLibraryAPI.js – The file that contains the library and store APIs.
• assets/backbone-min.js – An open source application framework.
• assets/index.html — The HTML file used to display the custom slot.
• assets/jquery-1.7.2.min.js — The jQuery library.
• assets/library.css – the styles for the template.
• assets/main.js — The main JavaScript file that starts the application.
• assets/underscore-min.js — JavaScript library used by Backbone.
• assets/.png – the images for the template.
• assets/.js – the JavaScript files for the template.

Note: Files above with "assets" should be included in the store Zip file for Viewer Builder.

To make use of this template with your own content, you'll complete the following steps:

1. Modify library/assets/AppView.js and store/assets/src/view/AppView.js.
2. Modify store/assets/index.html so it is pointing to your server.
3. Upload files to your server.
4. Upload files to the Viewer Builder.

The following sections describe each of these steps in more detail.

1. Modify AppView.js.

This modification is only necessary if you would like to test your account on the desktop. Since the API file is not available on the desktop, an XML feed is used to display the folios.

Open library/assets/AppView.js in Eclipse or another code editor. In AppView.js, on line 25, modify FULFILLMENT_URL. Update the accountId parameter to match your accountId.

In store/assets/src/view/AppView.js, on line 28, modify FULFILLMENT_URL to match the accountId parameter with your accountId.

For information on finding your accountId, see the section titled Connecting to fulfillment in Building a custom storefront. Once you have located your accountId, modify the value after http://edge.adobe-dcfs.com/ddp/issueServer/issues?accountId=.

In store/assets/src/view/AppView.js, on line 32, modify isEntitlementViewer to true or false, based on whether or not this is an entitlement viewer. This setting determines whether or not the Subscriber Login button is displayed.

In the store template, the marquee area contains data and images that are not stored in DPS. The first page of the marquee displays an offer to purchase a subscription. To modify this page of the marquee, you'll edit the code starting on lines 114 – 122. The handler for the subscription button is on line 160. This is where the subscription purchase() method is called. The next two pages of the marquee display the two most recent folios. To modify the data for these pages, edit the code beginning on lines 250 and 257. For desktop development when the API file is not available, make changes on lines 222 and 231.

In Eclipse, open store/build.xml in the Ant panel and run the concat targets (see Figure 8).

If you do not have Eclipse, you can alternatively modify the values specified above in store.js.

2. Modify store/assets/index.html.

In store/assets/index.html, on line 25, change the src attribute to point to the location where store.js is hosted.

In store/assets/index.html, on line 37, change the href attribute to point to the location where store.css is hosted.

3. Upload the files to your server.

Upload store/assets/css, store/assets/images, and store/assets/store.js to your server. The file structure on your server should look similar to Figure 10.

4. Upload files to the Viewer Builder.

To upload your files to Viewer Builder for the library custom slot, you must first create an archive that contains the files in library/assets. Make sure to zip the files at the file level rather than the enclosing assets folder

Next, create an archive that contains the following files for the store:

• store/assets/AdobeLibraryAPI.js
• store/assets/backbone-min.js
• store/assets/index.html
• store/assets/jquery-1.7.2.min.js
• store/assets/main.js
• store/assets/offline.css
• store/assets/offline.jpg
• store/assets/underscore-min.js

Once your files are compressed, open the Viewer Builder and navigate to the Navigation Toolbar section. For more information on the Viewer Builder, watch the Viewer Builder tutorial video.

First, you'll add the library. In the Navigation Toolbar section, select Use Custom Viewer Library. Navigate to the zip file you created above for the library. Use the Lock Orientation menu to choose Portrait, and then select the checkboxes to enable Hide Title Bar and Auto Launch (see Figure 11).

Next, click the plus (+) icon to add another slot for the store. Navigate to the zip file you created above for the store. Set the Lock Orientation menu to Portrait. Enable the Hide Title Bar and Auto Launch options. In the Label field enter Cover. This field is required but not used in this example (see Figure 12).

When your IPA has finished building, install the viewer on your device and begin testing.

In this article you learned how to modify two sample templates to create two custom slots: a library and store. If you would like more information on the JavaScript libraries used, check out the documentation for Backbone, jQuery, and Underscore. Additional articles and videos are also available for Digital Publishing Suite.

12/12/2012

• Changed FULFILLMENT_URL so it uses a proxy.
• Added condition to check for folio.isArchivable when archiving a folio.

11/06/2012

• API updates.