Prerequisite knowledge
  • JavaScript
User level: Intermediate
Required Adobe products (retail)
Documentation
Sample files
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 

 
Introduction

Release 30 of DPS (March 2014) includes new APIs for dialogs, transparent webviews, folio navigation, article metadata and calendar and reminder events. This article will provide examples on how to use these new APIs.
If you are using any of the new APIs from within a folio via the reading API, you need to enable the APIs by checking “Allow Access to Entitlement Information” from either the Folio Overlay panel for Web Content overlays or from Folio Producer for HTML articles.
 
Figure 01: Checkbox to enable the reading API.
Figure 01: Checkbox to enable the reading API.
 
In order to use these APIs you need to add an include for the respective JavaScript API in your HTML. For a custom tab you would use the library/store API and from within a folio you would use the reading API. To get the latest versions of the JavaScript APIs go to the documentation pages for the library/store API and reading API.
 

 
Sample File Overview

The sample files included in this article demonstrate how to use the transparent webviews, folio navigation, article metadata and calendar and reminder events API from a folio. Since the HTML is meant to be displayed from a folio, it uses the reading API. The HTML can be used as either an HTML article or in a web content overlay. The files do not work in a desktop browser and need to be used on an iPad.
 
Figure 02: Output of the sample HTML page.
Figure 02: Output of the sample HTML page.
 
The first link of the page opens the transparent webview (or “Information Screen”). The links below that use the new navigation formats to navigate between articles. The text following the links is the output from the article metadata APIs. Since this article was not in a section, the relevant output fields are null and undefined. The image is the article TOC preview image uploaded to Folio Producer. Below the image are two additional links. The first link adds a sample calendar event 24 hours from the time the link is tapped. The second link adds a reminder to buy recipe items.
 
Figure 03: The transparent webview that is displayed after a user taps “open transparent webview”.
Figure 03: The transparent webview that is displayed after a user taps “open transparent webview”.
 
The transparent webview that is displayed is hosted remotely at http://www.dpsapps.com/users/derek/r30_api_samples/transparent_webview.html.
 

 
Login and Subscribe Dialogs

Before r30, if you created a custom tab and wanted to open the native sign-in dialog or subscription dialog from JavaScript you were unable to. Because of this you would need to implement your own dialog in HTML and JavaScript. With r30, you can use adobeDPS.authenticationService.displaySignIn() and adobeDPS.receiptService.displaySubscribe() to display the native dialogs from a custom tab.
Displaying the native sign-in dialog is not available from within a folio via the reading API. Since it is only available via the library/store API, displaying the native sign in dialog is only available to DPS Enterprise customers.
To display the subscription dialog from within a folio via the reading API you need to use adobeDPS.subscriptionService.displaySubscribe(). Since it is available from the reading API, displaying the native subscription dialog is available to DPS Enterprise and DPS Professional customers.
When opening these dialogs there are not any events for when a user has logged in or bought a subscription. If you would like to listen for these events you should use adobeDPS.authenticationService.updatedSignal and adobeDPS.receiptService.newReceiptsAvailableSignal.
 

 
Information Screen (Transparent webview)

With r30 customers can now open a transparent webview from any web overlay, HTML article or custom tab. Using this API customers can do things such as:
  • Display a subscription call to action for users that have previewed but not bought an issue.
  • Display highlighted content with navigation links for users that have not opened the app in X days.
  • Display a promotion for related publications if the user is an active subscriber of the current publication.
  • Display a promotion (“Digital Blow-In”) every X pages or swipes.
The use case for this API is to display content which supplements or complements your content. If you would like to display a webpage from your site, it is recommended that you use a slide up webview via adobeDPS.dialogService.open().
To open a transparent webview, use adobeDPS.dialogService.displayCustomWebview(url).
To close the transparent webview you need to call adobeDPS.dialogService.dismissCustomWebview() from the opened webview. If you do not call this method from the transparent webview, users will not be able to close it.
The API that the webview can access depends on where the webview was invoked. If invoked from within the app, the webview will have access to the Library/Store API. If invoked from within a folio, the webview will have access to the Reading API. If your transparent webview was opened from a custom tab you will need to include the library/store API. If it was opened from a folio, you will need to include the reading API.
If you are calling a remote URL with this API, you should handle the case for when a user is offline. To check for connectivity you can use an XMLHttpRequest to hit a URL. If the user is offline it is recommended that you display messaging to the user.
Because this API is accessible from the library/store and reading APIs, this API is available to both DPS Enterprise and DPS Professional customers.
 

 
Folio Navigation

Prior to r30, customers could use navto links to navigate between articles by hard coding the name of the article, ie: navto://articlename. If a customer wanted to create “next” and “previous” links this would be problematic if an article was moved. It was also not possible to create a reusable navigation that multiple articles could use. With r30 a new navto format is available that allows for navigating between articles without hard coding an article name. The new formats are:
  • Go to first article: navto://relative/first
  • Go to last article: navto://relative/last
  • Go to next article: navto://relative/next
  • Go to previous article: navto://relative/previous
  • Go to n-th article: navto://relative/article_index
  • Go to next page: navto://relative/current#next
  • Go to previous page: navto://relative/current#previous
  • Go to n-th page: navto://relative/current#page_position
