Follow

Web

This document guides you through the basic set up of a Pugpig Web Reader (Magazines or Continuous). Please note this setup is only applicable if you do not use our Pugpig Distribution product and want to host the web reader on your own servers or embed into an existing website.

Getting Started

Here are some step-by-step instructions to get started:

  1. Download the latest Pugpig for Magazines Web version available here 
  2. Configure your Web Reader - see section
  3. Theme your app - see section
  4. Update the copy - see section
  5. Update the assets - see section
  6. Extending your app (optional) - see section
  7. Include your Pugpig licence - see section
  8. Setup your app in the Apple App store - see section
  9. Submit, and you're done!

 


 

Config

Unzip your download (Step 1) and in the folder open the provided index.html file using a HTML editor like Sublime.

Locate the following line:

/* PUGPIG_WEB_CONFIG_HERE */

This is where you will insert all related configuration for your Web Reader.

First you need to enter your content endpoint, add the following line:

feed: 'http://demo.pugpig.com/myfeed/editions-atom.xml'

This allows you to specify which feed the application should use as its data source. This can be either an OPDS feed containing various editions or an atom feed for a single edition. Replace the http:// part with your own OPDS feed URL which should be on the same domain as the web reader. 

If Pugpig for Web is on the same domain as content endpoint, you should use a relative URL to point to the feed.

If Pugpig for Web is on the same domain as content endpoint, you should use a relative URL to point to the feed.

If Pugpig for Web is on a different sub domain as the content endpoint you will need to setup Cross Origin Resource Sharing (CORS) headers (http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) on several assets (see hosting section below).

Next, upload to your server, the URL will be http://mydomain/folder/ 

 


Auth Endpoints (if applicable)

In the application config file (app/scripts/app-config.js) modify:

signInUrl - This is posted to to get the users token

verifySubscriptionUrl - This is posted to to retrieve a list of the editions that a user has access to and determine if their subscription is active or lapsed

editionsCredentialsUrl - This is posted to to determine if the user has the credentials for a specific edition

 

Installing your Pugpig licence

Obtain a licence key from Kaldor

Modify license in the application config file (app/scripts/app-config.js)

If this isn't filled in and a valid license the application will display a message in the Notification Panel

 


 

Google Analytics Key

This can be entered in app-config.js. The web reader provides support for a single key, or multiple keys. This is entered by modifying gaAccount in the application config file.

One key:

  • gaAccount: 'GA Key'

Multiple keys:

  • gaAccount: ['GA key one', 'GA key two']

 


 

Hosting

The Web Reader is delivered as a set of static HTML, JavaScript and CSS files. These should be publically available using a friendly, consumer facing domain name. These files must either be on the same domain, or appear to be on the same domain (see Use the CDN to have a single domain), as the content endpoint. If this is not possible, it can also be configured so that the web reader and content endpoint are on different sub domains (see Using sub-domains). The web reader static files should be served via your CDN if possible. 

The following CORS headers are required on the atom feed responses:

  • Access-Control-Allow-Origin: http://domain.com
  • Access-Control-Allow-Credentials: true
  • Access-Control-Allow-Headers: authorization

The following CORS headers are required on the authentication endpoint responses:

  • Access-Control-Allow-Origin: http://domain.com

IMPORTANT: Replace 'domain.com' with the domain name that the web reader is hosted on.

You will also need to put the following line in your content’s template and into the web reader’s index file:

<script>document.domain = 'domain.com';</script>

Replace domain.com with the top level domain for any sub domains hosting the web reader and the content.

Use the CDN to have a single domain

