Name: pymchild-scroll-visibility
Owner: NPR visuals team
Description: Small library to be included on pym child pages that performs visibility calculations based on the parent information sent in a custom iframe event.
Created: 2017-07-20 22:49:02.0
Updated: 2017-07-20 22:51:17.0
Pushed: 2017-07-21 20:21:47.0
Homepage: null
Size: 20
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
After the release of Pym.js version 1.3.0, Pym has added native optional support for scroll tracking, allowing the child pages to have all the information needed to determine if one of the child's element is currently on the viewport or not.
pymchild-scroll-visibility is a small library built for being included on the pym embedded child pages that take advantage of this new capability to make the appropriate calculations to invoke a callback function if the supplied element is currently visible.
In order for this to work you'll need to set you pym parent to opt into scroll tracking, read more about how to do that here.
Once that is set up, you need to create a Tracker for each element that you want to track and provide a callback function to be run when the element is visible:
tracker = new PymChildScrollVisibility.Tracker('example', function(id) {
console.log(id, 'visible')});
And also you'll need to listen in the child to updates from the parent on scroll position and perform a check to see if the visibility has changed once received.
hild.onMessage('viewport-iframe-position', function(parentInfo) {
tracker.checkIfVisible(parentInfo);
Optionally you can also pass it another callback function to be invoked if the element is visible for a configurable period of time (signaling it is read). Like this:
tracker = new PymChildScrollVisibility.Tracker('example', onVisible, onRead, {read_time: 1000});
onVisible = function(id) {
console.log(id, 'visible');
onRead = function(id) {
console.log(id, 'read');
Note: If you do pass a read callback, you'll need to make sure that the throttle for the scroll defined on the parent is lower than the read_time you are passing when instantiating the tracker for each element. If you don't, you'll most probably get spurious read callback invocations since the scroll position if not updated frequently enough.
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 pymchild-scroll-visibility library.examples – Collection of working use cases for pymchild-scroll-visibility.src – Source files for this projectGruntfile.js – Grunt.js task runner config fileNode.js is required. If you don't already have it, get it like this:
install node
Then, Make sure you have grunt installed globally
install -g grunt
Then bootstrap the project:
install
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 check pymchild-scroll-visibility 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.
pymchild-scroll-visibility
unt server
Grunt configuration is included for running common development tasks.
Javascript can be linted with jshint:
t jshint
Unminified source can be regenerated with:
t concat
Minified source can be regenerated with:
t uglify
API documention can be generated with jsdoc:
t jsdoc
We use grunt tasks to build the project into the dist folder. Linting JS, uglyfing, etc.
unt
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:
unt server
and navigate to http://localhost:9000/api/pymchild-scroll-visibility/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 this library is needed the workflow would be:
We use grunt tasks to build the project into the dist folder. Linting JS, uglyfing, etc.
unt
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:
unt server
and navigate to http://localhost:9000/api/pymchild-scroll-visibility/X.X.X/ on your browser.
Where X.X.X is the actual version of the loader defined in package.json.
The project follows the semantic versioning pattern MAJOR.MINOR.PATCH.
Released under the MIT open source license. See LICENSE for details.
pymchild-scroll-visibility.js was built by the NPR Visuals team