Follow

How To Write A Connector

This primer is intended for connector developers that want to be able to use their own Content Management System to manage Pugpig editions. We recommend reading through this to get an understanding of the process, before diving into the detail of each step. Also note that:

  • If you are using an off-the-shelf CMS, we may well already have something in development.
  • If you have a home-grown system based on PHP, Java or C#, we probably have components that can accelerate things.
  • Please get in touch with questions!

Most of the steps are optional - a basic prototype connector to most Content Management Systems requires only the first four steps, and should be achievable with a few days effort.

- Step 0 : Before you start
- Step 1 : Discovering the list of editions
- Step 2 : Creating the contents of an edition
- Step 3 : Creating the HTML
- Step 4 : Creating the offline manifests
- Step 5 : Pugpig Distribution Service



Step 0: Before you start 

In order to test your connector as you develop, you should download the iOS Pugpig Reader App from the App Store. This is a generic iPad and iPhone client that allows you to supply the entry point into your CMS and tweak some settings. You can get started with your connector without writing an iOS code.

Pugpig Reader for iOS




Step 1: Discovering the list of editions

                                                                                        

The first feed that needs to be implemented is the edition list, which serves as the entry point for the Pugpig Readers. It uses the Open Publication Distribution System (OPDS) Catalog specification, which is based on Atom. This feed tells the readers about all the editions in the system, which are then displayed on the issue selector. Editions are by default ordered by date, with the most recent on the right.

Each edition entry has:

  • A title, and an optional summary
  • A link to cover image
  • A link to the contents of the edition (see Step 2)
  • Information on whether the edition is free or paid for
  • Information on whether the edition is published or still in draft

More detailed information and samples can be found in the Document Discovery section. You should validate your editions feed using the Unofficial OPDS validator.

Below is a sample feed with only one edition. You can also look at the default feed using by the Pugpig Reader at http://books.pugpig.com/editions.xml.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:dcterms="http://purl.org/dc/terms/" 
xmlns:opds="http://opds-spec.org/2010/catalog" xmlns:app="http://www.w3.org/2007/app">
 
  <id>com.mycompany.myeditions</id>
  <link rel="self" type="application/atom+xml;profile=opds-catalog;kind=acquisition" href="URL_TO_THIS_DOCUMENT"/>
  <title>All Editions</title>
  <updated>2011-08-08T15:02:28+00:00</updated>
  <entry>
    <title>My First Edition</title>
    <id>com.mycompany.edition1</id>
    <updated>2011-08-08T14:37:52+00:00</updated>
    <author><name>Bob Smith</name></author>
    <dcterms:issued>2011-08-06</dcterms:issued>
    <summary type="text"></summary>
    <link rel="http://opds-spec.org/image" type="image/jpg" href="img/cover.jpg"/>
    <link rel="http://opds-spec.org/acquisition" type="application/atom+xml" href="edition1.xml"/>
    <link rel="alternate" type="application/atom+xml" href="edition1.xml"/>    
  </entry>
</feed>

Once you have implemented Step 1, you should be able to point your Pugpig Reader app at it and see the editions appear in the edition selector. You clearly will not be able to download any editions until you've completed Steps 2 and 3.




Step 2: Creating the contents of an edition

                                                                                       

Each edition uses an Atom feed to specify the pages which is contains. Each entry in the feed represents a page in the edition, and these are also the pages shown in the navigator drawer in the Pugpig client. Each page needs:

  • A unique ID
  • A link to the HTML of the page (see Step 3)
  • A link to the HTML5 offline manifest of the page (See Step 4)
  • The time of the last significant update
  • Optional categories and navigation depth

More detailed information and samples can be found here: Atom Document Type. If you are in a hurry, you could use the simpler (but less powerful) HTML Manifest Document Type instead.

You should validate your edition contents feed using the W3C Feed Validator - although we are happy not to use full URIs in the <id> fields.