An alternative option is to use a CDN with multiple origins. This can be done with most CDNs, including Cloudfront. So, for example, using our Drupal server URL structure you could have rules saying:

  • /editions.xml uses API origin
  • /edition/* uses API origin
  • /itunes/* uses API origin  (and any other receipt validation)
  • everything else points to the Web Reader static file bucket

 


 

Theming

All of the CSS in Pugpig for Web is generated with Sass. It uses the indented syntax which is documented here http://sass-lang.com/docs/yardoc/file.INDENTED_SYNTAX.html To update the CSS you will need to run a Sass compiler. This can be done in several ways that are documented here http://sass-lang.com/install

At Kaldor we use the command line Sass compiler. To do this, you need to install the Sass Ruby Gem via the following command:

gem install sass

During development, the process to compile Sass is to cd into your web reader directory and run:

sass --watch styles:styles --style expanded

This command will make sure that whenever you change a Sass file, your CSS will be recompiled and will be easy to read due to the 'expanded' style being used.

When you're ready to deploy to production, you will want to cd into the styles directory and run:

sass main.sass:main.css --style compressed

This command will not only compile your Sass to CSS, but it will also minify your CSS reducing the overall file size of main.css. Ideally this will be handled by a build system rather than being a manual process.

 


 

Customising styling

Pugpig for Web has been built in a way that allows you to customise the styling of certain elements without modifying the actual CSS styles for an element. The idea is that within app/styles/theme there are various .sass files that contain Sass variables for easy customisation. These theme files are named to relate to the view the options are for. For example if I wanted to modify the Edition Selector, I would modify app/styles/theme/edition-selector.sass

 


 

Switching between themes

Pugpig for Web has a mechanism for switching between the default theme and alternate themes. In app/styles/theme/base.sass there is a variable definition like so:

$theme:default

By default, this variable is not actually doing anything. The idea is that if you wish to have an alternate theme is you would change the variable definition to, e.g.

$theme: alternate

Then you can branch your variable definitions like so:

$something:10px

@if $theme == alternate
 $something:2px

We can now override the default variables and this can be done for as many alternate themes as you would like. In your console you should be able to see a debug line in case you're not sure what theme is being used during compilation:

/Applications/MAMP/htdocs/pugpig-web/app/styles/theme/_base.sass:6 DEBUG: Theme is currently default theme

 


 

Customising colour scheme

Customising colour schemes is done in the same way as all of the theme customisation but it is all handled in app/styles/theme/base.sass . The way the theme is defined is with five base colours:

$theme-color-one: $blue
$theme-color-two: $gray
$theme-color-three: $dark-blue
$theme-color-four: $near-black
$theme-color-five: $light-gray

These colour variables, e.g. $blue, are mapped to hexadecimal values above these variable definitions. All human readable colours should be defined at the same time. Colours should not be specified with hexadecimal values within your theme. Instead we define the human readable colour in the base theme file and then use that value.

/**
* Colours - Add any extra human readable colors you require for your theme here
*/
$blue:#4a6eb4 $gray:#717780 $dark-blue:#273b5b $near-black:#202123 $light-gray:#a5aeb8 $orange:#e3743e $dark-gray:#636460 $beige:#cfcdc1 $red:#dd5853

 


 

Customising Fonts

By default, Pugpig for Web uses a web font served from Google Fonts throughout the UI. If you wish to change the font that is being used, this can be done by modifying the following line in app/styles/theme/_typography.sass

$google-webfont-family-param:"Merriweather+Sans"
$google-webfont-font-family:"Merriweather Sans",sans-serif

You are able to use any of the fonts available at http://www.google.com/fonts/ Say for example I wished to change from Merriweather Sans to Roboto, I would make the following amend:

$google-webfont-family-param:"Roboto"
$google-webfont-font-family:"Roboto",sans-serif;

