- What is this?
- Assumptions
- What's in here?
- Bootstrap the project
- Hide project secrets
- Run the project
- Optional scroll tracking
- Build the project
- Update the project
- Deploy the project
- Versioning
- License and credits
- Additional contributors
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.
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 the library.examples-- Collection of working use cases for npr-pym-loader.jssrc-- Source files for this projectGruntfile.js-- Grunt.js task runner config filenprapps_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, Make sure you have grunt installed globally
npm install -g grunt
Then bootstrap the project:
npm install
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 npr-pym-loader
$ 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
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.
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
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
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/
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.
Released under the MIT open source license. See LICENSE for details.
npr-pym-loader.js was built by the NPR Visuals team