jquery.link-decorators
v1.1.1
Published
A family of jQuery plugins with custom link selectors and link modifiers to include file metadata for consistent, accessible markup.
Downloads
5
Maintainers
Readme
jquery.link-decorators
This is a family of jQuery plugins with custom link selectors and useful link modifiers. These help with creating consistent, accessible markup for links to downloadable files, offsite links, etc., that can show details like file size and file type, or enforce appropriate link targets. For example, links to offsite locations can be forced to open in a new window, regardless of the static markup.
This is especially useful on a CMS system, where there are multiple authors who may not be knowlegeable about markup, to enforce standards that improve usability and accessibility.
Getting Started
To use the plugin, include a reference to the file dist/jquery.link-decorators.js
or dist/jquery.link-decorators.min.js
in your page, after referencing jQuery itself.
The plugin is packaged as an NPM module, but Node.js is not required to use the plugin. It's a standard jQuery plugin, deployed with NPM because that is the form that the jQuery project encourages.
The files /demo/demo.html
and /demo/demo-fa
show simple examples of using the plugin.
Link Selectors
External link selector
jQuery("a:external")
Selects links to external locations, meaning links with a hostname different than the current location.
Internal link selector
jQuery("a:internal")
Selects internal links, where the hostname is the same as the current location.
Email link selector
jQuery("a:mailto")
Selects links to email addresses, where the protocol is mailto
.
Path starts with selector
jQuery("a:pathStartsWith(/download/)")
Selects links where the path starts with the given argument. Note that there are no quotes around the argument.
Path ends with selector
jQuery("a:pathEndsWith(.pdf)")
Selects links where the path ends with the given argument. Note that there are no quotes around the argument.
Path contains selector
jQuery("a:pathContains(something)")
Selects links where the path contains the given argument. Note that there are no quotes around the argument.
Link Modifiers
.addExtensionClass
Adds a class to a link corresponding to the file extension of the target. For example, a link to a .pdf
file
will have the class pdf
added to it. An optional argument can map from the extension to another
value.
For purposes of this operation, a link is considered to have an extension when the URL ends with a dot followed by 1-6 alphanumeric characters. Links whose URL does not match this pattern are unmodified.
With no argument supplied, the extension itself (not including the dot) is used as the class name. If an object is supplied, it is treated as a dictionary. If it has a property corresponding to the extension, the value of the property is used as the class name. If a function is supplied, it will be invoked with the extension, and the result will be used as the class.
With no argument: jQuery("a:pathStartsWith(/download/).addExtensionClass();
With a dictionary object:
var map = { pdf: "pdf-file", txt: "text-file" };
jQuery("a:pathStartsWith(/download/).addExtensionClass(map);
With a function:
var map = function(ext) {
return ext + "-file";
};
jQuery("a:pathStartsWith(/download/).addExtensionClass(map);
.openNewWindow
Causes links to open in a new window.
jQuery("a:pathStartsWith(/download/)").openNewWindow();
.decorate
Fetch the metadata corresponding to a link (file size, MIME type, etc.) and invoke a callback with the information.
Typically the callback will add some markup that includes the metadata, such as file size and MIME type.
The context (value of the this
keyword) for the callback is the link element.
The metadata is obtained by issuing a HEAD
request, and packaging the results into a simple data object with
the following properties:
ext
: The file extension as returned from the requestEXT
: The file extension in uppercasesize
: The file size, in bytesformattedSize
: The file size, formatted as an HTML snippet, with units of bytes, KB, MB, or GB.rawType
: The contents of theContent-Type
headermimeType
: The MIME type, obtained from theContent-Type
header
An optional second callback will be invoked if the request fails. This could be used to add an unhappy style to a broken link.
jQuery("a:pathStartsWith(/download/)")
.decorate(function (info) { $(this).append("<span class='popup'>[" + info.EXT + ": " + info.formattedSize + "]</span>") });
.noFollow
Add rel='nofollow'
to an <a>
element. This instructs search engines to not let this link
influence the ranking of the link's target.
.noOpener
Add rel='noopener'
to an <a>
element. This prevents "reverse tabnabbing" when the link refers
to a malicious page.
Common uses:
Make off-site links in the main div open in a new window, add a rel=noOpener
attribute,
and decorate with some popup text (the popup effect relies on appropriate CSS, not shown here).
$("div.main a:external")
.openNewWindow()
.noOpener()
.append("<span class='popup'>Opens in new window</span>")});
Give links to the documents folder document
class, and a class for the file extension,
show the file type and size in a popup, and open in a new window.
$("div.main a:pathStartsWith(/documents/)")
.addClass("document")
.addExtensionClass()
.openNewWindow()
.decorate(function (info) {
$(this).append("<span class='popup'>[" + info.EXT + ": " + info.formattedSize + "]</span>")
});