Prerequisite knowledge
Experience working with the Adobe Digital Publishing Suite is required. This article also assumes you have published public folios. To make modifications to the files, experience with HTML, CSS and JavaScript is recommended.
 
User level: Intermediate
 
Original publication date: 11/05/2012
Modified: 09/14/2013 (Change log)
Required products
Other required products
  • Mac OS X - Used to view the template on the desktop with Safari.
 
Documentation
Library and Store API v2
 
View on gihub
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
In this article you will learn how to modify a sample template to replace the default library. The sample files in this article contain an HTML implementation of the default library that is included with the viewer. This template enables you to replace the native implementation with an HTML implementation. Using this template, you can customize the library using HTML, JavaScript, and CSS to fit your needs. The template uses APIs that allow you to duplicate e-commerce functionality found in the default library and customize it to fit your project.
If you would like to easily customize the colors and fonts of this template you can use the configurator.
 

 
Template Overview

Begin by downloading the sample files that are provided at the beginning of this article. The sample contains the HTML implementation of the default library. The figures below show the various views of the library.
 
Figure 1. Grid view of folios.
Figure 1. Grid view of folios.
 
Figure 2. The sign in dialog box.
Figure 2. The sign in dialog box.

 
Using the template

To use the provided template you must have folios published as public. 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 decompress the sample files folder to see the contents.
 

 
Development considerations

During development, Adobe recommends that you first build and test your content on the desktop using Safari. This will allow you to adjust the user interface (UI) without having to generate a new viewer to see each change. When testing on your desktop, the API file is not available, so the viewer loads the data from the Adobe fulfillment XML feed.
While testing on the desktop, ensure that you remove the include for AdobeLibraryAPI.js in the index.html file—otherwise you will be unable to view the files in the desktop browser. When testing on the desktop, if nothing displays, open the debugger to check whether there are file paths that cannot be resolved. To use the debugger, use the following steps.
  1. If you do have the debugger on Safari open, select the Develop menu option by going to Safari > Preferences > Advanced. Select the Show Develop menu in menu bar option. The Develop menu will display.
  2. From the Develop menu, select Develop > Start Debugging JavaScript.
  3. Click Console to see if there are any errors. (On Safari 6, select Develop > Show Error Console.)
  4. Confirm that the template is running as expected on the desktop.
  5. Add the AdobeLibraryAPI.js include into to the page once again, and test the template on your device.
The following list contains descriptions of the key files in the template:
  • default_library.zip – The file that is uploaded to 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.10.2.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/*.js – The JavaScript files for the template.
 

 
Modifying the templates for your Digital Publishing Suite projects

To use of this template with your own content, simply complete the following steps:
  1. Modify js/Config.js.
  2. Change the images.
  3. Upload files to App Builder.
The following sections describe each of these steps in more detail.
 
Modifying Config.js.
To modify js/Config.js, use the following steps.
  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.
 
Changing the images
If your viewer uses entitlement, the images used for the banner are entitlement_banner_landscape.png and entitlement_banner_portrait.png.
 
Uploading files to App Builder
Use the following steps to upload your files to the App Builder.
  1. Create an archive that contains the files from the assets directory. When creating the archive, ensure that you archive the files at the file level rather than at the directory level of the assets directory.
  2. Open the App Builder and navigate to the Navigation Toolbar section. For more information on the App Builder, watch the App Builder tutorial video.
  3. In the Navigation Toolbar section, select the option to Use Custom Viewer Library.
  4. In the Library HTML Resources ZIP field, navigate to your ZIP file to add it to your viewer.
  5. Select an orientation if you would like to lock the orientation to portrait or landscape.
  6. Select the Hide Title Bar option if you do not want to display the title bar. The label in the title bar uses the value defined in the HTML title tag in index.html.
  7. Select the Auto Launch option if you would like the custom slot to be the first slot displayed.
 
Figure 4. The Navigation Toolbar section of the App Builder for the library.
Figure 4. The Navigation Toolbar section of the App Builder for the library.
 
  1. When your IPA has finished building, install the viewer on your device and begin testing.
 

 
Where to go from here

In this article you learned how to modify a sample template to replace the default library. If you would like more information on the JavaScript libraries used, check out the  documentation for BackbonejQuery, and Underscore. See additional articles and videos available for Digital Publishing Suite on the Adobe Developer Connection.
I have written the following articles explaining how to use the library/store API:
If you would like to easily customize the colors and fonts of this template you can use the configurator.
 

 
Change log

09/14/3013
  • Updated for iOS 7 look and feel.
11/09/2012
  • API updates.
05/03/2012
  • Sample files were updated.