Working with the combined library/store custom slot template using new DPS APIs

The sample files in this article contain a combined library / store custom slot you can implement in your DPS viewer. The template enables you to add a custom tab in the viewer that functions as a store and library using version 2 of the library and store APIs. This functionality is available to all enterprise customers of the Adobe Digital Publishing Suite through the use of custom navigation slots. With r22, publishers can replace the default library using their own implementation. These custom slots are implemented using HTML, CSS, and JavaScript. Using code, you can access APIs that allow you to duplicate e-commerce 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 file contain the combined library / store custom template that offers an alternate view of the default library. Using source code, you can change the e-commerce interface to create a custom user experience. Figures 1-5 show the various views of the template.

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

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

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 packaged with your viewer.

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.

File structure

Development considerations

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.

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 in the template:

• HTMLResources.zip – The file that is uploaded to the 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 the Viewer Builder.

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

1. Modify assets/AppView.js.
2. 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, this XML feed is used to display the folios.

Open AppView.js in your code editor. On line 41, modify FULFILLMENT_URL to match the accountId parameter with your accountId. If you need help 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=.

On line 45, 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.

2. Upload files to the Viewer Builder.

To upload your files to the Viewer Builder, you must first create an archive that contains the files from the “assets” directory. When the archive is created, be sure to zip the files at the file level rather than the directory level of the assets directory.

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.

In the Navigation Toolbar section, select the option to Use Custom Viewer  Library. Navigate to the zip file you created above and use the Lock Orientation menu to choose Portrait. Select the checkboxes to Hide Title Bar and Auto Launch.

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

In this article you learned how to modify a sample template to create a library and store custom slot. 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.

To learn more about how to extend Adobe DPS to meet your business needs, watch the video of Klaasjan Tukker's MAX 2013 session, Extending and Integrating 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.