Prerequisite knowledge
Experience working with JavaScript, HTML, XML, and the Adobe Digital Publishing Suite is required. This article also assumes you have access to a web server and have published public folios.
 
User level: Beginning
 
Original publication date: 08/08/2012
Modified: 09/18/2013 (Change log)
Adobe products Other required products
  • Mac OS X - Used to view the template on the desktop with Safari.
Documentation

 

Sample files
default_iphone_library_v2.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
The sample files in this article contain a template 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 on the iPhone using version 2 of the library and store APIs. This functionality is available to all enterprise users of the Adobe Digital Publishing Suite through the use of custom navigation slots. 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 design. If you would like to easily customize the colors and fonts of this template you can use the configurator.
 

 
Overview of the template

Begin by downloading the sample files provided at the beginning of this article. The sample files contain a template that offers an alternate view of the default library. Using source code, you can change the appearance of the interface to publish a custom user experience. Figures 1-5 shows the various views of the template implementation.
 
Figure 1. Folios are displayed in a list.
Figure 1. Folios are displayed in a list.
 
Figure 2. Clicking the settings icon displays the settings view.
Figure 2. Clicking the settings icon displays the settings view.
Note: The Auto Archive option is only displayed if auto-archive is enabled for the viewer.
 
Figure 3. Clicking Restore Purchases lets users restore purchases.
Figure 3. Clicking Restore Purchases lets users restore purchases.
 
Figure 4. Clicking Subscribe enables a user choose a subscription.
Figure 4. Clicking Subscribe enables a user choose a subscription.
 
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
 
Figure 5. Clicking Subscriber Login displays a login view.
Figure 5. Clicking Subscriber Login displays a login view.
 
The Subscriber Login button is used for entitlement viewers. It is displayed if a flag, Config.IS_ENTITLEMENT_VIEWER, is set to true in the JavaScript source code.
 

 
Understanding the store and library APIs

In order to use this template you must have folios which are published as public.
Where does the data come from?
The template uses the library and store APIs to display folio data and images. All other images are packaged in your viewer. Download and uncompress the sample files folder to see the contents.
 
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:
  • default_iphone_library_v2.zip – The file that is uploaded to the App Builder. It is included as an example. This file can be uploaded to App Builder as-is for testing purposes.
  • libs/AdobeLibraryAPI.js – The file that contains the library and store APIs.
  • libs/backbone-min.js – An open source application framework.
  • index.html — The HTML file used to display the custom slot.
  • libs/jquery-1.9.1.min.js — The jQuery library.
  • styles.css — the styles for the template.
  • js/main.js — The main JavaScript file that starts the application.
  • libs/underscore-min.js — JavaScript library used by Backbone.
  • images/*.png — the images for the template.
  • *.js — the JavaScript files for the template.
 

 
Modifying the template for your projects

To use this template with your own DPS content, you'll complete the following steps:
  1. Modify Config.js
  2. Upload files to App Builder.
The following sections describe each of these steps in more detail.
  1. If your viewer is not an entitlement viewer, set IS_ENTITLEMENT_VIEWER to false. If you are creating an entitlement viewer, you will need to set the BANNER_TARGET_URL, CREATE_ACCOUNT_URL and FORGOT_PASSWORD_URL. If CREATE_ACCOUNT_URL or FORGOT_PASSWORD_URL are blank, the respective links in the signin dialog are not displayed.
  2. Change FULFILLMENT_URL if you would like to test your account on the desktop. Since the API file is not available on the desktop, you can use this XML feed to display the folios. Modify FULFILLMENT_URL to match the accountId parameter with your accountId. To get your account id, go to http://lighthouse.adobe.com/dps/entitlement/. Once you have located your accountId, modify the value after http://edge.adobe-dcfs.com/ddp/issueServer/issues?accountId=[your value].
  3. If you do not want folios to automatically open when enough have been downloaded, set IS_AUTO_OPEN_DOWNLOADED_FOLIO to false.
 
  1. Upload the files to the App Builder.
If you have not made any modifications to the files you can upload the zip as is to App Builder. If you have made any changes, zip the files at the file level rather than containing folder.
Once your files are compressed, open App Builder and navigate to the Navigation Toolbar section. For more information on App Builder, watch the App 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 select the Hide Title Bar checkbox.
 
Figure 6. The Navigation Toolbar section of the App Builder.
Figure 6. The Navigation Toolbar section of the App Builder.
 
When your IPA has finished building, install the content on your device and begin testing.
 

 
Where to go from here

In this article you learned how to modify a sample template to create a library and store custom slot. To get more information about the JavaScript libraries used, check out the documentation for Backbone, jQuery and Underscore. Additional articles and videos are also available for Digital Publishing Suite.
If you would like to easily customize the colors and fonts of this template you can use the configurator.
 

 
Change log

09/18/2013
  • Updated for v28 and iOS 7.
12/12/2012
  • Changed FULFILLMENT_URL so it uses a proxy.
  • Added condition to check for folio.isArchivable when archiving a folio.
10/15/2012
  • API updates.