IMPORTANT SECURITY ALERT : Pym users, we’ve released an update that closes a potential security hole. We recommend everyone update to 1.3.2 as soon as possible. More information here.

• What is this?
• Assumptions
• What's in here?
• Bootstrap the project
• Hide project secrets
• Run the project
• Test the project
• Build the project
• Update the project
• Deploy the project
• Versioning
• What is the loader script for? Why do we need it?
• License and credits
• Additional contributors

Using iframes in a responsive page can be frustrating. It’s easy enough to make an iframe’s width span 100% of its container, but sizing its height is tricky — especially if the content of the iframe changes height depending on page width (for example, because of text wrapping or media queries) or events within the iframe.

Pym.js embeds and resizes an iframe responsively (width and height) within its parent container. It also bypasses the usual cross-domain issues.

Use case: The NPR Visuals team uses Pym.js to embed small custom bits of code (charts, maps, etc.) inside our CMS without CSS or JavaScript conflicts. See an example of this in action.

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.

The project contains the following folders and important files:

• dist -- Unminified and minified versions of pym.js library and the pym-loader.js loader.
• examples -- Collection of working use cases for pym.js
• src -- Source files for this project
• test/pym -- Unit testing specs for pym.js
• test/pym-loader -- Unit testing specs for pym-loader.js
• test/html -- Child pages used for pym.js testing
• test/html-fixtures -- HTML templates for testing loader through the htmljs karma preprocessor
• .travis.yml -- Travis CI config file
• Gruntfile.js -- Grunt.js task runner config file
• karma.conf.js -- Karma runner configuration file
• karma.conf-sauce.js -- Karma runner configuration file for Sauce Labs
• nprapps_tools -- NPR Deployment tools to the CDN

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

brew install node

Then bootstrap the project:

npm install

In order to do your own tests in Sauce Labs (optional) you will need to have a Sauce Labs account (to their credit, they have a free tier for open source projects).

Once you have an account you will need to copy the example credentials file in the sauce folder to the actual credentials that will be used.

$ cd sauce
$ cp sauce_cred_sample.json sauce_cred.json

Edit the sauce_cred.json file to fill in your USERNAME and ACCESSKEY from user settings.

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.

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 pym.js
$ grunt server

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

The release process is documented on the wiki.

We have introduced unit testing for Pym.js starting with the 1.0.0 release. The Pym.js testing suite uses a combination of Karma, Jasmine and Sauce Labs to improve our browser coverage (Sauce Labs provides a nice free tier solution for opensource projects)

Requires Chrome and Firefox installed on your machine

In order to run unit tests each time a change is detected, run:

grunt test

In order to run a one-off complete test suite, run:

npm test

First you will need to make a copy the credentials sample file sauce_cred_sample.json, call it sauce_cred.json, and update your Sauce Labs USERNAME and ACCESSKEY that you will obtain once you have set up an account with Sauce Labs.

$ cd sauce
$ cp sauce_cred_sample.json sauce_cred.json

In order to run unit tests each time a change is detected, run:

$ grunt sauce

In order to run a one-off complete test suite, run:

$ npm run sauce

For local testing the list of browsers to use can be modified on sauce/saucelabs-local-browsers.js. We use Travis CI for our continuous integration. When Travis is invoked it will use sauce/saucelabs-browsers.js as the list of browsers to test on.

A note around testing Pym.js on Sauce Labs, since the architecture of the tests with Travis and Sauce Labs creating tunnels between VMs is a bit unreliable in terms of timing in some random cases the response to a test case will not arrive in time and the test will fail due to a Timeout. We have tried to configure longer Timeouts for that error not to happen but still we find them during some test runs.

We have decided to create a small test suite using Travis own VM capabilities to test Pym.js on Firefox and declared the build successful if those tests pass. After that in the after_success section of the Travis CI configuration we launch the Sauce Labs tests but that will not affect the result of the build process.

So If you see some of the Browsers in the Sauce Labs Matrix as failures that is, presumably, the reason for it. We are in contact with Sauce Labs to figure out if there's a way around this issue.

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

$ grunt

We generate two copies of the pym and pym-loader libraries due to some really tight length requirements when embedding scripts in the homepage of some of our users CMSs.

• p.v1.m.js is a copy/alias of pym-v1.min.js
• pl.v1.m.js is a copy/alias of pym-loader-v1.min.js

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

• Make the needed changes on code and test it thoroughly in NPR.org and member stations test sites.
• Change the version according following the semantic versioning pattern inside package.json and bower.json.

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/pym.js/X.X.X/ on your browser.

Where X.X.X is the actual version defined in package.json

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 pym.js
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/

Note: Pym.js is used widely outside of NPR so test thoroughly and use semantic versioning in order not to impact existing applications

Starting with Pym.js v1.0.0, 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 pym 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.

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

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

• The same can be said for the pym-loader. pym-loader.v1.js and pym-loader.v1.min.js will have the latest version of pym-loader in that MAJOR version.

NPR will host and serve pym.js and 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.

Pym.js v1.0.0 development has been driven by a change needed to extend the ability to use Pym.js in certain CMSs used by NPR member stations and other use cases found by our collaborators that broke the loading process of loading Pym.js in common cases and thus made the embeds unusable.

We have decided to separate the particular needs of the Pym.js loading process in these special situations into a separate script that will act wrap and load Pym.js for these cases instead of polluting the Pym.js library itself with special needs of certain CMSs.

We want to keep Pym.js loading and invocation as manageable as possible. Due to the extensive use of Pym.js in many different environments, we encourage implementers to create special loaders if their integrations require it.

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

Pym.js was built by the NPR Visuals team, based on work by the NPR Tech Team and Ioseb Dzmanashvili. Thanks to Erik Hinton for suggesting the name.

See CONTRIBUTORS