jQuery urlInternal: Easily test URL internal-, external or fragment-ness

Version: 1.0, Last updated: 10/7/2009

Project Homehttp://benalman.com/projects/jquery-urlinternal-plugin/
GitHubhttp://github.com/cowboy/jquery-urlinternal/
Sourcehttp://github.com/cowboy/jquery-urlinternal/raw/master/jquery.ba-urlinternal.js
(Minified)http://github.com/cowboy/jquery-urlinternal/raw/master/jquery.ba-urlinternal.min.js (1.7kb)
Summary
jQuery urlInternal: Easily test URL internal-, external or fragment-nessVersion: 1.0, Last updated: 10/7/2009
LicenseCopyright © 2009 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.
ExamplesThis working example, complete with fully commented code, illustrates a few ways in which this plugin can be used.
Support and TestingInformation about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).
Release History
Methods
Functions
jQuery.isUrlInternalTest whether or not a URL is internal.
jQuery.isUrlExternalTest whether or not a URL is external.
jQuery.isUrlFragmentTest whether or not a URL is a fragment in the context of the current page, meaning the URL can either begin with # or be a partial URL or full URI, but when it is navigated to, only the document.location.hash will change, and the page will not reload.
jQuery.fn.urlInternalFilter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).
jQuery.fn.urlExternalFilter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).
jQuery.fn.urlFragmentFilter a jQuery collection of elements, returning only elements that have an fragment URL (as determined by jQuery.isUrlFragment).
Selectors
Selectors
:urlInternalFilter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).
:urlExternalFilter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).
:urlFragmentFilter a jQuery collection of elements, returning only elements that have an fragment URL (as determined by jQuery.isUrlFragment).
Support methods
Functions
jQuery.elemUrlAttrGet the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.
jQuery.urlInternalHostConstructs the regular expression that matches an absolute-but-internal URL from the current page’s protocol, hostname and port, allowing for any number of optional hostnames.
jQuery.urlInternalRegExpSet or get the regular expression that matches an absolute-but-internal URL.

License

Copyright © 2009 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.  http://benalman.com/about/license/

Examples

This working example, complete with fully commented code, illustrates a few ways in which this plugin can be used.

http://benalman.com/code/projects/jquery-urlinternal/examples/urlinternal/

Support and Testing

Information about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).

jQuery Versions1.3.2
Browsers TestedInternet Explorer 6-8, Firefox 2-3.7, Safari 3-4, Chrome, Opera 9.6-10.
Unit Testshttp://benalman.com/code/projects/jquery-urlinternal/unit/

Release History

1.0(10/7/2009) Initial release

Methods

Summary
Functions
jQuery.isUrlInternalTest whether or not a URL is internal.
jQuery.isUrlExternalTest whether or not a URL is external.
jQuery.isUrlFragmentTest whether or not a URL is a fragment in the context of the current page, meaning the URL can either begin with # or be a partial URL or full URI, but when it is navigated to, only the document.location.hash will change, and the page will not reload.
jQuery.fn.urlInternalFilter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).
jQuery.fn.urlExternalFilter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).
jQuery.fn.urlFragmentFilter a jQuery collection of elements, returning only elements that have an fragment URL (as determined by jQuery.isUrlFragment).

Functions

jQuery.isUrlInternal

Test whether or not a URL is internal.  Non-navigating URLs (ie.  #anchor, javascript:, mailto:, news:, tel:, im: or non-http/https protocol:// links) are not considered internal.

Usage

jQuery.isUrlInternal( url );

Arguments

url(String) a URL to test the internal-ness of.

Returns

(Boolean) true if the URL is internal, false if external, or undefined if the URL is non-navigating.

jQuery.isUrlExternal

Test whether or not a URL is external.  Non-navigating URLs (ie.  #anchor, mailto:, javascript:, or non-http/https protocol:// links) are not considered external.

Usage

jQuery.isUrlExternal( url );

Arguments

url(String) a URL to test the external-ness of.

Returns

(Boolean) true if the URL is external, false if internal, or undefined if the URL is non-navigating.

jQuery.isUrlFragment

Test whether or not a URL is a fragment in the context of the current page, meaning the URL can either begin with # or be a partial URL or full URI, but when it is navigated to, only the document.location.hash will change, and the page will not reload.

Usage

jQuery.isUrlFragment( url );

Arguments

url(String) a URL to test the fragment-ness of.

Returns

(Boolean) true if the URL is a fragment, false otherwise.

jQuery.fn.urlInternal

Filter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).  If URL cannot be determined, remove the element from the collection.

Usage

jQuery('selector').urlInternal( [ attr ] );

Arguments

attr(String) Optional name of an attribute that will contain a URL to test internal-ness against.  See jQuery.elemUrlAttr for a list of default attributes.

Returns

(jQuery) A filtered jQuery collection of elements.

jQuery.fn.urlExternal

Filter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).  If URL cannot be determined, remove the element from the collection.

Usage

jQuery('selector').urlExternal( [ attr ] );

Arguments

attr(String) Optional name of an attribute that will contain a URL to test external-ness against.  See jQuery.elemUrlAttr for a list of default attributes.

Returns

(jQuery) A filtered jQuery collection of elements.

jQuery.fn.urlFragment

Filter a jQuery collection of elements, returning only elements that have an fragment URL (as determined by jQuery.isUrlFragment).  If URL cannot be determined, remove the element from the collection.

