linkToolkit

linkToolkit

A collection of functions for sanitising links in HTML pages. The functions in this API depend on jQuery. Some functions also depend on URI.js (including its optional jQuery extension). jQuery must be loaded into the document before bartificer.linkToolkit.js.

All the functions in this API alter selective link tags in some way. All functions will ignore links with the CSS class bartificer-ignore.

Requires

  • module:jQuery

Methods

(static) autoExternalise($containeropt, optsopt) → {number}

Scan through a document, or a subset of a document, and call bartificer.linkToolkit.externalise() on each link that is not considered local to the site.

Parameters:
Name Type Attributes Default Description
$container jQueryObject <optional>
 $(document)

Where to search for the links. The entire document is searched by default.
opts PlainObject <optional>

Specify configuration options.

Properties
Name Type Attributes Default Description
addIcon boolean <optional>
 true

If true, the icon image will be added after all altered links.
linkClasses string <optional>
 ''

Additional classes to add to all altered links.
subDomainsLocal boolean <optional>
 true

Whether or not subdomains of the current domain should be considered local.
ignoreDomains Array.<string> <optional>
 []

Links to domains in this array will be ignored.
iconSrc string <optional>

The value to use for the icon image's src attribute. By default, a data attribute is used.
iconExternal boolean <optional>
 true

If true, the icon image will be added after the link (with jQuery's .after() function), otherwise, it will be added to the end of the link (with jQuery's .append() function).
iconClasses string <optional>
 ''

Additional classes to add to the icon image as a singel space-separated string.
altText string <optional>
 'External Link Icon'

The alternative text for the icons.
titleText string <optional>
 'Link Opens in New Window/Tab'

The title text for the icons.
See:
Requires:
  • module:URI
Throws:

  • An error is thrown if the first argument is present, but not a jQuery object.

    Type
    TypeError

  • An error is thrown if the second argument is present, but not a plain object.

    Type
    TypeError

  • Throws an exception if URI.js is not loaded.

    Type
    Error
Returns:

The number of links altered.

Type
number
Example
// externalise all links in the enture document that lead outside the site
bartificer.linkToolkit.autoExternalise();

// externalise all links within a given container, using a custom icon, and skipping links
// to a list of specified domains
bartificer.linkToolkit.autoExternalise(
  $('#main_content'),
  {
    iconSrc: 'externalIcon.png',
    ignoreDomains: ['bartbusschots.ie', 'www.bartbusschots.ie']
  }
);

(static) autoExternalize()

An alias for bartificer.linkToolkit.autoExternalise.

See:

(static) debug(doDebugopt) → {boolean}

Get or set the debug status. When debug mode is enabled, messages will be logged to the web/JavaScript console with console.trace(). Since Versions of IE before 11 don't support console.trace, don't enable debug mode on a live site.

Parameters:
Name Type Attributes Description
doDebug boolean <optional>

If this parameter is passed, the debug mode will be set accordingly.
Returns:

true is debug mode is enabled, false otherwise.

Type
boolean
Example
// get the debug status
if(bartificer.linkToolkit.debug()){
  window.alert('debug mode ENABLED');
}else{
  window.alert('debug mode DISABLED');
}

// enable debug mode
bartificer.linkToolkit.debug(true);

// disable debug mode
bartificer.linkToolkit.debug(false);

(static) externalise($linksopt, optsopt) → {number}

Make links external by setting their target to _blank, adding noopener to their rel attribute, and optionally appending an icon.

Each element represented by $links will be checked to see if it is a link. By default, anything that is not a link will be skipped, however, by setting the option opts.searchContainers to true, all elements that are not links will be searched for containing links, and those links externalised.

Any icon can be added, but by default, an icon from the Fugue Icons icon set by Yusuke Kamiyamane, which is licensed as Creative Commons Attribution 3.0 is used.

When looking inside a container, the function will skip any links that have any of the CSS classes bartificer-ignore, bartificer-externalize-ignore, or bartificer-externalise-ignore. Links specified directly will not be ignored based on their CSS classes.

Altered links will have the CSS class bartificer-externalLink added, and if icons are added, they will also have the CSS class bartificer-externalLink.

Any links which already have a class of bartificer-externalLink will be skipped on the assumption that they have already been externalised previously.

Parameters:
Name Type Attributes Default Description
$links jQueryObject <optional>
 $()

The links to alter. If a jQuery object is passed that does not represent any links, including a completely empty jQuery object, the function will silently do nothing.
opts PlainObject <optional>

Specify configuration options.

Properties
Name Type Attributes Default Description
searchContainers boolean <optional>
 false

Whether or not to look inside non-link elements in $links for links.
addIcon boolean <optional>
 true

If true, the icon image will be added after all altered links.
linkClasses string <optional>
 ''

Additional classes to add to all altered links.
iconSrc string <optional>

The value to use for the icon image's src attribute. By default, a data attribute is used.
iconExternal boolean <optional>
 true

If true, the icon image will be added after the link (with jQuery's .after() function), otherwise, it will be added to the end of the link (with jQuery's .append() function).
iconClasses string <optional>
 ''

Additional classes to add to the icon image as a singel space-separated string.
altText string <optional>
 'External Link Icon'

The alternative text for the icons.
titleText string <optional>
 'Link Opens in New Window/Tab'

The title text for the icons.
Throws:

  • An error is thrown if the first argument is not a jQuery object.

    Type
    TypeError

  • An error is thrown if the second argument is present, but not a plain object.

    Type
    TypeError
Returns:

The number of links altered.

Type
number
Example
// externalise all links in the entire document using the default icon
bartificer.linkToolkit.externalise($('a'));

// externalise all links within a given container using a custom icon
bartificer.linkToolkit.externalise(
  $('a', $('#main_content')),
  { iconSrc: 'externalIcon.png' }
);

