Resize an iframe responsively depending on the height of its content and the width of its container.
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.
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.jssrc -- Source files for this projecttest/pym -- Unit testing specs for pym.jstest/pym-loader -- Unit testing specs for pym-loader.jstest/html -- Child pages used for pym.js testingtest/html-fixtures -- HTML templates for testing loader through the htmljs karma preprocessor.travis.yml -- Travis CI config fileGruntfile.js -- Grunt.js task runner config filekarma.conf.js -- Karma runner configuration filekarma.conf-sauce.js -- Karma runner configuration file for Sauce Labsnprapps_tools -- NPR Deployment tools to the CDNNode.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.
Starting with Pym.js v1.0.0, the project follows the semantic versioning pattern MAJOR.MINOR.PATCH.
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
FAQs
Resize an iframe responsively depending on the height of its content and the width of its container.
The npm package pym.js receives a total of 0 weekly downloads. As such, pym.js popularity was classified as not popular.
We found that pym.js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.