The article_index and page_position are both zero-based meaning page one would be referenced with a zero. For the n-th page in a smooth scrolling stack, the value is a percent.
This feature is available to both DPS Enterprise and DPS Professional customers.
These new formats are also available from InDesign by adding your navto links to the buttons panel. Whethere you are using this feature from InDesign or HTML you do not need to include the Reading API.
If you would like more information on navto links, please visit the help page.
 

 
Article Metadata

With r30, you now have access to article metadata from within a folio. This API allows you to retrieve metadata about an article using a new class called adobeDPS.folioDataService. This class contains two properties, totalArticlesInFolio and totalArticlesInSection, and two methods, getArticleMetaData() and getArticlePosition(). If the article is not in a section the properties return null and undefined.
getArticleMetaData(relativeIndex, successCallback, errorCallback) takes three parameters. The first parameter is the index of the article for which you would like metadata. The index is relative to the current article. If the value is 0, it gets the current article’s properties. If the value is negative (-1, -2, etc), it gets the metadata of an article on the left. If the value is positive (1, 2, etc), it gets the metadata of an article on the right. The second parameter is the callback function that is called when the data is returned. This callback is passed an ArticleMetaData object which contains the metadata for the article. The third parameter is the callback function that is called when an error has occurred.
ArticleMetaData contains the following properties: title, description, author, kicker, articleTOCPreviewURL, isHorizontalSwipeOnly and hasFreePreview.
getArticlePosition(successCallback, errorCallback) takes two parameters. The first parameter is the callback function that is called when the data is returned. This callback is passed an ArticlePosition object which contains the position data for the article. The second parameter is the callback function that is called when an error has occurred.
ArticlePosition contains the following properties: currentIndexInFolio, currentIndexInSection, currentPageNumber and totalPageCount.
Using this API customers can do things such as:
  • Create a table of contents at runtime.
  • Use this API and the aforementioned navigation formats to create a dynamic navigation similar to the numbered page navigation displayed at the bottom of Google search results.
  • Use this API and the aforementioned navigation formats to dynamically generate a list of links to articles and pages within an article.
This feature is available from within folios so you must use the reading API. Since it is used from within a folio, the feature is available to both DPS Enterprise and DPS Professional customers.
 

 
Calendar and reminder events

R30 now gives you the ability to add calender and reminder events to the respective apps on iOS. Using this API customers can do things such as:
  • Allow users to add special events to their calender by tapping a button. For example, a conference brochure could allow people to add sessions to their calendar.
  • Allow users to add a list of items to their reminders. For example, a cooking magazine could create a shopping list of ingredients for a recipe that gets added as a reminder.
This API is accessed from a new class called adobeDPS.calenderService.
The steps to add a calendar event are:
  1. Create a new adobeDPS.calendarService.EventItem(summary, description, location, alarms). This class contains the data for the event. Alarms is an Array of times for when to display a reminder that the event will be starting.
  2. Create a new adobeDPS.calendarService.CalendarEvent(eventItem, startDate, endDate, allDay, eventId). The eventItem is the object created in the previous step. startDate and endDate are milliseconds for the respective dates.
  3. Add the CalendarEvent using adobeDPS.calendarService.addEvent(calendarEvent, successCallback, errorCallback). This method adds the event to the calendar. The successCallback is triggered if the event was added successfully otherwise the errorCallback is triggered. You can also use adobeDPS.calendarService.addEvents() to add multiple events at once.
 
Figure 04: The sample event added to the calendar app.
Figure 04: The sample event added to the calendar app.
 
The steps to add a reminder event are:
  1. Create a new adobeDPS.calendarService.EventItem(summary) for each reminder item. The summary property is the value that will be displayed in the reminder.
  2. Create a new adobeDPS.calendarService.ReminderEvent(eventItem, listTitle, dueDate) for each reminder item. The eventItem is the object created in the previous step. To group reminders under the same list, use the same listTitle for each ReminderEvent.
  3. Add the ReminderEvent using adobeDPS.calendarService.addEvent(reminderEvent, successCallback, errorCallback). This method adds the event to the reminders. The successCallback is triggered if the event was added successfully otherwise the errorCallback is triggered. You can also use adobeDPS.calendarService.addEvents() to add multiple events at once.
 
Figure 05: The sample reminder added to the reminders app.
Figure 05: The sample reminder added to the reminders app.
 
This feature is available from a custom tab and from within a folio. DPS Enterprise customers can use the feature from a custom tab via the library/store API while both DPS Enterprise and DPS Professional customers can use it from a folio via the reading API.
With r32, customers can now reset their folios by using navto://relative/reset. This feature allows a customer to go back to the beginning of a folio and reset the article's reading position to the top. This can be useful for DPS apps which function as kiosk and demo apps. To make use of this feature, add navto://relative/reset to the URL of a button.
 

 
Where to go from here

This article provided samples of the new APIs available in r30. If you are interested in the library/store API please visit this page. If you are interested in more examples of the reading API please visit these articles: New Consumer Marketing APIs, Getting started with the camera API and Getting Started with the geolocation API.
 
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.