Below is a sample edition with two pages.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="self" type="application/atom+xml" href="URL_TO_THIS_DOCUMENT"/>  
  <title type="text">Sample Edition</title>
  <subtitle type="text">This is a sample edition with 2 pages</subtitle>
  <author><name>John Doe</name></author>
  <updated>2011-07-11T12:30:24Z</updated>
 
  <entry>
    <id>e1</id>
    <link rel="alternate" type="text/html" href="page1.html" />
    <link rel="related" type="text/cache-manifest" href="page1.manifest" />
    <title type="text">Page 1</title>
    <summary type="text">Page 1 summary</summary>
    <updated>2011-07-11T12:30:24Z</updated>
  </entry>
 
  <entry>
    <id>e2</id>
    <link rel="alternate" type="text/html" href="page2.html" />
    <link rel="related" type="text/cache-manifest" href="page2.manifest" />
    <title type="text">Page 2</title>
    <summary type="text">Page 2 summary</summary>
    <updated>2011-07-11T12:30:25Z</updated>
  </entry>
</feed>

TIP: We would recommend that CMS connectors have two new content types - one called Edition Container and one called Edition. For hierarchical systems, the only allowed children of the Edition Container should be of type Edition. The Edition Container would output the OPDS feed by iterating over the child editions. The Edition would output the Atom by iterating over the children of the edition.

Even though you've implemented Step 2, you won't be able to download an edition unless the HTML is in place.




Step 3: Creating the HTML

Each page in a Pugpig application is a standalone HTML page that will be rendered in a single web view. You should create this HTML in exactly the same way you would normally create HTML targeting tablet devices.

We can provide some sample templates to help you get started. Get in touch if you think these will be useful.

For your test connector, you could use the HTML you already have for your web pages although it might not adapt beautifully to the iPad. You can test your markup by viewing it in the target browsers (for example, Mobile Safari on an iPad or iPhone) to ensure it behaves as expected.

For more advanced topics on creating Pugpig markup, see Example HTML Content.

Once Step 3 is complete and you have HTML, you should be able to download an edition. However, the associated assets (for example, images and style sheets) won't be downloaded and cached for offline use until you've completed Step 4 (adding manifest files to the document's feed).




Step 4: Creating the offline manifests

As the Pugpig client pre-downloads issues in the background, it needs to know all the assets associated with an issue. In order to achieve this, you need to provide a standard HTML5 Offline Cache Manifest for every page. If your CMS is doing any offline web sites, the chances are you have implemented this step already.

In order to test the manifest, you should download the issue using the Pugpig Reader, then go into offline mode before viewing the issue. The Pugpig Reader will log any unexpected uncached items.

You should validate your manifests using the Cache Manifest Validator.

You can find more details (including how to incorporate a Content Delivery Network) at Asset Downloading. A simple example is shown below:

CACHE MANIFEST
# page: 2.html
# generated by the pugpig plugin

CACHE:

# page attachments
lovelypicture.jpg
lovelyattachments.pdf

# Theme: theweek
/theme/style.css
/theme/header.jpg

NETWORK:
*

TIP: The offline manifest is normally made up of two kinds of assets - the “furniture” assets that are used by almost every page and then the assets that are unique to each page. The first set can either by created by hand, or by looking for all the files in the so-called “theme directory”. The second set is normally created by looking for all assets attached to the page. Note that the Pugpig client will never fetch the same asset twice if it is included in multiple manifests.

If you've completed step 4, you should be able to download an edition, go offline, and still view all the contents of the edition.




Step 5: Pugpig Distribution Service

There are a few things that you do not need to worry about at this stage, as they are handled by the Pugpig distribution service. These include:

  • Optimizing batched downloads
  • Selling through the iOS App Store
  • Securing your content
  • Implementing push notifications
  • Sending iOs push newsstand notifications
  • iOS tracking with Flurry

If you have any questions regarding these features, please feel free to send us a ticket.

 
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk