a JavaScript plugin to warn users about links to private pages
JavaScript
Latest commit 5a1cf5f Apr 1, 2016 @afeld afeld bump to 1.1.0
Permalink
Failed to load latest commit information.
assets
CONTRIBUTING.md
LICENSE.md
README.md
package.json
private-eye.js

README.md

Private Eye

detective image

A JavaScript plugin to warn users about links to private pages. Places a πŸ”’ icon next to any links with any URLs that you specify as private, and gives a warning message:

screenshot

At 18F, this is used on public sites that contain links to internal content like private GitHub repositories or Google Docs. Rather than write two versions to redact those links, this allows us to publish new content and give a warning to both staff and external readers.

Installation

Compatible with modern browsers (IE 9+). No dependencies.

Script

Private Eye can be included as a normal script on your page, exposing a PrivateEye global.

<script src="private-eye.js"></script>

CommonJS

Private Eye supports CommonJS, and is thus compatible with Browserify, WebPack, etc.

  1. Install the module.

    npm install --save @18f/private-eye
  2. Include in your application:

    var PrivateEye = require('private-eye');

Basic Usage

To get started using Private Eye, initialize PrivateEye with an object containing an ignoreUrls property with a list of URLs to match.

document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    // list of URLs to match as substrings – can be full URLs, hostnames, etc.
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );

Advanced Usage

Private Eye supports custom messages for links. The examples below provide different ways to customize a URL's messaging from general to granular.

Reconfiguring the default message

The default message given to links can be configured across all private urls by passing in an option named defaultMessage. This property is added to the object passed into PrivateEye( { /*...*/ } );.

document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    // Update the default message to a custom `string`.
    defaultMessage: "This link is secured, please ensure you have the proper credentials to access it."
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );

In the example above, all URLs matched by ignoreURLs will have the customized defaultMessage as the message the user sees when they hover over the link.

Configuring custom messages for individual URLs

Custom messaging is supported on a per-URL basis as well. This is done by passing an object in the ignoreUrls array with a url and message property for the URL to match and the message to display respectively.

document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    ignoreUrls: [
      'http://so.me/private/url',
      // Custom messages for individual URLs are passed in as an object.
      {
        url: 'anoth.er',
        message: 'This is another link that may not be accessible to you without the proper credentials',
      },
      // ...
    ]
  });
}, false );

In the example above, the URL matches for http://so.me/private/url will have the base default message. The URL matches for anoth.er will have a specific custom message for only those individual matches.

Using HTML to configure granular individual custom messages.

Custom messaging is supported on a per-element basis. If a title attribute is found on any matched anchor, the default or custom messaging is never set on the anchor. The original title attribute is left unmodified. This can be used to customize individual anchor elements on a more granular level.

// Set up for the plugin is the same as "Basic Usage" above.
document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    // list of URLs to match as substrings – can be full URLs, hostnames, etc.
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );
<!-- Base, or configured, default messaging for this link. -->
<a href="http://so.me/private/url">A private URL</a>
<!-- Granluar custom message for only this specific element. -->
<a href="http://so.me/private/url" title="This link is still private and you may not have access to it.">Another private URL</a>

In the example above, the customized message is set as a title attribute on one of the matched anchor elements. The first match without a title attribute will have the base default message. The second match with a title attribute will have the custom message found in title. This use case is particularly useful if you HTML page already contains valuable messaging around private URLs, or if you'd like to configure the messaging without the need of using JavaScript.

See also