Build a horizontal swipe storefront with folio preview

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 adjacent to the Library and Viewer tabs. 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 buyFolio() , archiveFolio() and getFolioData() , which retrieves the state and data for a folio. 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.

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.

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 Adobe fulfillment XML data 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.

Note: For information on using Adobe fulfillment XML data, see the "Connecting to fulfillment" section in the Adobe article Building a custom storefront.

Since the Magazines and Specials sections both use the fulfillment XML data 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.

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.

To view the app running on the desktop, open either store.html or store_dev.html 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:

• apps.xml—used to specify which apps should appear in the apps tab
• *backbone.js—open source application framework
• build.xml—Ant script used to aggregate the JS files in src into store.js.
• *jquery-1.7.1.min.js—JQuery library
• *network_detection.js—detects whether or not the device has an internet connection
• *offline_landscape.jpg, *offline_portrait.jpg—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.

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 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 main.js

On line 7, 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 10, modify APPS_URL so the value matches the URL for where you will be hosting apps.xml.

On line 13, modify IMAGE_PATH_URL so the value matches the path to where your images will be hosted.

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

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

3. Modify store.html

On line 9, change the src attribute so it is pointing at the location for where you will be hosting store.js.

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

6. Upload files to Viewer Builder

To upload your files to Viewer Builder, you must first zip the following files:

• backbone.js
• jquery-1.7.1.min.js
• network_detection.js
• offline_landscape.jpg
• offline_portrait.jpg
• offline.css
• store.html
• underscore-min.js

You must keep the files in a flat folder structure so they are all in the same folder and zip the files at the file level, not the containing folder. 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). If you don't have any custom icons, you can use the provided store_disabled.jpg, store_off.jpg and store_on.jpg images.

Before testing from the iPad, it is recommended that you first test from desktop Safari on OS X. Note that you might see the message "Please rotate iPad to view the store" if the Safari browser window resembles "landscape" aspect ratio; if so, drag the Safari window corner to resize it to more of a portrait ratio. If the store is still 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.

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.