(static) externalize()

An alias for bartificer.linkToolkit.externalise.

See:

(static) isLocalUrl(url, optsopt) → {boolean}

A function to test if a given URL is local to the current domain or not. All relative URLs are considered local, as are URLs with the same host component as the current page. URLs with host components that are subdomains of the host component of the current pages can optionally also be considered local.

Parameters:
Name Type Attributes Description
url string

The URL to test.
opts PlainObject <optional>

A plain object containing configuration information.

Properties
Name Type Attributes Default Description
subDomainsLocal boolean <optional>
 true

Whether or not subdomains of the current domain should be considered local.
localDomains Array.<string> <optional>
 []

Links to domains in this array will be considered local.
Requires:
  • module:URI
Throws:

Throws an exception if URI.js is not loaded.

Type
Error
Returns:

true if the link is local, false otherwise. Values that are not strings or numbers will always return false. The empty string is a relative URL to the current page, so it will return true.

Type
boolean
Example
// test if a URL is local to the current website (default settings)
var isLocal = bartificer.linkToolkit.isLocalUrl('http://www.bartb.ie/test');

// test if a URL is local to the current site - subdomains exluded and alternative domain
// explicitly marked as local
var isLocal = bartificer.linkToolkit.isLocalUrl(
  'http://www.bartb.ie/test',
  {
    subDomainsLocal: false,
    localDomains: ['bartbusschots.ie', 'www.bartbusschots.ie']
  }
);

(static) markExternal($containeropt, optsopt) → {number}

Append an icon to the end of links with a target of _blank. A custom image can be specified, but by default an icon from the Fugue Icons icon set by Yusuke Kamiyamane, which is licensed as Creative Commons Attribution 3.0.

The function will skip any links that have any of the CSS classes bartificer-ignore, or bartificer-markExternal-ignore

Both the links that have icons added to them, and the generated icons will have the CSS class bartificer-externalLink.

Parameters:
Name Type Attributes Default Description
$container jQueryObject <optional>
 $(document)

Where to search for the links.
opts PlainObject <optional>

Specify configuration options.

Properties
Name Type Attributes Default Description
iconSrc string <optional>

The value to use for the icon image's src attribute. By default, a data attribute is used.
iconExternal boolean <optional>
 true

If true, the icon image will be added after the link (with jQuery's .after() function), otherwise, it will be added to the end of the link (with jQuery's .append() function).
iconClasses string <optional>
 ''

Additional classes to add to the icon image as a singel space-separated string.
altText string <optional>
 'External Link Icon'

The alternative text for the icons.
titleText string <optional>
 'Link Opens in New Window/Tab'

The title text for the icons.
Returns:

The number of icons injected.

Type
number
Example
// add the default icon after all links within the enture document
bartificer.linkToolkit.markExternal();

// add the default icon after all links with a target of _blank within a given container
bartificer.linkToolkit.markExternal($('#main_content'));

// add a custom icon after all links with a target of _blank within a given container
bartificer.linkToolkit.markExternal(
  $('#main_content'),
  { iconSrc: 'externalIcon.png'}
);

(static) noopenerFix($containeropt, optsopt) → {number}

To counter-act a known security vulnerability, it's good practice to set the rel attribute of all links that have a target of _blank to noopener. By default, when a new window/tab is opened by a web page, the web page that loads into that newly created window/tab will contain a JavaScript object named opener that points back to the window/tab that created it. While JavaScript's cross-domain rules prevent this object from doing many things, they do not prevent the objet from doing everything, so a page opened by clicking on a link with a target of _blank can do some neferious things, including altering the URL in the opening window. This could facilitate a convincing phishing attack.

This function scans the entire document, or a sub-set of the document, for links that have a target of _blank, and adds a rel of noopener to any that do not already have it. The HTML specification states that the rel attribute can have multiple space-separated values, so, this function will append noopener to any rel attributes that already exist, but do not contain the value noopener.

The function will skip any links that have any of the CSS classes bartificer-ignore, or bartificer-noopener-ignore.

The function also skips all local links by default, and a list of domains to be considered local can be supplied. Local links are those that are relative, or that go to the same domain as the current page. Sub domains of the current page's domain are also considered local by default. This behaviour can be disabled.

If local links are to be skipped, then the URI.js libary is required.

Parameters:
Name Type Attributes Default Description
$container jQueryObject <optional>
 $(document)

A jQuery object to confine the function's effect. If passed, only links containined within the elements represented by the jQuery object will be examined and potentially altered by the function.
opts PlainObject <optional>

A plain object containing configuration information.

Properties
Name Type Attributes Default Description
ignoreLocalLinks boolean <optional>
 true

Whether or not to ignore local links.
subDomainsLocal boolean <optional>
 true

Whether or not subdomains of the current domain should be considered local.
ignoreDomains Array.<string> <optional>
 []

Links to domains in this array will be ignored.
Throws:

An error is thrown if the first argument is present, but not a jQuery object.

Type
TypeError
Returns:

The number of links that were altered.

Type
number
Example
// add rel=noopener to all links with a target of _blank that link to a URL outside the current
// site througout the entire document with the default settings
bartificer.linkToolkit.noopenerFix();

// add rel=noopener to all links with a target of _blank that link to a URL outside the current
// site but only within a given container
bartificer.linkToolkit.noopenerFix($('#main_content'));

// add re=noopener to all links with a target of _blank, regardless of what URL they link to throughout
// the entire document
bartificer.linkToolkit.noopenerFix(undefined, { ignoreLocalLinks: false });

(static) version() → {string}

Get the version number for the API as a number.

Returns:

the version number as a string of the form majorVersion.minorVersion, e.g. '1.0'.

Type
string
Example
var ver = bartificer.linkToolkit.version();