Note: This article uses the V2 version of the DPS JavaScript API. If you wish to use the V1 API version of the Horizontal Swipe Store, see the original version of this article.
 
Prerequisite knowledge
This article assumes knowledge of JavaScript, HTML and XML and the Adobe Digital Publishing Suite. This article also assumes you have access to a web server and have folios which are published as public.
 
User level: Intermediate
 
Original publication date: 04/02/2012
Modified: 03/15/2013 (Change log)
Adobe products
Other required products
  • Eclipse—not mandatory but used to run an ANT script which will combine the JavaSript files into one file.
  • OS X—for testing on the desktop with Safari

 

Documentation

 

 

Sample files
master.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
 
Recently, a major publisher wanted to merchandise their collection of back issues, books, and special-interest publications in a custom and highly branded experience. This article describes the framework used and provides guidance on how to adapt it to your needs. This functionality is available to all enterprise customers of the Adobe Digital Publishing Suite through the addition of custom navigation slots. These custom slots are implemented using HTML, CSS, and JavaScript and have access to a store API that is automatically injected into the HTML page for the custom slots. The API includes methods such as folio.purchase() , folio.archive() and authenticationService.login(). Using the API, 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. This article will get you started on using a template that has been created to enable users to swipe horizontally through pages and to view a folio preview when they tap a cover.
 

 
Store overview

The store template offers a number of features publishers can leverage to enrich the user experience. Figures 1-4 show how these features look in the template.
 
Figure 1. Users can swipe horizontally to navigate within a section or click a tab to navigate to a different section. Folios in this section, called "Magazines" in this template, are populated from the API. Pricing information is obtained through the store APIs, which in turn access iTunesConnect for prices.
Figure 1. Users can swipe horizontally to navigate within a section or click a tab to navigate to a different section. Folios in this section, called "Magazines" in this template, are populated from the API. Pricing information is obtained through the store APIs, which in turn access iTunesConnect for prices.
 
 
Figure 2. The Apps section lets publishers cross-sell items available in the app store. Pricing and all other metadata comes from a publisher-hosted XML feed. This section name can be modified as desired.
Figure 2. The Apps section lets publishers cross-sell items available in the app store. Pricing and all other metadata comes from a publisher-hosted XML feed. This section name can be modified as desired.
 
 
Figure 3. The Specials section displays folios that are specially offered and not part of the regular publishing schedule. Folios in this section are populated from the API.
Figure 3. The Specials section displays folios that are specially offered and not part of the regular publishing schedule. Folios in this section are populated from the API.
 
 
Figure 4. If users click a cover, a scrollable preview of the folio is displayed. Previews are flat images created by the publisher and fetched at runtime via an HTTP request.
Figure 4. If users click a cover, a scrollable preview of the folio is displayed. Previews are flat images created by the publisher and fetched at runtime via an HTTP request.
 
 
 

 
Getting started

 
Where does the data come from?
In order to make use of this store template you must have folios which are published as public. This store uses the API to populate the Magazines and Specials tab and uses a different XML file, apps.xml, to populate the apps tab. Folio covers are also served from the fulfillment server. All other images are hosted on your server.
Since the Magazines and Specials sections both use the API as a data source, a naming convention is used to distinguish between the two folio types. If the Folio Number, entered from Folio Producer, contains a month in the value, then the folio is a regular magazine. If it does not contain a month in the value, then it is a special. For example, "January 2011" would display in Magazines, but "Spring Decorating" would display in Specials since it does not contain a month in the Folio Number. The filtering is done at the collection level in JavaScript when the XML is parsed in MagazinesCollection.js and SpecialsCollection.js.
In this template, the second tab is labeled "Apps," and the example depicts how publishers could cross-sell other apps that they might have in the iTunes App Store or Google Play marketplace. This tab could be renamed and repurposed for any other use, such as for selling physical goods. For example, it could be renamed "Shop," and you could swap out the links in the apps.xml file for URLs that point to goods on an e-commerce site.
 
File structure
If you unzip the horizontal_swipe_store.zip file, you will see the file structure displayed in Figure 5.
 
Figure 5. Top-level file structure of horizontal_swipe_store.zip
Figure 5. Top-level file structure of horizontal_swipe_store.zip
 
 
When setting up your store, there are two locations for files. One set of files will be embedded with your viewer by uploading a ZIP file to Viewer Builder. For a description of files that are uploaded to your server, see step 5 below. For a list of files that are zipped for Viewer Builder, see step 6 below.
The "images" folder contains the images used by this template. They should not be included in your store ZIP file, but should be uploaded to your server.
The "src" folder contains the JavaScript files that are combined into store.js for production. This folder is for development only and should not be included in your store ZIP file or uploaded to the server for production. The files are combined into store.js using build.xml. In development, it is recommended that as much work as possible is done on the desktop using Safari. Using Safari allows local files to access data across domains (see Figure 6). This is needed because data will be loaded across different domains using this custom store template.
 
Figure 6. Requests across two different domains.
Figure 6. Requests across two different domains.
 
 
To view the app running on the desktop, delete the JavaScript include for AdobeLibraryAPI.js in either store.html or store_dev.html and open the respective file in Safari. The difference between the two is that store_dev.html loads each JavaScript file in the src folder and the store.css file locally, whereas store.html loads store.js, which aggregates all of the JS files so there is only one request, and store.css from a server. Please remember that since the store is running on the desktop and not in the viewer, the store API is not available.
Here are the key files in the package:
  • *AdobeLibraryAPI.js—The file that contains the library and store APIs.
  • apps.xml—used to specify which apps should appear in the apps tab
  • *backbone-min.js—open source application framework
  • build.xml—Ant script used to aggregate the JS files in src into store.js.
  • *jquery-1.7.2.min.js—JQuery library
  • *main.js — The main JavaScript file that starts the application.
  • *offline.gif—displayed when the device is offline
  • *offline.css—used when the device is offline
  • store_dev.html—used for development on the desktop
  • store_disabled.jpg, store_off.jpg, store_on.jpg—sample icon files for the store tab
  • store.css—styles for the store, loaded remotely
  • *store.html—used for production on the device or final testing on the desktop
  • store.js—the aggregated JavaScript file used for production, loaded remotely
  • *underscore-min.js—JavaScript library used by backbone.js
