Description
nlm.notifyExternal finds all the links to selected external sites and modifies them with a message appropriate to the privacy policy. The link will get a message inserted into it's title attribute.
Usage
Standard Usage
The standard use for nlm.notifyExternal is to call setNotification() after
the document has loaded. This will put the default message on all links matched by the default
site list.
Example - Standard Usage
<script src="https://assets.nlm.nih.gov/jquery/jquery-latest.min.js" ></script> <script src="/core/nlm-notifyExternal/1.0/nlm-notifyExternal.js" ></script> <script type="text/javascript"> // Usual behavior $(document).ready(function() {nlm.notifyExternal.setNotification()}); </script>
Specifying an Element
setNotification() accepts a jQuery element if you want to scan a section of the
document. This can be useful for sections of the document that are modified after the document is
loaded, e.g. via AJAX.
Example - Specified Element
<script type="text/javascript"> // Simple AJAX load $('#feed').load('ajax/test.html', function() {nlm.notifyExternal.setNotification($(this))}); </script>
Alternate Message
You can override the message by providing an options object with a message property.
The string value of this property will be used as the message.
If you customize the behavior to remove the link, change the language, or change which external sites this is applied to, please notify the NLM ISSO.
Example - Alternate Message
<script type="text/javascript"> $(document).ready(function() { nlm.notifyExternal.setNotification($(document), {message : 'Good Bye' }); }); </script>
Alternate Sites
You can override the sites matched by setNotification by providing an options object
with a sites property. This value of this property is an array of strings and/or
regular expressions matching the external site hostnames. Do not include the protocol (e.g.
http:// or ftp://. setNotification will match a protocol
before comparing the hostnames.
If you customize the behavior to remove the link, change the language, or change which external sites this is applied to, please notify the NLM ISSO.
Example - Alternate Sites
<script type="text/javascript"> // Start with the default sites mysites = nlm.notifyExternal.defaultSites(); // Add a few more sites mysites.push('www.cnn.com'); mysites.push(new RegExp('([^/]+\\.)?microsoft\\.com'); $(document).ready(function() { nlm.notifyExternal.setNotification($(document), {sites : mysites }); }); </script>
Customizing Behavior
setNotification returns a jQuery object containing all the elements it matched and
modified. This allows you to perform additional manipulation of the elements by chaining
additional functions.
Example - Custom Formatting
<script type="text/javascript"> $(document).ready(function() { // Highlight external links by setting a background color. nlm.notifyExternal.setNotification().css('background-color', '#ddd'); }); </script>
Defaults
Messages
nlm.notifyExternal has the following default messages. It will attempt to determine
the language of the document from the HTML tag's lang attribute or the content-language meta tag.
If it can't determine the language, or there isn't a message for that language, the English message
is used. The default messages are:
- English (en)
- External link: please review our privacy policy.
- Spanish (es)
- Enlace externo: Por favor, revise nuestra política de privacidad.
Sites
The default site list is:
- apple.com domain
- facebook.com domain
- twitter.com domain
- youtube.com domain
Domains are specified with regular expressions similar to the following for apple.com:
([^/]+\\.)?apple\\.com.
Methods
nlm.notifyExternal.defaultSites()
Default site definitions. Can be used to extend sites found when calling setNotification()
Returns:
- {Array of Strings and RegExp}
- A copy of the default patterns that match external sites.
nlm.notifyExternal.setNotification()
Scan for anchor tags containing links to external sites and add a message to them.
Parameters:
- element {jQuery object} Optional, Default: 'document'
- Element(s) below which to scan for external links.
- options {object} Optional
- Additional configuration options. The recognized properties are:
- message {String} Optional, Default: 'document'
- Message to display on external links
- sites {Array of Strings and/or RegExp} Optional
- A list containing strings and/or regular expressions identifying which sites are considered external
Returns:
- {jQuery object}
- The anchor elements that were identified as external. Can be used to add custom modifications to the elements.
Example
See the demonstration page for working examples
Last Reviewed: March 25, 2013