jurlp.js

Summary

jurlp.js
JQuery URL parser.	JQuery URL parser plugin for parsing, manipulating, filtering and monitoring URLs in href and src attributes within arbitrary elements (including document.location.href), as well as creating anchor elements from URLs found in HTML/text.
Authors	Thomas James Bonner (tom.b.nosp@m.onner@gmai.nosp@m.l.com).
Version	1.0.4
License	Copyright © 2012, Thomas James Bonner (tom.b.nosp@m.onner@gmai.nosp@m.l.com).
URL overview.	A quick quide to URL nomenclature in this plugin.
URL Objects	URL object definition.
Quick overview	Useful example code.
Parsing document.location.href	Parsing the document URL.
Parsing elements with an “href” or “src” attribute.	Parsing “href” or “src” attributes.
Parsing element text/HTML.	Parsing text/HTML for URLs.
Parsing URL strings directly.	How to directly parse, modify or monitor an arbitrary URL string.
Unknown URLs.	Overview of unknown URL parsing.
Operators.	Overview of filter operators.
this parameter.	Where “this” is refered to as an argument to the method functions, it may be one of the following;
Internal functions.	All internal private functions.
Functions
initialiseElement	Initialise an element for use with the URL parser.
initialiseElementText	Initialise an elements text field for use with the URL parser.
setAttrUrl	Given an element, and an attribute, set the attribute to the supplied URL, and created a backup of the original URL if not already done.
restoreAttrUrl	Given an element, and an attribute, then restore the URL attribute value to its original value.
restoreElement	Destroys any data associated with an element that has previously been initialised for use with the URL parser, and restores the elements “href” or “src” attribute (if any) to its original value.
getHref	Get the href URL for the element.
updateHref	Update a segment of the elements href URL.
updateHrefShim	Shim function for reorganising parameters before calling updateHref().
setHref	Sets the href URL value for an element.
urlToObject	Parse a URL into segments using the DOM.
objectToUrl	Convert a URL object to a string.
sanitiseUrl	Sanitise a URL.
urlObjectToString	Converts a URL object to a string (used to override toString for URL objects).
setUrlSegment	Set the value of a segment within a URL string.
getUrlObject	Convert a URL string to an object, if not already.
getFragmentString	Retrieve the fragment string for a given URL.
getQueryString	Retrieve the query string for a given URL.
updateQuery	Update the query string for the elements URL.
queryStringToObject	Convert a query string to an object.
getQueryObject	Retrieve the query object for a given URL.
queryObjectToString	Query objects toString method.
getPathString	Retrieve the path string for a given URL.
getPathObject	Retrieve the path object for a given URL.
updatePath	Update the path string for the elements URL.
pathObjectToString	Path objects toString method.
getPortString	Retrieve the port string for a given URL.
getHostString	Retrieve the host string for a given URL.
getPasswordString	Retrieve the password string for a given URL.
getUserString	Retrieve the user string for a given URL.
getSchemeString	Retrieve the scheme string for a given URL.
addSelectorCallback	Add a function the selector callstack.
returnEachElement	Apply the callback for each element in this.
returnEachObject	Apply the callback for each element in this, and buffer return codes.
dispatchGetSetHelper	Dispatch to get or set helper functions depending on the arguments supplied.
methodDispatcher	Main method dispatcher for the public interface.
URI parser interface.	All URI parsing is handled through this interface.
Functions
uri.toString.http	Converts a URI object with an “http” scheme to a string.
uri.toString.mailto	Converts a URI object with a “mailto:” scheme to a string.
uri.toString.javascript	Converts a URI object with a “javascript:” scheme to a string.
uri.toString.generic	Converts an generic URI object to a string.
uri.parsers.http	Parse a URI with a “http://” scheme into a URI object.
uri.parsers.mailto	Parse a URI with a “mailto:” scheme into a URI object.
uri.parsers.javascript	Parse a URI with a “javascript:” scheme into a URI object.
uri.parsers.generic	Parses any URI (URIs with a scheme seperator of “://” are parsed as “http://”, everything else is treated as unknown..
uri.parse	Parse a URI string based on scheme.
Helper interface.	All private helper methods.
Functions
getUrl	Return the elements URL (stored under its “data-href”, and/or “href”/”src” attribute).
setUrl	Set the elements URL (stored under it’s “data-href”, and/or “href”/”src” attribute).
parseUrl	Return the URL object for the elements “data-href” attribute value.
getFragment	Get the fragment object from the elements URL.
setFragment	Set the fragment string for the elements URL.
getQuery	Get the query object from the elements URL.
setQuery	Set the query string for the elements URL.
getPath	Get the path object from the elements URL.
setPath	Set the path string for the elements URL.
getPort	Get the port string from the elements URL.
setPort	Set the port string for the elements URL.
getHost	Get the host string from the elements URL.
setHost	Set the host string for the elements URL.
getPassword	Get the password string from the elements URL.
setPassword	Set the password string for the elements URL.
getUser	Get the user string from the elements URL.
setUser	Set the user string for the elements URL.
getScheme	Get the scheme string from the elements URL.
setScheme	Set the scheme string for the elements URL.
= (equals)	Test if the actual value is equal to the user supplied value.
!= (not equals)	Test if the actual value is equal to the user supplied value.
< (less than)	Test if the actual value is less than the user supplied value.
> (greater than)	Test if the actualValue is greater than the user supplied value.
<= (less than or equal to)	Test if the actual value is less than or equal to the user supplied value.
>= (greater than or equal to)	Test if the actual value is greater than or equal to the user supplied value.
*= (contains)	Test if the actual value contains the user supplied value.
^= (starts with)	Test if the start of the actual value matches the user supplied value.
$= (ends with)	Test if the end of the actual value is the same as the user supplied value.
regex (regular expression)	Test if the actual value matches the user supplied regular expression.
Public interface.	All public methods exposed via the JQuery URL parser plugin interface.
Functions
url	Get/Set the href string for the given element(s).
fragment	Get/Set the fragment segment of the URL for the given element(s).
query	Get/Set the query segment of the URL for the given element(s).
path	Get/Set the path segment of the URL for the given element(s).
port	Get/Set the port segment of the URL for the given element(s).
host	Get/Set the host segment of the URL for the given element(s).
password	Get/Set the password segment of the URL for the given element(s).
user	Get/Set the user segment of the URL for the given element(s).
scheme	Get/Set the scheme segment of the URL for the given element(s).
initialise	Initialise the parser for the given element(s).
restore	Removes any parser data associated with the element(s), and sets the href attribute to its original value.
goto	Set document.location.href to the supplied elements “href”, “src” or “data-href” attribute value.
proxy	Proxy the URL.
watch	Automatically apply all modifications to new elements added to the DOM that match the selector for the supplied elements.
unwatch	Removes a watch previously created with watch, and prevents modifications being made to new elemenets of the same selector.
filter	Filters elements by URL or URL segment.
interface	Get the available methods for the parser interface.
JQuery plugin interface.
Functions
$.fn.jurlp	Public interface/method dispatcher for the JQuery URL parser.
$.jurlp	Returns an interface for directly parsing, manipulating and monitoring the supplied URL.

JQuery URL parser.

JQuery URL parser plugin for parsing, manipulating, filtering and monitoring URLs in href and src attributes within arbitrary elements (including document.location.href), as well as creating anchor elements from URLs found in HTML/text.

Summary

Authors	Thomas James Bonner (tom.b.nosp@m.onner@gmai.nosp@m.l.com).
Version	1.0.4
License	Copyright © 2012, Thomas James Bonner (tom.b.nosp@m.onner@gmai.nosp@m.l.com).

Authors

Thomas James Bonner (tom.b.nosp@m.onner@gmai.nosp@m.l.com).

Yonas Sandbæk (sel.nosp@m.tar@gmai.nosp@m.l.com).

Version

1.0.4

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

URL overview.

URL naming scheme

A quick quide to URL nomenclature in this plugin.

Throughout this plugin, URLs are segmented and refered to in the following manner;

http://username:password@www.example.com:443/path/file.name?query=string#anchor
|_____||______| |______| |_____________| |_||_____________||___________||_____|
   |       |       |           |          |         |             |         |
scheme   user   password      host       port      path         query   fragment
|______________________________________________________________________________|
                                       |
                                      url

Scheme

Contains the protocol identifier (i.e. “https://”, “ftp://”).

User

Conains the username to use when connecting to the host server. This segment may be empty.

Password

Contains the password to use in conjunction with the username when connecting to the remote server. This segment may be empty (and cannot be set without a user name).

Host

Contains the name or IP address of the host server (i.e. “www.example.com”, or “127.0.0.1”).

Port

Contains the listening port number for the host server (i.e. “80”, or “8080”). Note that an empty port value implies the default port (80).

Path

Contains the file path (i.e. “/index.html”, or “/”).

Query

Contains any parameters passed in the query (i.e. “?param1=value1&param2=value2”). This segment may be empty.

Fragment

Contains any anchors/hash tags (i.e. “#elementname”). This segment may be empty.

URL Objects

URL object definition.

For the purposes of this plugin, URLs can be represented either as a string, for example “http://www.example.com:8080/path/file.name?query=string#anchor”, or as an object;

{
    scheme: "http://"
    user: "username",
    password: "password",
    host: "www.example.com",
    port: "8080",
    path: "/path/file.name",
    query: "?query=string",
    fragment: "#anchor"
}

Therefore, wherever URLs are supplied as a parameter to the plugin via the url or proxy methods, either a string or object representation or the URL may be supplied.

URL objects that have been returned via the parser interface can easily be converted to a string by calling the objects toString() method.

Example

// Parse the document.location.href URL, and convert it back to a string again.
$(document).jurlp("url").toString();

Quick overview

Useful example code.

// Parse and set the element(s) URL
$("a").jurlp("url");
$("a").jurlp("url", "http://www.example.com/");

// Get or set individual URL segments for the element(s)
$("a").jurlp("scheme");
$("a").jurlp("scheme", "https://");

$("a").jurlp("user");
$("a").jurlp("user", "username");

$("a").jurlp("password");
$("a").jurlp("password", "password");

$("a").jurlp("host");
$("a").jurlp("host", "www.example.com");

$("a").jurlp("port");
$("a").jurlp("port", "8080");

$("a").jurlp("path");
$("a").jurlp("path", "../file.name");

$("a").jurlp("query");
$("a").jurlp("query", {"param":"value"});

$("a").jurlp("fragment");
$("a").jurlp("fragment", "elementid");

// Filter on URL segments
$("a").jurlp("filter", "scheme", "^=", "http")
      .jurlp("filter", "user", "=", "user")
      .jurlp("filter", "password", "=", "password")
      .jurlp("filter", "host", "=", "www.example.com")
      .jurlp("filter", "port", "!=", "8080")
      .jurlp("filter", "path", "$=", ".html")
      .jurlp("filter", "query", "*=", "param=value")
      .jurlp("filter", "fragment", "regex", /(\#)/);

// Watch a selector for new nodes
$("a:eq(0)").jurlp("watch", function(element, selector){})
            .jurlp("filter", "host", "=", "www.example.com")
            .jurlp("query",{"found":"example"});

$("body").prepend("<a href='http://www.example.com/'></a>");

$("a:eq(0)").jurlp("unwatch");

// Parse an element's text for URLs and create/return anchor elements
$("<div>www.example.com</div>").jurlp();

// Get an interface for parsing/manipulating the supplied URL
url = $.jurlp("http://www.example.com:80/path/file.name?param1=value1#fragment");

// Parse the URL to an object.
url.url();

// Get the URL scheme.
url.scheme();

// Get the URL user name.
url.user();

// Get the URL password.
url.password();

// Get the URL host.
url.host();

// Get the URL port.
url.port();

// Get the URL path.
url.path();

// Get the URL query.
url.query();

// Get a specific parameter value from the URL query.
url.query().param1;

// Get the URL fragment.
url.fragment();

// Set the full URL.
url.url("http://www.example.com:80/path/file.name?param1=value1#fragment");

// Set the URL scheme.
url.scheme("https://");

// Set the URL user name.
url.user("user");

// Set the URL password.
url.password("password");

// Set the URL host.
url.host("www.newexample.com");

// Set the URL port.
url.port("80");

// Set the URL path.
url.path("/newpath/newfile.file");

// Append to the URL path.
url.path("./newfile.file");

// Remove two path elements and append to the URL path.
url.path("../../newfile.file");

// Set the URL query.
url.query("?param=value");

// Append/modify the URL query (string or object)
url.query("param=value");
url.query({"param":"value"});

// Remove the URL query
url.query("");
url.query({});

// Set the URL fragment.
url.fragment("#newfragment");

Parsing document.location.href

Parsing the document URL.

The document URL (document.location.href) can be parsed by specifying the HTML document element to the parser in the following manner;

// Parse the document.location.href URL string into a URL object
$(document).jurlp("url");

Similarly, the document URL can be modified by the plugin, but it is worth noting that changes will not be directly applied to document.location.href until goto is explicitly called on the element, and instead, a working copy of the URL is stored under the documents “data-href” attribute.

// Does not modify document.location.href (updates $(document).data("href"))
$(document).jurlp("url", "www.example.com");

// Does modify document.location.href (from $(document).data("href"))
$(document).jurlp("goto");

Parsing elements with an “href” or “src” attribute.

Parsing “href” or “src” attributes.

Elements with an “href” or “src” attribute (i.e. <a href=””>, <base href=””>, <link href=””>, <img src=””>, <script src=””> or <iframe src=””>), can be parsed by specifying the element(s) to the parser in the following manner;

// Parse all anchor element URLs into an array
$("a").jurlp("url");

Any modifications made to the URL will modify the relevant “href” or “src” attribute directly. If you want to visit the URL within an elements “href” or “src” attribute, it is possible to call goto on the element.

// Directly set the first anchor elements URL, and then goto it!
$("a:eq(0)").jurlp("url", "www.example.com").jurlp("goto");

Parsing element text/HTML.

Parsing text/HTML for URLs.

It is possible for the URL parser to find URLs within text/HTML, and convert them into HTML anchor elements.

// Parse the HTML for URLs, and convert all URLs found in the text to anchors.
$("<div>Here are URLs: www.example1.com, www.example2.com</div>").jurlp();

// HTML becomes:
<div>
    Here are URLs:
    <a href="http://www.example1.com/" class="jurlp-no-watch">www.example1.com</a>,
    <a href="http://www.example2.com/" class="jurlp-no-watch">www.example2.com</a>
</div>

Parsing URL strings directly.

How to directly parse, modify or monitor an arbitrary URL string.

// Get an interface for parsing the document URL...
var url = $.jurlp();

// .. or get an interface for parsing your own URL.
url = $.jurlp("www.example.com");

// Parse the URL to an object.
url.url();

// Get the URL scheme.
url.scheme();

// Get the URL host.
url.host();

// Get the URL port.
url.port();

// Get the URL path.
url.path();

// Get the URL query.
url.query();

// Get a specific parameter value from the URL query.
url.query().parameter;

// Get the URL fragment.
url.fragment();

// Create a watch for new URLs that contain "example.com" in the host name
var watch = $.jurlp("example.com").watch(function(element, selector){
    console.log("Found example.com URL!", element, selector);
});

// We can even apply filters to the watch to be sure!
watch.jurlp("filter", "host", "*=", "example.com");

// Append a new URL, which will trigger the watch
$("body").append("<a href=\"www.example.com\"></a>");

// Stop watching for "example.com" URLs.
watch.jurlp("unwatch");

Unknown URLs.

Overview of unknown URL parsing.

Unknown scheme

The parser will attempt to parse any type of URL it encounters based on its scheme. However, not all URLs are parsable, for example “spotify:track:<trackid>”. In this case, the following URL object is returned;

{
    scheme: "spotify:",
    url: "track:<trackid>"
}

The unknown URL object will always contain the scheme (if present), for filtering purposes, and also contains a toString() method, which will convert the URL object back to the original URL string.

mailto

”mailto:” URLs are parsable in the same manner as a regular HTTP URL. For example, the following URL object is returned for a URL with a “mailto:” scheme;

{
    scheme: "mailto:"
    user: "username",
    password: "",
    host: "www.example.com",
    port: "",
    path: "",
    query: "?subject=subject&body=body",
    fragment: ""
}

Therefore, “mailto:” URLs can be fully parsed using this parser, but note that it is not possible to set the password, port or fragment strings on a “mailto:” URL.

javascript

”javascript” URLs are parsable in the same manner as a regular HTTP URL. For example, the following URL object is returned for a URL with a “javasrcipt:” scheme;

{
    scheme: "javascript:"
    user: "",
    password: "",
    host: "www.example.com",
    port: "",
    path: "/",
    query: "",
    fragment: "",
    javascript: "alert('!');"
}

Therefore, “javascript:” URLs can be fully parsed using this parser, but note that the current “document.location.href” will always be parsed/returned as the main URL object.

Operators.

Overview of filter operators.

The following filter operators may be specified as the “operator” parameter to the filter method.

URL filter operators

”=”	Equal to.
”!=”	Not equal to.
”*=”	Contains.
”<”	Less than.
”<=”	Less than or equal to.
”>”	Greater than.
”>=”	Greater than or equal to.
”^=”	Starts with.
”$=”	Ends with.
”regex”	Regular expression.

this parameter.

Where “this” is refered to as an argument to the method functions, it may be one of the following;

HTML document element.
An array of 1 or more elements with a “href” or “src” attribute.
A URL parser interface returned from $.jurlp().

Internal functions.

All internal private functions.

This section contains all internal functions that perform the grunt work for the parser interface.

Summary

Functions
initialiseElement	Initialise an element for use with the URL parser.
initialiseElementText	Initialise an elements text field for use with the URL parser.
setAttrUrl	Given an element, and an attribute, set the attribute to the supplied URL, and created a backup of the original URL if not already done.
restoreAttrUrl	Given an element, and an attribute, then restore the URL attribute value to its original value.
restoreElement	Destroys any data associated with an element that has previously been initialised for use with the URL parser, and restores the elements “href” or “src” attribute (if any) to its original value.
getHref	Get the href URL for the element.
updateHref	Update a segment of the elements href URL.
updateHrefShim	Shim function for reorganising parameters before calling updateHref().
setHref	Sets the href URL value for an element.
urlToObject	Parse a URL into segments using the DOM.
objectToUrl	Convert a URL object to a string.
sanitiseUrl	Sanitise a URL.
urlObjectToString	Converts a URL object to a string (used to override toString for URL objects).
setUrlSegment	Set the value of a segment within a URL string.
getUrlObject	Convert a URL string to an object, if not already.
getFragmentString	Retrieve the fragment string for a given URL.
getQueryString	Retrieve the query string for a given URL.
updateQuery	Update the query string for the elements URL.
queryStringToObject	Convert a query string to an object.
getQueryObject	Retrieve the query object for a given URL.
queryObjectToString	Query objects toString method.
getPathString	Retrieve the path string for a given URL.
getPathObject	Retrieve the path object for a given URL.
updatePath	Update the path string for the elements URL.
pathObjectToString	Path objects toString method.
getPortString	Retrieve the port string for a given URL.
getHostString	Retrieve the host string for a given URL.
getPasswordString	Retrieve the password string for a given URL.
getUserString	Retrieve the user string for a given URL.
getSchemeString	Retrieve the scheme string for a given URL.
addSelectorCallback	Add a function the selector callstack.
returnEachElement	Apply the callback for each element in this.
returnEachObject	Apply the callback for each element in this, and buffer return codes.
dispatchGetSetHelper	Dispatch to get or set helper functions depending on the arguments supplied.
methodDispatcher	Main method dispatcher for the public interface.

Functions

initialiseElement

var initialiseElement = function ( )

Initialise an element for use with the URL parser.

Parameters

this	The element to initialise. See this parameter.

initialiseElementText

var initialiseElementText = function ( )

Initialise an elements text field for use with the URL parser.

Parameters

this	The element to initialise.

setAttrUrl

var setAttrUrl = function ( attr,
url )

Given an element, and an attribute, set the attribute to the supplied URL, and created a backup of the original URL if not already done.

Note, if the attribute doesn’t exist, then it will not be created.

Parameters

this	The element to set the attribute URL on.
attr	The name of the attribute to set.
url	The value of the attributes URL.

restoreAttrUrl

var restoreAttrUrl = function ( attr )

Given an element, and an attribute, then restore the URL attribute value to its original value.

Parameters

this	The element to restore the attribute URL on.
attr	The name of the attribute to restore.

restoreElement

var restoreElement = function ( )

Destroys any data associated with an element that has previously been initialised for use with the URL parser, and restores the elements “href” or “src” attribute (if any) to its original value.

Parameters

this	The element to destroy.

getHref

var getHref = function ( )

Get the href URL for the element. Prioritises internal objects href, over “data-href”, over “href”, over “src” attributes.

Parameters

this	The element to retieve the URL value from.

updateHref

var updateHref = function ( segment,
value )

Update a segment of the elements href URL.

Parameters

this	The element to update the URL value on.
segment	The segment to update (“scheme”, “host”, “port”, “path”, “query” or “fragment”).
value	The new value for the segment.

updateHrefShim

var updateHrefShim = function ( parameters )

Shim function for reorganising parameters before calling updateHref(). Called via the each callback.

Parameters

this	The element to update the URL value on.
parameters	Array containing segment and value parameters for updateHref().

setHref

var setHref = function ( url )

Sets the href URL value for an element.

Parameters

this	The element to set the URL value on.
url	The new url (string) value.

urlToObject

var urlToObject = function ( url )

Parse a URL into segments using the DOM. Parses authority information from the URL using parseUri (http://blog.stevenlevithan.com/archives/parseuri).

Parameters

url	URL String to parse.

Returns

URL object.

objectToUrl

var objectToUrl = function ( url )

Convert a URL object to a string.

Parameters

url	The URL object to convert.

Returns

URL string.

sanitiseUrl

var sanitiseUrl = function ( url )

Sanitise a URL. Creates a fully qualified URL by converting it from a string to a DOM element and back to a string again.

Parameters

url	The URL to sanitise.

Returns

The sanitised URL string.

urlObjectToString

var urlObjectToString = function ( )

Converts a URL object to a string (used to override toString for URL objects).

Parameters

this	The URL object to convert to a string.

Returns

The URL string.

setUrlSegment

var setUrlSegment = function ( url,
segment,
value )

Set the value of a segment within a URL string.

Parameters

url	The URL to modify.
segment	The segment of the URL to modify (“scheme”, “host”, “port”, “path”, “query” or “fragment”).
value	The new segment value.

Returns

The URL string containing the update segment.

getUrlObject

var getUrlObject = function ( url )

Convert a URL string to an object, if not already. Used to ensure we always work with URL objects where either a string or object can be supplied.

Parameters

url	URL string or object.

Returns

URL object.

getFragmentString

var getFragmentString = function ( url )

Retrieve the fragment string for a given URL.

Parameters

url	URL string or object.

Returns

The fragment string.

getQueryString

var getQueryString = function ( url )

Retrieve the query string for a given URL.

Parameters

url	URL string or object.

Returns

The query string.

updateQuery

var updateQuery = function ( query )

Update the query string for the elements URL.

Parameters

this	The element to set the new query string on.
query	New query object.

queryStringToObject

var queryStringToObject = function ( query )

Convert a query string to an object.

Parameters

query

Query string to convert to an object.

Returns

The query object.

getQueryObject

var getQueryObject = function ( url )

Retrieve the query object for a given URL.

Parameters

url	URL string or object.

Returns

The query object.

queryObjectToString

var queryObjectToString = function ( )

Query objects toString method.

Parameters

this	Query object.

Returns

The query string.

getPathString

var getPathString = function ( url )

Retrieve the path string for a given URL.

Parameters

url	URL string or object.

Returns

The path string.

getPathObject

var getPathObject = function ( url )

Retrieve the path object for a given URL.

Parameters

url	URL string or object.

Returns

The path obbject.

updatePath

var updatePath = function ( path )

Update the path string for the elements URL.

Parameters

this	The element to set the new path string on.
path	New path object.

pathObjectToString

var pathObjectToString = function ( )

Path objects toString method.

Parameters

this	Path object.

Returns

The path string.

getPortString

var getPortString = function ( url )

Retrieve the port string for a given URL.

Parameters

url	URL string or object.

Returns

The port string.

getHostString

var getHostString = function ( url )

Retrieve the host string for a given URL.

Parameters

url	URL string or object.

Returns

The host string.

getPasswordString

var getPasswordString = function ( url )

Retrieve the password string for a given URL.

Parameters

url	URL string or object.

Returns

The password string.

getUserString

var getUserString = function ( url )

Retrieve the user string for a given URL.

Parameters

url	URL string or object.

Returns

The user string.

getSchemeString

var getSchemeString = function ( url )

Retrieve the scheme string for a given URL.

Parameters

url	URL string or object.

Returns

The scheme string.

addSelectorCallback

var addSelectorCallback = function ( element,
callback,
parameters )

Add a function the selector callstack.

returnEachElement

var returnEachElement = function ( callback,
parameters )

Apply the callback for each element in this. Used for methods that return elements.

Parameters

this Array of elements to iterate through.

callback Function to call for each element found.

parameters Callback function parameters (array).

Returns

Array of elements.

returnEachObject

var returnEachObject = function ( callback,
parameters )

Apply the callback for each element in this, and buffer return codes. Used for methods that return data.

Parameters

this Array of elements to iterate through.

callback Function to call for each element found.

parameters Callback function parameters (array).

Returns

Array of return codes.

dispatchGetSetHelper

var dispatchGetSetHelper = function ( getHelper,
setHelper,
helperArguments )

Dispatch to get or set helper functions depending on the arguments supplied.

If no user arguments are supplied, perform the get, ortherwise perform the set with the user arguments.

Parameters

getHelper	Get URL data callback.
setHelper	Set URL data callback.
helperArguments	User arguments supplied to the public interface.

Returns

get/setHelper() return code.

methodDispatcher

var methodDispatcher = function ( method )

Main method dispatcher for the public interface.

Parameters: method

method

The method to perform.

Returns

Array of method handler results (either elements for set/filter methods, or strings/objects for get methods).

URI parser interface.

All URI parsing is handled through this interface.

This section contains all parser interfaces utilised by the public parser interface.

ToDo: Extend this interface with the current URL segment parsing logic, and implement a more comprehensive URI parser set.

See http://en.wikipedia.org/wiki/URI_scheme for an overview of URIs.

Summary

Functions
uri.toString.http	Converts a URI object with an “http” scheme to a string.
uri.toString.mailto	Converts a URI object with a “mailto:” scheme to a string.
uri.toString.javascript	Converts a URI object with a “javascript:” scheme to a string.
uri.toString.generic	Converts an generic URI object to a string.
uri.parsers.http	Parse a URI with a “http://” scheme into a URI object.
uri.parsers.mailto	Parse a URI with a “mailto:” scheme into a URI object.
uri.parsers.javascript	Parse a URI with a “javascript:” scheme into a URI object.
uri.parsers.generic	Parses any URI (URIs with a scheme seperator of “://” are parsed as “http://”, everything else is treated as unknown..
uri.parse	Parse a URI string based on scheme.

Functions

uri.toString.http

Converts a URI object with an “http” scheme to a string.

uri.toString.mailto

Converts a URI object with a “mailto:” scheme to a string.

uri.toString.javascript

Converts a URI object with a “javascript:” scheme to a string.

uri.toString.generic

Converts an generic URI object to a string.

uri.parsers.http

Parse a URI with a “http://” scheme into a URI object.

uri.parsers.mailto

Parse a URI with a “mailto:” scheme into a URI object.

uri.parsers.javascript

Parse a URI with a “javascript:” scheme into a URI object.

uri.parsers.generic

Parses any URI (URIs with a scheme seperator of “://” are parsed as “http://”, everything else is treated as unknown..

uri.parse

Parse a URI string based on scheme.

Helper interface.

All private helper methods.

This section contains all get/set and filter methods utilised by the public interface.

Summary

Functions
getUrl	Return the elements URL (stored under its “data-href”, and/or “href”/”src” attribute).
setUrl	Set the elements URL (stored under it’s “data-href”, and/or “href”/”src” attribute).
parseUrl	Return the URL object for the elements “data-href” attribute value.
getFragment	Get the fragment object from the elements URL.
setFragment	Set the fragment string for the elements URL.
getQuery	Get the query object from the elements URL.
setQuery	Set the query string for the elements URL.
getPath	Get the path object from the elements URL.
setPath	Set the path string for the elements URL.
getPort	Get the port string from the elements URL.
setPort	Set the port string for the elements URL.
getHost	Get the host string from the elements URL.
setHost	Set the host string for the elements URL.
getPassword	Get the password string from the elements URL.
setPassword	Set the password string for the elements URL.
getUser	Get the user string from the elements URL.
setUser	Set the user string for the elements URL.
getScheme	Get the scheme string from the elements URL.
setScheme	Set the scheme string for the elements URL.
= (equals)	Test if the actual value is equal to the user supplied value.
!= (not equals)	Test if the actual value is equal to the user supplied value.
< (less than)	Test if the actual value is less than the user supplied value.
> (greater than)	Test if the actualValue is greater than the user supplied value.
<= (less than or equal to)	Test if the actual value is less than or equal to the user supplied value.
>= (greater than or equal to)	Test if the actual value is greater than or equal to the user supplied value.
*= (contains)	Test if the actual value contains the user supplied value.
^= (starts with)	Test if the start of the actual value matches the user supplied value.
$= (ends with)	Test if the end of the actual value is the same as the user supplied value.
regex (regular expression)	Test if the actual value matches the user supplied regular expression.

Functions

getUrl

"getUrl" : function ( )

Return the elements URL (stored under its “data-href”, and/or “href”/”src” attribute).

setUrl

"setUrl" : function ( url )

Set the elements URL (stored under it’s “data-href”, and/or “href”/”src” attribute). Note: This does not change document.location.href for the $(document) element!

parseUrl

"parseUrl" : function ( )

Return the URL object for the elements “data-href” attribute value.

getFragment

"getFragment" : function ( )

Get the fragment object from the elements URL.

Parameters

this	The element to retrieve the fragment object from.

Returns

The fragment object. Call .toString() on the object to convert it to a string value.

setFragment

"setFragment" : function ( fragment )

Set the fragment string for the elements URL.

Parameters

this	The element to set the fragment string on.
fragment	The new fragment string/object.

Returns

Array of elements that were changed.

getQuery

"getQuery" : function ( )

Get the query object from the elements URL.

Parameters

this	The element to retrieve the query object from.

Returns

The query object. Call .toString() on the object to convert it to a string value.

setQuery

"setQuery" : function ( query )

Set the query string for the elements URL.

Parameters

this	The element to set the query object on.
query	The new query string represented as an object.

Returns

Array of elements that were changed.

getPath

"getPath" : function ( )

Get the path object from the elements URL.

Parameters

this	The element to retrieve the path object from.

Returns

The path object. Call .toString() on the object to convert it to a string value.

setPath

"setPath" : function ( path )

Set the path string for the elements URL.

Parameters

this	The element to set the path string on.
path	The new path string/object.

Returns

Array of elements that were changed.

getPort

"getPort" : function ( )

Get the port string from the elements URL.

Parameters

this	The element to retrieve the port string from.

Returns

The port string.

setPort

"setPort" : function ( port )

Set the port string for the elements URL.

Parameters

this	The element to set the port string on.
port	The new port string.

Returns

Array of elements that were changed.

getHost

"getHost" : function ( )

Get the host string from the elements URL.

Parameters

this	The element to retrieve the host string from.

Returns

The host string.

setHost

"setHost" : function ( host )

Set the host string for the elements URL.

Parameters

this	The element to set the host string on.
host	The new host string.

Returns

Array of elements that were changed.

getPassword

"getPassword" : function ( )

Get the password string from the elements URL.

Parameters

this	The element to retrieve the password string from.

Returns

The password string.

setPassword

"setPassword" : function ( password )

Set the password string for the elements URL.

Parameters

this	The element to set the password string on.
password	The new password string.

Returns

Array of elements that were changed.

getUser

"getUser" : function ( )

Get the user string from the elements URL.

Parameters

this	The element to retrieve the user string from.

Returns

The user string.

setUser

"setUser" : function ( user )

Set the user string for the elements URL.

Parameters

this	The element to set the user string on.
user	The new user string.

Returns

Array of elements that were changed.

getScheme

"getScheme" : function ( )

Get the scheme string from the elements URL.

Parameters

this	The element to retrieve the scheme string from.

Returns

The scheme string.

setScheme

"setScheme" : function ( scheme )

Set the scheme string for the elements URL.

Parameters

this	The element to set the scheme string on.
scheme	The new scheme string.

Returns

Array of elements that were changed.

= (equals)

"=" : function ( actualValue,
userValue )

Test if the actual value is equal to the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual and user values are equal.
false	The actual and user values are not equal.

!= (not equals)

"!=" : function ( actualValue,
userValue )

Test if the actual value is equal to the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual and user values are not equal.
false	The actual and user values are equal.

< (less than)

Test if the actual value is less than the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual value is less than the user supplied value.
false	The actual value is greater than or equal to the user supplied value.

> (greater than)

">" : function ( actualValue,
userValue )

Test if the actualValue is greater than the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual value is greater than the user supplied value.
false	The actual value is less than or equal to the user supplied value.

<= (less than or equal to)

Test if the actual value is less than or equal to the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual value is less than or equal to the user supplied value.
false	The actual value is greater than the user supplied value.

>= (greater than or equal to)

">=" : function ( actualValue,
userValue )

Test if the actual value is greater than or equal to the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual value is greater than or equal to the user supplied value.
false	The actual value is less than the user supplied value.

*= (contains)

"*=" : function ( actualValue,
userValue )

Test if the actual value contains the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The actual value contains the user supplied value.
false	The actual value does not contain the user supplied value.

^= (starts with)

"^=" : function ( actualValue,
userValue )

Test if the start of the actual value matches the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The start of the actual value matches the user supplied value.
false	The start of the actual value does not match the user supplied value.

$= (ends with)

"$=" : function ( actualValue,
userValue )

Test if the end of the actual value is the same as the user supplied value.

Parameters

actualValue	Actual value.
userValue	User supplied value.

Returns

true	The end of the actual value matches the user supplied value.
false	The end of the actual value does not match the user supplied value.

regex (regular expression)

"regex" : function ( actualValue,
userValue )

Test if the actual value matches the user supplied regular expression.

Parameters

actualValue	Actual value.
userValue	Regular expression to apply.

Returns

true	The regular expression matches.
false	The regular expression does not match.

Public interface.

All public methods exposed via the JQuery URL parser plugin interface.

Summary

Functions
url	Get/Set the href string for the given element(s).
fragment	Get/Set the fragment segment of the URL for the given element(s).
query	Get/Set the query segment of the URL for the given element(s).
path	Get/Set the path segment of the URL for the given element(s).
port	Get/Set the port segment of the URL for the given element(s).
host	Get/Set the host segment of the URL for the given element(s).
password	Get/Set the password segment of the URL for the given element(s).
user	Get/Set the user segment of the URL for the given element(s).
scheme	Get/Set the scheme segment of the URL for the given element(s).
initialise	Initialise the parser for the given element(s).
restore	Removes any parser data associated with the element(s), and sets the href attribute to its original value.
goto	Set document.location.href to the supplied elements “href”, “src” or “data-href” attribute value.
proxy	Proxy the URL.
watch	Automatically apply all modifications to new elements added to the DOM that match the selector for the supplied elements.
unwatch	Removes a watch previously created with watch, and prevents modifications being made to new elemenets of the same selector.
filter	Filters elements by URL or URL segment.
interface	Get the available methods for the parser interface.

Functions

url

"url" : function ( url )

Get/Set the href string for the given element(s).

Parameters

this	See this parameter.
url	If present, specifies the new URL object/string to set. Otherwise the function will get the URL.

Returns

If a URL was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of element URLs.

Examples

// Parse the document.location.href URL
$(document).jurlp("url");

// Parse all URLs in anchor tags
$("a").jurlp("url");

// Update the working URL for the document
$(document).jurlp("url", "http://www.google.com");

// Replace all anchor tags with the google URL!
$("a").jurlp("url", "http://www.google.com");

// Output the documents URL object
console.log($(document).jurlp("url"));

// Output the documents URL string
console.log($(document).jurlp("url").toString());

fragment

"fragment" : function ( fragment )

Get/Set the fragment segment of the URL for the given element(s).

Parameters

this	See this parameter.
fragment	If present, specifies the new fragment string to set. Otherwise the function will get the fragment string from each elements URL.

Returns

If a fragment string was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of URL fragments from each element.

Examples

// Parse the document.location.href URL for the fragment string
$(document).jurlp("fragment");

// Parse all URLs in anchor tags and retrieve their fragment strings
$("a").jurlp("fragment");

// Set a new fragment for the document
$(document).jurlp("fragment", "elementid");

// Replace the fragment string in all anchor tags with the new element ID
$("a").jurlp("fragment", "elementid");

// Output the documents URL fragment
console.log($(document).jurlp("fragment"));

query

"query" : function ( query )

Get/Set the query segment of the URL for the given element(s).

Parameters

this	See this parameter.
query	If present, specifies the new query object to set. Otherwise the function will get the query object from each elements URL.

Returns

If a query object was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of URL query objects from each element. Each returned query object can be converted to a string by calling its toString() method.

Examples

// Parse the document.location.href URL for the query object
$(document).jurlp("query");

// Parse all URLs in anchor tags and retrieve their query object
$("a").jurlp("query");

// Set/update the "new" parameter in the query string for the document
$(document).jurlp("query", {"new":"parameter"});

// Remove the query string for the document
$(document).jurlp("query", {});

// Update the query string in all anchor tags with the new query object.
$("a").jurlp("query", {"new":"parameter"});

// Remove the query string in all anchor tags.
$("a").jurlp("query", {});

// Output the documents URL query object
console.log($(document).jurlp("query"));

// Output the documents URL query string
console.log($(document).jurlp("query").toString());

path

"path" : function ( path )

Get/Set the path segment of the URL for the given element(s).

Parameters

this	See this parameter.
path	If present, specifies the new path to set. Otherwise the function will get the path object from each elements URL.

A quick guide to paths

Leading slashes (i.e. “/index.html”) set the full path.
No leading slash (or a “./”) will append to the existing path.
You can use “../” to remove elements from the existing path, or the path string you supply (which makes concatinating an existing file path and new path easy, as specifying a leading “../” in the new path will remove the file name segment of the existing path).

Returns

If a path was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of URL path objects from each element. Each returned path object can be converted to a string by calling its toString() method.

Examples

// Parse the document.location.href URL for the path object
$(document).jurlp("path");

// Parse all URLs in anchor tags and retrieve their path object
$("a").jurlp("path");

// Set a new path for the document
$(document).jurlp("path", "/index.html");

// Append a path to the document URLs path
$(document).jurlp("path", "./file.name");

// Append a path to the document URLs path, which removes 2 existing path
// elements before appending the new path
$(document).jurlp("path", "../../folder/file.name");

// Update the file name segment of the path in all anchor tags
// with the new file name.
$("a").jurlp("path", "../file.name");

// Remove the path in all anchor tags.
$("a").jurlp("path", "/");

// Output the documents URL path object
console.log($(document).jurlp("path"));

// Output the documents URL path string
console.log($(document).jurlp("path").toString());

port

"port" : function ( port )

Get/Set the port segment of the URL for the given element(s).

Parameters

this	See this parameter.
port	If present, specifies the new port to set. Otherwise the function will get the port string from each elements URL.

Returns

If a port was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of port strings from each elements URL.

Examples

// Parse the document.location.href URL for the port
$(document).jurlp("port");

// Parse all URLs in anchor tags and retrieve their port
$("a").jurlp("port");

// Set a new port for the document
$(document).jurlp("port", "8080");

// Replace the port in all anchor tags with the new port number
$("a").jurlp("port", "8080");

// Output the documents URL port
console.log($(document).jurlp("port"));

host

"host" : function ( host )

Get/Set the host segment of the URL for the given element(s).

Parameters

this	See this parameter.
host	If present, specifies the new host name to set. Otherwise the function will get the host name string from each elements URL.

Returns

If a host name was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of host name strings from each elements URL.

Examples

// Parse the document.location.href URL for the host name
$(document).jurlp("host");

// Parse all URLs in anchor tags and retrieve their host name
$("a").jurlp("host");

// Set a new host name for the document
$(document).jurlp("host", "www.example.com");

// Replace the host name in all anchor tags with the new host name
$("a").jurlp("host", "www.example.com");

// Output the documents URL host name
console.log($(document).jurlp("host"));

password

"password" : function ( password )

Get/Set the password segment of the URL for the given element(s).

Note! A password cannot be set on a URL unless a user name has been set first (see user).

Parameters

this	See this parameter.
password	If present, specifies the new password to set. Otherwise the function will get the password string from each elements URL.

Returns

If a password was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of password strings from each elements URL.

Examples

// Parse all URLs in anchor tags and retrieve their password
$("a").jurlp("password");

// Replace the password in all anchor tags with the new password string
$("a").jurlp("password", "newpassword");

user

"user" : function ( user )

Get/Set the user segment of the URL for the given element(s).

Parameters

this	See this parameter.
user	If present, specifies the new username to set. Otherwise the function will get the username string from each elements URL.

Returns

If a username was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of username strings from each elements URL.

Examples

// Parse all URLs in anchor tags and retrieve their username
$("a").jurlp("user");

// Replace the username in all anchor tags with the new username string
$("a").jurlp("username", "newusername");

scheme

"scheme" : function ( scheme )

Get/Set the scheme segment of the URL for the given element(s).

Parameters

this	See this parameter.
scheme	If present, specifies the new scheme. Otherwise the function will get the scheme string from each elements URL.

Returns

If a scheme string was specified, then this function returns the array of modified elements for chaining purposes, otherwise it returns an array of scheme strings from each elements URL.

Examples

// Parse the document.location.href URL for the scheme
$(document).jurlp("scheme");

// Parse all URLs in anchor tags and retrieve their scheme
$("a").jurlp("scheme");

// Set a new scheme name for the document
$(document).jurlp("scheme", "https://");

// Replace the scheme in all anchor tags href attributes
$("a").jurlp("scheme", "https://");

// Output the documents URL host name
console.log($(document).jurlp("scheme"));

initialise

"initialise" : function ( )

Initialise the parser for the given element(s). HTML anchor elements or the HTML document element need not be explicitly initialised.

Elements are initialised as follows;

$(document)	Initialise the “data-href” attribute for the document with the value of “document.location.href”. The “data-href” attribute will be modified instead of “document.location.href” when modifying this element. See Parsing document.location.href.
Elements with “href”/”src” attributes	An attribute named “data-original-href” or “data-original-src” is created to store a copy of the elements original “href”/”src” attribute at the time of initialisation. See <Parsing elements with an href or src attribute>.
All other elements	Parses the element HTML for URLs, wraps any URLs found in an anchor tag, and returns all anchor elements.

Parameters

this	See this parameter.

Returns

Array of initialised elements (minus the parent container element).

Examples

// Not necessary
$(document).jurlp();

// Not necessary
$("a").jurlp();

// Parse the HTML for URLs, and convert all URLs found in the
// text to anchors tags, and return the anchor elements.
$("<div>www.example.com</div>").jurlp();

restore

"restore" : function ( )

Removes any parser data associated with the element(s), and sets the href attribute to its original value.

$(document)	Removes the “data-href” attribute.
Elements with “href”/”src”	Restores the “href”/”src” attribute to the “data-original-href/src” attribute value, and removes any other added attributes.
All other elements	Currently there is no way to restore an elements HTML which has been converted by the parser, so consider saving it first if needed!

Parameters

this	See this parameter.

Returns

Array of elements which were restored for chaining purposes.

Examples

// Restore the working URL for the document.
$(document).jurlp("restore");

// Restore the URL for all anchor elements.
$("a").jurlp("restore");

goto

"goto" : function ( )

Set document.location.href to the supplied elements “href”, “src” or “data-href” attribute value.

Parameters

this	See this parameter.

Examples

// Goto the documents URL.
$(document).jurlp("goto");

proxy

"proxy" : function ( url,
parameter )

Proxy the URL. The elements URL will be replaced with the proxy URL, and the original URL will be encapsulated under the query string using the parameter name specified.

Parameters

this	See this parameter.
url	The proxy URL.
parameter	The name of the query string parameter to encapsulate the original URL in.

Returns

Array of modified elements for chaining purposes.

Examples

// Proxy all URLs in anchor tags to www.example.com
// URL becomes "http://www.example.com/?url=<original URL>"
$("a").jurlp("proxy", "http://www.example.com", "url");

watch

"watch" : function ( callback )

Automatically apply all modifications to new elements added to the DOM that match the selector for the supplied elements. This allows URL filters/modifications that have been applied to existing elements to be propogated to new elements if the page content is being modified (i.e. inserting new anchor tags via AJAX).

Overview

Watch will monitor the selector of the supplied elements via a DOM node listener to detect when new elements are inserted. For each new element that is inserted, any prior filters or modifications made to URLs with the same selector will be applied, and the watcher will be alerted via a callback.

Note! It is not possible to call watch more than once for the same selector. To do this, try naming the selector differently, i.e. instead of “a”, use “a:not(uniqueid)”, where “uniqueid” is a nice lengthy descriptive name!

To stop watching for updates on a selecter, use unwatch.

Parameters

this	Array of elements to obtain the selector from. See this parameter.
callback	Function to call when elements are found, which is supplied two arguments, the new element that was inserted into the DOM, and the selector that triggered the watch.

Returns

Array of unmodified elements for chaining purposes.

Examples

// Add a watch on the first anchor element, and if the host name is
// "www.example.com", set the URL query string to "found=example".
// The "filter" and "query" calls will also be applied to all new elements that
// watch discovers!..
$("a:eq(0)").jurlp("watch", function(element, selector){
    // If we get here, the first anchor element has changed to a URL containing
    // "www.example.com" and now contains "found=example" in the query string.
    // Dump the URL object to prove it!
    console.log($(element).jurlp("url"));
}).jurlp("filter", "host", "=", "www.example.com")
  .jurlp("query",{"found":"example"});

//  Prepend a new anchor tag to the page. This will trigger the watch on the
//  "a:eq(0)" selector, which will apply all prior calls to this selector,
//  so in this instance:
//  - First perform the filter host, to ensure the host name is "www.example.com".
//  - If the host name matches, update the URL query string with "found=example").
// If the host name does not match, then the query string will not be set.

$("body").prepend ( "<a href='http://www.example.com/'></a>" );

// Stop watching for updates on the "a:eq(0)" selector.
// The "a:eq(0)" selector can now be watched on again.
$("a:eq(0)").jurlp("unwatch");

Watching the “same selector”:

// As an arbitrary example, we want to modify the query string on all existing
// facebook/twitter URLs, and then watch the "a" selector for all new
// facebook/twitter URLs that appear, and apply the new query string to those too:

// THIS WILL NOT WORK!:
$("a").jurlp("watch").
      .jurlp("filter", "host", "=", "www.facebook.com").
      .jurlp("query",{"found":"facebook"});

// This call will fail, as the "a" selector is now watched.
$("a").jurlp("watch").
      .jurlp("filter", "host", "=", "www.twitter.com")
      .jurlp("query",{"found":"twitter"});

// THIS WILL WORK!:
$("a:not(facebook)").jurlp("watch").
                    .jurlp("filter", "host", "=", "www.facebook.com")
                    .jurlp("query",{"found":"facebook"});

$("a:not(twitter)").jurlp("watch")
                   .jurlp("filter", "host", "=", "www.twitter.com")
                   .jurlp("query",{"found":"twitter"});

unwatch

"unwatch" : function ( )

Removes a watch previously created with watch, and prevents modifications being made to new elemenets of the same selector. This will also clear the list of modifications for the selector, and the selector is free to use in a sebsequent call to watch.

Parameters

this	Array of elements to obtain the selector from.

Returns

Array of unmodified elements for chaining purposes.

Examples

// Create a watch on the "a" selector
$("a").jurlp("watch");

// Remove the watch on the "a" selector
$("a").jurlp("unwatch");

filter

"filter" : function ( segment,
operator,
value )

Filters elements by URL or URL segment.

Parameters

this	Array of elements to filter. See this parameter.
segment	The URL segment to filter on (either “scheme”, “host”, “port”, “path”, “query” or “fragment”), or “url” to filter on the full URL. See URL overview for more information.
operator	The type of filtering to apply (either “!=”, “$=”, “*=”, “<”, “<=”, “=”, “>”, “>=” or “^=”). See Operators for more information.
value	The value of the item to filter on.

Returns

Filtered element array for chaining purposes.

Examples

// Get the URL object for all anchors that match
// the document URLs host name.
$("a").jurlp("filter", "host", "=", $(document).jurlp("host"))
      .jurlp("url");

// Get the URL object for all anchors that match
// the document URLs host, and has a path ending in ".php".
$("a").jurlp("filter", "host", "=", $(document).jurlp("host"))
      .jurlp("filter", "path", "$=", ".php")
      .jurlp("url");

// Get the URL object for all anchors whose query
// string matches the regular expression
$("a").jurlp("filter", "query", "regex", /(\?)/).jurlp("url");

interface

"interface" : function ( )

Get the available methods for the parser interface.

Returns

Array of interface methods.

Examples

// Return all methods exposed by the URL parser interface.
$.fn.jurlp ( "interface" );

JQuery plugin interface.

Summary

Functions
$.fn.jurlp	Public interface/method dispatcher for the JQuery URL parser.
$.jurlp	Returns an interface for directly parsing, manipulating and monitoring the supplied URL.

Functions

$.fn.jurlp

$.fn.jurlp = function ( method )

Public interface/method dispatcher for the JQuery URL parser.

See Public interface for more information on the available methods.

See initialise for more specific information on how elements are initialised by the parser.

Parameters

this	Element(s) to process. See this parameter.
method	See Public interface for an overview of available methods and arguments.
arguments	Method arguments.

Returns

Either an array of elements for chaining purposes, or array of specific values, depending on the method called.

$.jurlp

$.jurlp = function ( url )

Returns an interface for directly parsing, manipulating and monitoring the supplied URL.

Parameters

url	The URL string to provide a URL parser interface for. Defaults to document.location.href if no URL is supplied.

Returns

The URL parser interface for the given URL.

Members

href	The URL string.

Methods

url	See url.
scheme	See scheme.
user	See user.
password	See password.
host	See host.
port	See port.
path	See path.
query	See query.
fragment	See fragment.
proxy	See proxy.
goto	See goto.
watch	Sets a watch for all “href” and “src” attributes containing the URLs hostname (selector is “[href=”host”],[src=”host”]” where host is this.host()), and returns all elements of the same selector for chaining purposes. See watch for more information.
unwatch	Removes a watch created for the current URLs hostname. See unwatch.

Examples

See Parsing URL strings directly.