Pym.js v1.0.0 release - what do you need to know
The NPR Visuals Team happy to announce the release of
Pym.js v1.0.0. We want to share with all of you the goals that we hope to achieve with it and the design process that led us to the new release.
But wait, what is Pym.js for?
Pym.js embeds and resizes an iframe responsively (width and height) within its parent container while bypassing the usual cross-domain related issues.
Pym.js v1.0.0 Goals
Pym.jsloading issues and integration problems with certain CMSes.
- Add automated unit testing to improve reliability moving forward.
Pym.jsthrough a canonical CDN, but leave room for the library evolution.
- Clean up small issues and merge pull requests made by the community.
Loading Pym.js in complicated environments
Pym.js v1.0.0 development has been driven by a change needed to extend the ability to use
Pym.js in certain CMSes used by NPR member stations and other use cases found by our collaborators. The Pym.js loading process broke for these users and thus made the embeds unusable.
pjax to load content, and still others use
RequireJS to load libraries. Since
Pym.js was designed as a library with support for inclusion using
CommonJS, we have encountered certain CMSes scenarios where
Pym.js broke in some cases or did not load at all.
Pym.js v1.0.0 development was geared towards solving these issues.
That’s why we created
pym-loader.js, an additional script that acts as a wrapper to deal with all the nitty gritty details to successfully load
Pym.js in many common cases.
pym-loader.js was developed after much thought and discussion with developers using
We have decided to separate the particular needs of the
Pym.js loading process in these special situations into a separate script that will wrap and load
Pym.js for these cases instead of polluting the
Pym.js library itself with special needs of certain CMSes.
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.
If you have a reasonable amount of control over your CMS’s
Pym.js implementation, we recommend the raw inclusion of
Pym.js. If you do not have that control over your CMS, are having problems loading
Pym.js directly or just prefer to feel more protected against future changes to your CMS then you can use the loader script.
Having some unit testing in place for
Pym.js will allow us to be more reliable and efficient moving forward with the maintenance of the library. So in this v1.0.0 release we have introduced unit testing for
The 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 open source projects).
We have found some caveats using Sauce Labs as a testing platform for open source projects. Sauce Labs manages parts of its services, specifically badges, with a user-based approach instead of a project based approach. If you need to test more than one open source project you will need to rely on creating virtual users which is just not a good long term solution.
Having talked to Sauce Labs support about it, they have pointed us to their product ideas website to ask for that feature to be included. If you work with open source projects and would like to be able to include tests for multiple projects under the same user, go ahead and support our feature idea.
Starting with Pym.js v1.0.0, the library 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.
NPR will host and serve
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. Specifically, you can link to:
- http://pym.nprapps.org/pym.v1.min.js (minified)
- http://pym.nprapps.org/pym.v1.js (uncompressed)
To minimize the impact on our current and future customers, on the production side of
Pym.js we are only going to keep the major version exposed. That way 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.
If for any reason you want to point to a particular release instead, just head over to our Github release page and download the version you are looking for.
Issues & Pull Requests
Pym.js v1.0.0 release we have fixed 7 open issues and integrated 7 pull requests.
Most of the issues were related with better documentation and fixing integration problems with various CMSes.
Most of the Pull Requests dealt also with adding more configuration options to
Pym.js as well as solving integration issues.
We hope that this release of
Pym.js will extend its ability to be used by NPR member stations and other customers thanks to the new
Interested in using
Pym.js? Please refer to the user documentation and API documentation.
We would like to thank all of our collaborators/contributors for their insightful feedback and thorough discussion, a special shout-out goes to Hearken for the progress on their
Pym.js fork and willingness to merge together so that we do not diverge and thus help us grow