NPR custom pym loader - Handles special libraries for NPR.org while still being reusable by member stations
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
examples
nprapps_tools
src
.gitignore
CHANGELOG
Gruntfile.js
LICENSE
README.md
jsdoc.conf.json
package.json

README.md

npr-pym-loader

What is this?

NPR custom pym loader that handles specific library needs inside npr.org while still being usable by our member stations.

Being able to use the same loader script inside NPR.org and inside our member station websites is a goal that we need to prepare to in advance so that we can profit for future developments in our CMS API as well as avoiding separation in our code.

Using an external script together with versioning will allow us moving forward to be able to patch assets embedded in a centralized fashion.

If you do not know what pym.js is and why it may be useful for you please check pym.js documentation. You'll see the standard loader in that documentation which follows the same practices as we used in our custom one.

But we needed some flexibility to account for NPR.org specific needs and did not want to pollute the standard pym-loader with NPR specific needs...that's why we have created a custom loader to account for our specific needs.

Important: The version of pym that this loader points to is defined in package.json if a MAJOR release of pym is added then we should also change it here.

Assumptions

The following things are assumed to be true in this documentation.

  • You are running OS X.
  • You have installed Node.js.
  • You have installed Grunt globally.

For more details on the technology stack used in NPR Visuals' app template, see our development environment blog post.

Modern versions of Windows and Linux should work equally well but are untested by the NPR Visuals Team.

What's in here?

The project contains the following folders and important files:

  • dist -- Unminified and minified versions of the library.
  • examples -- Collection of working use cases for npr-pym-loader.js
  • src -- Source files for this project
  • Gruntfile.js -- Grunt.js task runner config file
  • nprapps_tools -- NPR Deployment tools to the CDN

Bootstrap the project

Node.js is required. If you don't already have it, get it like this:

brew install node

Then, Make sure you have grunt installed globally

npm install -g grunt

Then bootstrap the project:

npm install

Hide project secrets

In this project the only project secrets that we have are the Sauce Labs credentials to secure a tunnel between Travis and Sauce Labs used in our continuous integration process. Those keys have been encrypted through Travis; you can read more about that process here

Project secrets should never be stored anywhere else in the repository. They will be leaked to the client if you do. Instead, always store passwords, keys, etc. in environment variables and document that they are needed here in the README.

Run the project

In order to run pym.js the best approach is to fire up a local webserver and go to the examples to see it in action.

The included server includes livereload so each time you change something on the examples or src folder the server will refresh the page for you.

$ cd npr-pym-loader
$ grunt server

Development tasks

Grunt configuration is included for running common development tasks.

Javascript can be linted with jshint:

grunt jshint

Unminified source can be regenerated with:

grunt concat

Minified source can be regenerated with:

grunt uglify

API documention can be generated with jsdoc:

grunt jsdoc

Optional scroll tracking

After the release of Pym.js v1.3.0 there's an optional native support of scroll tracking on Pym.js.

This is useful if the child page needs to do some actions based on the position of some of its elements on the current viewport, i.e., lazyload of assets.

In order to use it you'll need to include some data-atributes on the container where Pym.js will include the child iFrame.

  • data-pym-trackscroll: to signal Pym that you want it to track the scroll on the parent page.
  • data-pym-scrollwait: If you want to override the default throttle wait on the scroll. Default: 100ms

For example:

<p data-pym-loader data-pym-trackscroll data-pym-scrollwait="40" data-child-src="child.html" id="example">Loading...</p>
<script type="text/javascript" src="npr-pym-loader.js"></script>

In order to see this functionality in action the easiest way is to fire up the local server.

$ cd npr-pym-loader
$ grunt server

Then, open the trackscroll example.

If you want to see it action on NPR.org take a look at this story.

Build the project

We use grunt tasks to build the project into the dist folder. Linting JS, preprocessing, uglyfing, etc.

$ grunt

That execution will create a minified and unminified version of our custom folder on the dist folder.

It will also generate an API documentation if you want to check that out run:

$ grunt server

and navigate to http://localhost:9000/api/npr-pym-loader.js/X.X.X/ on your browser.

Where X.X.X is the actual version of the loader defined in `package.json

Update the project

NPR only If a new version of the npr pym loader is needed the workflow would be:

  • Make the needed changes on code and test it thoroughly in NPR.org and member stations test sites.
  • Verify if versions of pym and carebot used need to be updated
  • Change the version according following the semantic versioning pattern.

We use grunt tasks to build the project into the dist folder. Linting JS, preprocessing, uglyfing, etc.

$ grunt

That execution will create a minified and unminified version of our custom folder on the dist folder.

It will also generate an API documentation if you want to check that out run:

$ grunt server

and navigate to http://localhost:9000/api/npr-pym-loader.js/X.X.X/ on your browser.

Where X.X.X is the actual version of the loader defined in `package.json

Deploy the project

After having build the new version of the library see above.

NPR only If a new version of the projects is needed the workflow would be:

cd nprapps_tools
mkvirtualenv npr-pym-loader
pip install -r requirements.txt
fab deploy

This will deploy whatever is inside the dist folder to S3 and make it available through a CDN at https://pym.nprapps.org/

Versioning

The project follows the semantic versioning pattern MAJOR.MINOR.PATCH.

  • MAJOR version changes for backwards-incompatible API changes.
  • MINOR version for new backwards-compatible functionality.
  • PATCH version for backwards-compatible bug fixes.

To minimize the impact on our current and future customers, on the uncompressed and on the minified production side of npr-pym-loader we are only going to keep the major version exposed. That we can apply PATCHES and MINOR version changes without any change being made on our customer's code but we maintain the possibility of new major releases that are somewhat disruptive with previous versions of the library.

  • npr-pym-loader.v1.0.0 and npr-pym-loader.v1.1.1 will both end up being minified into the same npr-pym-loader.v1.min.js.

  • You can safely assume that npr-pym-loader.v1.js and npr-pym-loader.v1.min.js will have the latest version of pym in that MAJOR version.

NPR will host and serve npr-pym-loader.js through a canonical CDN at pym.nprapps.com. We recommend that you link directly there to benefit instantaneously from the patches and minor releases.

License and credits

Released under the MIT open source license. See LICENSE for details.

npr-pym-loader.js was built by the NPR Visuals team