Note: Files above with "*"should be included in the store Zip file for Viewer Builder.
 

 
Modifying the template for your use

To make use of this template with your own content, complete the following steps:
  1. Modify apps.xml so it is pointing to your apps (or other items you want in that tab)
  2. Modify src/view/main.js, then run build.xml to create a new store.js.
  3. Modify store.html so it is pointing at your web server.
  4. Create preview images of your folios.
  5. Upload files to your web server.
  6. Upload files to Viewer Builder.
The following sections explain these steps in more detail.
 
1. Modify apps.xml
This XML file creates the list of app thumbnails in the Apps tab.
 
Each app node represents the data required to display one application. If you have more than one page of apps in the viewer, new pages will be automatically created. If you would like to market something other than an app, you can change the appStoreUrl node to link to something else. For example, you could link directly to your e-commerce page that is selling a hat.
 
2. Modify src/view/main.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.
On line 8, modify FULFILLMENT_URL so the accountId parameter matches your accountId. For information on finding your accountId, see the "Connecting to fulfillment" section in the Adobe article Building a custom storefront. Once you have your accountId, you will modify the value after http://edge.adobe-dcfs.com/ddp/issueServer/issues?accountId=.
On line 11, modify APPS_URL so the value matches the URL for where you will be hosting apps.xml.
On line 14, modify IMAGE_PATH_URL so the value matches the path to where your images will be hosted.
On line 17, modify PREVIEW_DIR if the subdirectory for your preview images will be different. This path is a subdirectory of IMAGE_PATH_URL. The preview images are the images that are visible when a user clicks a thumbnail.
In Eclipse, open build.xml in the Ant panel and run the concat target (see Figure 7).
 
Figure 7. Ant panel with build.xml
Figure 7. Ant panel with build.xml
 
 
If you do not have Eclipse, you can alternatively modify the values specified above in store.js beginning on line 2979.
 
3. Modify store.html
On line 10, change the src attribute so it is pointing at the location for where you will be hosting store.js.
On line 13, change the href attribute so it is pointing at the location for where you will be hosting store.css.
 
4. Create preview images
Preview images are displayed when a user taps a thumbnail, as was shown in Figure 4. Preview images should not be wider than 567px nor longer than 3600px. Beyond 3600px, iOS will make the image appear scaled. Preview images should be named with the format <product-id>.jpg. So if your product ID is jan2012, then the filename for the preview should be jan2012.jpg. Images should then be uploaded to IMAGE_PATH_URL + PREVIEW_DIR. In the example files, this translates to http://lighthouse.adobe.com/dps/horizontal_swipe_store/images/previews/.
 
5. Upload files to your web server
When your file modifications and images are ready, upload your images, apps.xml, store.css, and store.js to the URLs specified in step 2. Keep in mind that the image paths in store.css are relative to store.css, so the images should be in a folder named "images" on the same level as store.css. The file structure on your server should look similar to Figure 8.
 
Figure 8. File structure on the web server
Figure 8. File structure on the web server
 
 
 
6. Upload files to Viewer Builder
To upload your files to Viewer Builder, you must first zip the following files:
  • AdobeLibraryAPI.js
  • backbone-min.js
  • jquery-1.7.2.min.js
  • main.js
  • offline.jpg
  • offline.css
  • store.html
  • underscore-min.js
Once your files are zipped, open Viewer Builder and navigate to the Navigation Toolbar section. For more information on Viewer Builder, see the Viewer Builder tutorial video. In the Navigation Toolbar section, there is a "+" icon in the lower-middle right of the screen which will allow you to add a custom slot (see Figure 9). 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. If you don't have any custom icons, you can use the provided store_disabled.jpg, store_off.jpg and store_on.jpg images.
 
Figure 9. The Navigation Toolbar section from Viewer Builder
Figure 9. The Navigation Toolbar section from Viewer Builder
 
 
Before testing from the iPad, it is recommended that you first test from desktop Safari on OS X. If the store is displaying incorrectly or not displaying any folios, it will be worthwhile to open the debugger to see if there are any file paths that can't be resolved. If you don't have a Develop menu option, first select Safari > Preferences > Advanced and choose "Show Develop menu in menu bar." Once this item is chosen, select Develop > Start Debugging JavaScript and click Console to see if there are any errors. Once your store is running correctly on the desktop, you should test on your device.
 

 
Where to go from here

This article has shown you how to modify sample files to create a store that allows a user to swipe horizontally and view folio previews. If you would like more information on the JavaScript libraries used, you can check the documentation for Backbone, jQuery and Underscore. Additional articles and videos are also available for Digital Publishing Suite.
 

 
Change log

03/15/2013
  • Bug fixes in sample file.
12/12/2012
  • Changed FULFILLMENT_URL so it uses a proxy.
12/07/2012
  • Added link to the original version of this article, which uses the V1 version of the DPS JavaScript API, to a note at the top of the article.
11/06/2012
  • Updated to v2 of library/store API.