Skip to:

jsLinks

This jQuery plugin makes it easy to add links or buttons to the DOM that require JavaScript to do their job. It does so in an unobtrusive manner. Adding these kinds of links/buttons to the page should be done using JavaScript as they won't work when JavaScript is disabled.

addJsLink( content, options, fn );
addPrintLink( content, options );
addBackLink( content, options );
addCloseLink( content, options );

Besides links/buttons with custom Javascript callbacks this jQuery plugin offers also three predefined types: print, go back and close window. These predefined types each have their own method: addPrintLink(), addBackLink() and addCloseLink(). The addJsLink() method can be used for adding any type of JavaScript links to the DOM, including those with custom callback functions.

Make sure you use links that require JavaScript only for enhancing the user experience, not as the sole access to your content and/or the core functionality of the page!

Return

jQuery object

Arguments

content [ String | required ]
The text that will be inserted into the DOM. If only part of this text should be the actual link/button, then this part must be surrounded by double square brackets, e.g. "This is the [[actual link]]." (see contentReplace).
The value must not be empty.
options [ Object | optional ]
Key/value pairs that extend/alter the default configuration:
- elem [ String | optional | default: "a" ]
  The type of element that will be inserted. Options are "a" or "button".
- wrapper [ String | optional ]
  HTML code that is to be wrapped around the inserted content, e.g. "<p>[@]</p>". [@] indicates the exact location of the content within the wrapper; (see wrapperReplace). wrapper may be useful in cases where you want to keep the content separated from the markup as much as possible.
- insert [ String | optional | default: "append" ]
  The method used to insert the whole of content + wrapper into the DOM, relative to the matched elements. Options are "prepend", "append", "before" or "after".
- steps [ Number | optional | default: 1 ]
  only applies to addBackLink() method
  The number of steps back in the browser's history.
  NOTE: the link/button will only be added if the number of locations in the history is bigger than the value of steps.
- winClose [ Window object | optional | default: window ]
  only applies to addCloseLink() method
  A reference to the window that is to be closed.
- winFocus [ Window object / String | optional ]
  only applies to addCloseLink() method
  A reference to the window that should receive focus after the closing window is closed. To give focus to the window from which the closing window was opened the value "opener" can be used.
Additional options (for advanced use only, in which case you probably won't be using a plugin like this):
- contentReplace [ RegExp | optional | default: /\[\[([\s\S]*)\]\]/ ]
  The pattern used to replace the actual link/button within the content. The default matches the double square brackets around the actual link text.
  Change this property only if using double square brackets is not an option for this purpose.
- wrapperReplace [ RegExp / String | optional | default: "[@]" ]
  The pattern used to find the location of the content within the wrapper.
  Change this property only if using "[@]" is not an option for this purpose.
- tmpClass [ String | optional | default: "jsAddedLink_tmp" ]
  ClassName which is only temporarily added to the link/button during initialisation. It is removed after the link is inserted.
  Change this property only if you really need to use the default className for other elements/purposes. I guess that would be extremely odd, but still...
fn [ Function / String | required ]
only applies to addJsLink() method
A function to bind to the click event on the inserted link/button. It receives two arguments. The first argument is the jQuery event object and the other one is an object with properties (defaults, extended with the ones passed) that were used for creating the link. Within the function's scope the this keyword refers to the link, as you would expect.
It's also possible to trigger predefined functions, passing one of the following strings: "print", "back", "close". These strings correspond to addJsPrint(), addJsBack() and addJsClose().

DOM alterations

The JavaScript link is inserted into the DOM.

A print link is only added if window.print is supported.
A back link is only added if the property steps is smaller than the number of pages in the browser's history.
A close link is only added if the window that is to be closed exists, is not closed yet and is opened from within another window.

Examples

<ul id="pageTools">
    <li><a href="mailafriend.php">Mail a friend</a></li>
    <li><a href="feedback.php">Feedback</a></li>
</ul>

Here $("#pageTools").addPrintLink("Print page"); would result in the following DOM structure ($("#pageTools").addJsLink("Print page", "print"); will give the same result):

<ul id="pageTools">
    <li><a href="mailafriend.php">Mail a friend</a></li>
    <li><a href="feedback.php">Feedback</a></li>
    <li><a href="">Print page</a></li>
</ul>

Clicking the link will open the print dialog box.

The way the link is inserted can be changed by passing an object with some optional properties. Given the following command...

$("#pageTools").addPrintLink("[[Print]] this page", {wrapper: "<span>[@]</span>", insert: "prepend"});

... the result will be:

<ul id="pageTools">
    <li><span><a href="">Print</a> this page</span></li>
    <li><a href="mailafriend.php">Mail a friend</a></li>
    <li><a href="feedback.php">Feedback</a></li>
</ul>

Inserting back links and close links works in a similar fashion. Both have their own dedicated method plus additional options though.

For custom JavaScript links only the general addJsLink(); method can be used:

$("#pageTools").addJsLink("Reload page", {wrapper: "<p>[@]</p>", insert: "after"}, function() { window.location.replace(); });

This will insert a link, wrapped in <p></p>, after the element #pageTools. On click the function that was passed in will be called, which will reload the page.