Note that in most browsers, selecting $(“a[href^=#]”) is reliable, but this doesn’t always work in IE6/7!  In order to properly test whether a URL attribute’s value is a fragment in the context of the current page, you can either make your selector a bit more complicated.. or use .urlFragment!

Usage

jQuery('selector').urlFragment( [ attr ] );

Arguments

attr(String) Optional name of an attribute that will contain a URL to test external-ness against.  See jQuery.elemUrlAttr for a list of default attributes.

Returns

(jQuery) A filtered jQuery collection of elements.

Selectors

Summary
Selectors
:urlInternalFilter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).
:urlExternalFilter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).
:urlFragmentFilter a jQuery collection of elements, returning only elements that have an fragment URL (as determined by jQuery.isUrlFragment).

Selectors

:urlInternal

Filter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).  If URL cannot be determined, remove the element from the collection.

Usage

jQuery('selector').filter(':urlInternal');
jQuery('selector').filter(':urlInternal(attr)');

Arguments

attr(String) Optional name of an attribute that will contain a URL to test internal-ness against.  See jQuery.elemUrlAttr for a list of default attributes.

Returns

(jQuery) A filtered jQuery collection of elements.

:urlExternal

Filter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).  If URL cannot be determined, remove the element from the collection.

Usage

jQuery('selector').filter(':urlExternal');
jQuery('selector').filter(':urlExternal(attr)');

Arguments

attr(String) Optional name of an attribute that will contain a URL to test external-ness against.  See jQuery.elemUrlAttr for a list of default attributes.

Returns

(jQuery) A filtered jQuery collection of elements.

:urlFragment

Filter a jQuery collection of elements, returning only elements that have an fragment URL (as determined by jQuery.isUrlFragment).  If URL cannot be determined, remove the element from the collection.

Note that in most browsers, selecting $(“a[href^=#]”) is reliable, but this doesn’t always work in IE6/7!  In order to properly test whether a URL attribute’s value is a fragment in the context of the current page, you can either make your selector a bit more complicated.. or use :urlFragment!

Usage

jQuery('selector').filter(':urlFragment');
jQuery('selector').filter(':urlFragment(attr)');

Arguments

attr(String) Optional name of an attribute that will contain a URL to test fragment-ness against.  See jQuery.elemUrlAttr for a list of default attributes.

Returns

(jQuery) A filtered jQuery collection of elements.

Support methods

Summary
Functions
jQuery.elemUrlAttrGet the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.
jQuery.urlInternalHostConstructs the regular expression that matches an absolute-but-internal URL from the current page’s protocol, hostname and port, allowing for any number of optional hostnames.
jQuery.urlInternalRegExpSet or get the regular expression that matches an absolute-but-internal URL.

Functions

jQuery.elemUrlAttr

Get the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.

In the jQuery.fn.urlInternal and jQuery.fn.urlExternal methods, as well as the :urlInternal and :urlExternal selectors, this list is used to determine which attribute contains the URL to be modified, if an “attr” param is not specified.

Default Tag-Attribute List

ahref
basehref
iframesrc
imgsrc
inputsrc
formaction
linkhref
scriptsrc

Usage

jQuery.elemUrlAttr( [ tag_attr ] );

Arguments

tag_attr(Object) An object containing a list of tag names and their associated default attribute names in the format { tag: ‘attr’, ...  } to be merged into the internal tag-attribute list.

Returns

(Object) An object containing all stored tag-attribute values.

jQuery.urlInternalHost

Constructs the regular expression that matches an absolute-but-internal URL from the current page’s protocol, hostname and port, allowing for any number of optional hostnames.  For example, if the current page is http://benalman.com/test or http://www.benalman.com/test, specifying an argument of “www” would yield this pattern:

/^(?:http:)?\/\/(?:(?:www)\.)?benalman.com\//i

This pattern will match URLs beginning with both http://benalman.com/ and http://www.benalman.com/.  If the current page is http://benalman.com/test, http://www.benalman.com/test or http://foo.benalman.com/test, specifying arguments “www”, “foo” would yield this pattern:

/^(?:http:)?\/\/(?:(?:www|foo)\.)?benalman.com\//i

This pattern will match URLs beginning with http://benalman.com/, http://www.benalman.com/ and http://foo.benalman.com/.

Not specifying any alt_hostname will disable any alt-hostname matching.

Note that the plugin is initialized by default to an alt_hostname of “www”.  Should you need more control, jQuery.urlInternalRegExp may be used to completely customize the absolute-but-internal matching pattern.

Usage

jQuery.urlInternalHost( [ alt_hostname [, alt_hostname ] ... ] );

Arguments

alt_hostname(String) An optional alternate hostname to use when testing URL absolute-but-internal-ness.

Returns

(RegExp) The absolute-but-internal pattern, as a RegExp.

jQuery.urlInternalRegExp

Set or get the regular expression that matches an absolute-but-internal URL.

Usage

jQuery.urlInternalRegExp( [ re ] );

Arguments

re(String or RegExp) The regular expression pattern.  If not passed, nothing is changed.

Returns

(RegExp) The absolute-but-internal pattern, as a RegExp.

Test whether or not a URL is internal.
Test whether or not a URL is external.
Test whether or not a URL is a fragment in the context of the current page, meaning the URL can either begin with # or be a partial URL or full URI, but when it is navigated to, only the document.location.hash will change, and the page will not reload.
Get the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.
Filter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).
Filter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).
Filter a jQuery collection of elements, returning only elements that have an internal URL (as determined by jQuery.isUrlInternal).
Filter a jQuery collection of elements, returning only elements that have an external URL (as determined by jQuery.isUrlExternal).
Set or get the regular expression that matches an absolute-but-internal URL.
Close