Skip to content
Asynchronously write javascript, even with document.write.
JavaScript Visual Basic
Find file
Failed to load latest commit information.
src refactor(write-stream): refactor to remove redundant code (#184) Apr 29, 2016
test test(ci): fix coveralls reporting (#181) Apr 28, 2016
.codeclimate.yml chore(coverage): publish coverage to codeclimate (#182) Apr 28, 2016
.editorconfig docs(LICENSE): update date in LICENSE Apr 28, 2016
.eslintignore feat: big update to v2 with many changes (#138) Apr 18, 2016
.eslintrc.js feat: big update to v2 with many changes (#138) Apr 19, 2016
.gitignore chore(build): clean out dist and add sourcemaps (#179) Apr 27, 2016
.jscsrc feat: big update to v2 with many changes (#138) Apr 19, 2016
.npmignore chore(build): clean out dist and add sourcemaps (#179) Apr 27, 2016
.travis.yml chore(coverage): publish coverage to codeclimate (#182) Apr 28, 2016
AUTHORS feat: big update to v2 with many changes (#138) Apr 19, 2016
CHANGELOG.md fix(parsing): fix problem with iframe src containing badly quoted dou… Apr 22, 2016
CLA.md docs(CLA): update company in CLA (#170) Apr 25, 2016
CONTRIBUTING.md feat: big update to v2 with many changes (#138) Apr 19, 2016
CONTRIBUTORS feat: big update to v2 with many changes (#138) Apr 19, 2016
LICENSE docs(LICENSE): update date in LICENSE Apr 28, 2016
README.md fix(readme): fix cdn path in README Apr 28, 2016
bower.json feat: big update to v2 with many changes (#138) Apr 19, 2016
gulpfile.babel.js chore(build): clean out dist and add sourcemaps (#179) Apr 27, 2016
package.json chore(package): update eslint to version 2.9.0 (#187) Apr 29, 2016
webpack.config.babel.js chore(build): clean out dist and add sourcemaps (#179) Apr 27, 2016

README.md

Overview

Version License Build Status Code Climate Coverage Dependencies Commitizen friendly semantic-release Gitter

Remote scripts, especially ads, block the page from doing anything else while they load. They contribute a large % to load times which affects your bottom line. Asynchronous ads do not block the page and can be delivered after core content - Async FTW.

Why is it so hard to deliver ads asynchronously? Because they may contain calls to document.write, which expects to be handled synchronously. PostScribe lets you deliver a synchronous ad asynchronously without modifying the ad code.

Approach

Other tag writing libraries exist (see alternatives), but PostScribe is novel in its use of what we call DOM Proxies, a way to ensure that the content is written as close to the way the browser would natively write the content with document.write/innerHTML. Read: it behaves just like the browser would, without convoluted parsing or hacks.

For more information:

Getting Started

PostScribe overrides document.write. It is best and safest to use PostScribe after DOM is ready.

Installation

Browser

If you just want to use the script without installing anything, use the following to load the script from cdnjs:

<script src="https://cdnjs.cloudflare.com/ajax/libs/postscribe/2.0.5/postscribe.min.js"></script>

NPM

You can include postscribe using npm:

npm install --save postscribe

Postscribe runs in browsers, so this assumes you're using a module bundler like webpack, Browserify, JSPM or Rollup to consume CommonJS modules.

Bower

You can include postscribe using bower:

bower install --save postscribe

Accessing

ES6/ES2015

import postscribe from 'postscribe';

AMD

define(['postscribe'], function(postscribe) {

});

CommonJS

var postscribe = require('postscribe');

Usage

To append html to #mydiv:

postscribe('#mydiv', '<h1>Hello PostScribe</h1>');

In general:

postscribe(element, html, options);
  • element: a DOM Element, jQuery object, or id selector (e.g. "#mydiv")
  • html: an html string or a function that takes a DOM Document and writes to it.
  • options: a hash of options
    • done: a callback that will be called when writing is finished.

If you just want to mess around, include the js files at the top of an html page that contains the following:

<div id="mydiv"></div>
<script type="text/javascript">
  postscribe('#mydiv', '<h1>Hello PostScribe</h1>');
</script>

How to use PostScribe to render an ad after load

Where normally you would have

<div id="ad"><h5>Advertisement</h5>
  <script type="text/javascript">
    // Build url params and make the ad call
    document.write('<script src=doubleclick_url_with_params><\/script>');
  </script>
</div>

Instead, remove the ad call and close the div

<div id="ad"><h5>Advertisement</h5></div>

<script type="text/javascript">
  // jQuery used as an example of delaying until load.
  $(function() {
    // Build url params and make the ad call
    postscribe('#ad', '<script src=doubleclick_url_with_params><\/script>');
  });
</script>

There are some hooks you may pass as the third argument. For example:

<script type="text/javascript">
  // jQuery used as an example of delaying until load.
  $(function() {
    postscribe('#ad', '<script src=doubleclick_url_with_params><\/script>', {
      done: function() {
        console.info('Dblclick script has been delivered.');
      }
    });
  });
</script>

See the beginning of postscribe.js for a complete list.

FAQ

Does it work with jQuery, Prototype, Backbone, Underscore, jQuery UI, YUI, mooTools, dojo, etc.?

Yep. It neither depends on nor conflicts with any of the existing popular javascript frameworks.

Does it work with another tag writing library on the page?

No. Only one tag writer at a time.

Who is using it

This project was originally developed at Krux as part of its SuperTag product. There it has been battle tested on high-profile sites like The New York Times, The Wall Street Journal, NBCU, and hundreds of others. It is actively maintained by Krux.

Browser Compatibility

PostScribe was designed to behave as closely to the native document.write/innerHTML does as possible, and we've taken great care to make sure that it works on every browser we can get our hands on. We expect it to work on every browser built after 2009. There are over 500 unit tests that run on every commit. PostScribe is thoroughly tested and known to work well in the following browsers:

  • Firefox 4+
  • Chrome 10+
  • Safari 5.0+
  • Opera 10.0+
  • Internet Explorer 8+
  • iPhone/iPad and other WebKit-based browsers

Note that we do not provide any support for Internet Explorer versions earlier than IE8.

Alternatives

We've stood on the shoulders of giants with our work, and there are other alternative approaches to solve this problem. Shout out to the best ones we found:

If you would like your project to be added to this list, file an issue and we'd be happy to.

Help/Bugs/Requests

We ♥ bug reports.

Have a problem? Need help? Would you like additional functionality added? We use GitHub's ticket system for keeping track of these requests.

Please check out the existing issues, and if you don't see that your problem is already being worked on, please file a new issue. The more information the better to describe your problem.

Contributing

We ♥ forks and pull requests.

Please see CONTRIBUTING.md for full details.

Environment

The project requires nodejs (>=5.6) and npm (>=3.6.0) for development. It has no runtime dependencies.

Developing

Check the code out and install the development dependencies using:

npm install

Building

To build the code, run

npm run build

Linting

We use ESLint and JSCS to do static analysis of the JavaScript and keep things smelling good. To run both, use:

npm run lint

Testing

Using travis-ci, the unit tests are run on every commit using PhantomJS to run the tests with a real browser.

To test the code locally, you can use:

npm test

To run tests in Test-Driven-Development mode, where the test will be run after every change, use:

npm run tdd

To run the cross-browser tests, use:

npm run test:cross-browser

Issue Guidelines

Please either add a failing unit test or include a jsfiddle that distills and reproduces the issue.

Try forking this jsfiddle. We've set everything up there for you so that you can reproduce your issue.

License

We aim for you to use this inside your application, so we picked the least restrictive license we could find.

See LICENSE.

Something went wrong with that request. Please try again.