Basically, the $google-webfont-family-param variable should be set to the value that family equals in the embed instructions on Google Fonts, e.g. @import url(http://fonts.googleapis.com/css?family=Roboto); would mean I want to set it to Roboto. Any font faces with a space in their name will need the spaces swapped out with a plus sign. Again this matches the Google Fonts embed instructions, e.g for Roboto Slab: @import url(http://fonts.googleapis.com/css?family=Roboto+Slab);

The $google-webfont-font-family variable should be set to the value Google Fonts provided for you to use in your CSS, e.g. 'Roboto Slab', serif

Should you not wish to use a Google Font, you will want to edit the app/styles/theme/_typography.sass file. Change the following line:

$use-google-fonts: true

To be:

$use-google-fonts: false

You will also want to change:

$font-family: 'OpenSans'
+bulletproof-font-face( $font-family, 'OpenSans-Regular-webfont' )

To reflect the font you wish to use.

Out of the box, Pugpig for Web has OpenSans-Regular-webfont.{woff,ttf,svg,oet} inside its fonts directory. It is this filename that dictates the second parameter to the bulletproof-font-face mixin. It should be identical with the file extension removed. The $font-family variable value is less important, but it makes sense to set it to the name of the font you're using.

 


 

Customising logo

There are three different places where the brand.png file within app/images will be displayed. These are, top left on the edition selector view, in the login modal and in the table of contents on the article viewer. The way the customisation of this works is that in app/styles/theme/_base.sass we define the size of our logo containers:

$small-brand-width:100px
$small-brand-height:32px

$large-brand-width:500px
$large-brand-height:240px

 

There are two styles of the brand logo, the small brand and the large brand. Small is in the table of contents and on the edition selector and the large one is displayed in the login modal. What we are actually specifying the size of is a div to contain the brand, this is achieved using background-size: contain (https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) on the element. The $large-brand-width variable should not exceed 500px in width as this is the maximum width available within the login modal. In both instances, the logo will be positioned in the center of the container we have defined.

 

 

Customising login modal background image

To customise the login modal's background image, you need to edit the following line in app/theme/modals/login.sass:

$login-modal-background-image:"login-bg.jpg"

The application will handle the sizing of this image using background-size: cover (https://developer.mozilla.org/en-US/docs/Web/CSS/background-size). This will ensure that the entire modal background is filled with the image whatever its size is.

 

Application config file

There are various customisations that we can make by modifying our application config file (app/scripts/app-config.js).

Options

  • feed - Allows you to specify which feed the application should use as its data source. This can be either an OPDS feed containing various editions or an atom feed for a single edition
  • license - If this isn't filled in and a valid license the application will display a message in the Notification Panel
  • version - This specifies the version of the configuration file. If this changes then the application config stored in the users local storage will be updated. If the version number remains the same the user will instead use the local storage configuration. If you need to get the application config to update, update this version number. This will not overwrite the users own settings, e.g. if they have set custom dimensions or a specific font size.
  • mode - Sets the mode that the application runs in. Can either be window.PUGPIGWEB.Modes.COMMERCIAL or window.PUGPIGWEB.Modes.PREVIEW . Commercial mode should be used unless the application is being used as a preview tool.
  • customText - Each of the properties of the customText option modify different strings of text or HTML within the application.
  • subscriptionInputs - Adding new objects to this array allow you to customise the subscription login inputs that are shown to the user in the login modal. The label key value pair dictates the placeholder text within the input and the name is used as the input name and will be used as the key name for the value entered in the input when the form is submitted.
  • signInUrl - This is posted to to get the users token
  • verifySubscriptionUrl - This is posted to to retrieve a list of the editions that a user has access to and determine if their subscription is active or lapsed.
  • editionsCredentialsUrl - This is posted to to determine if the user has the credentials for a specific edition
  • addThisServices - Adding new objects to this array allows you to add new social networking services to the Social view. Label is used in the Social view at the text for the item and the code refers to the services listed on http://www.addthis.com/services/liste.g. If I wanted to add Pinterest I would add an object that looks like
    {
       label: 'Pinterest',
       code: 'pinterest'
    }
  • imageViewingEnabled - Determines if automatic tap to fullscreen is enabled on images. The logic is identical to the logic described here Tap for Full Screen Images 
  • commercialViewport - By adding a width or a height key value pair to this object, you can define fixed dimensions for the viewport in the Article Viewer. If these properties to not exist, the viewport will be 100% of the browser width and the viewport will expand to the height of the articles content. If you wanted a fixed pixel height you would add height: 500 to the object.
  • fontSizeIndex - Sets the default font size index. This index refers to the fontSizes array. If a user changes the font size they want to use, this will be overridden.
  • fontSizes - Modifier values for the three font sizes you can select in the Settings panel. A value of '1.125' indicates that the font size will be adjusted to be 112.5% of the base font size.
  • deviceIndex - Defines the default device index. This index refers to the devices array. If a user changes the device they want to preview a template with, this will be overridden.
  • devices - An array of device objects. Any devices added require a name, orientation, width and height property using the same types for the values as the provided examples. This array is only used in preview mode Custom dimensions must be the last array item.

 

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

Comments

Powered by Zendesk