0
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
1 (jQuery) URL Parser v2.2
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
2 ======================
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
3
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
4 An AMD compatible utility to parse urls and provide easy access to their attributes (such as the protocol, host, port etc), path segments, querystring parameters, fragment parameters and more.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
5
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
6 The core parser functionality is based on the [Regex URI parser by Steven Levithan](http://blog.stevenlevithan.com/archives/parseuri), and the query string parsing is handled by a modified version of [node-querystring](https://github.com/visionmedia/node-querystring).
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
7
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
8 **Note this used to have a jQuery dependency - this is now optional. See below for details**
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
9
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
10 **License:** Available for use under a MIT-style license. If you need a different license for any reason please just let me know.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
11
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
12 To jQuery or *not* to jQuery, that is the question...
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
13 ----------------------------------------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
14
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
15 This utility can be used in two ways - with jQuery or without. There is just one file (purl.js) for both versions - if jQuery is included on the page before it then it will provide the 'jQuery-style' interface (see examples below), otherwise it will be accessible via the global `purl` variable.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
16
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
17 The jQuery version has an additional feature that lets it extract the URL from a jQuery element object, where appropriate.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
18
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
19 Specifying the URL to parse
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
20 ---------------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
21
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
22 There are a few different ways to choose what URL to parse:
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
23
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
24 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
25 /*---- jQuery version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
26 var url = $.url(); // parse the current page URL
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
27 var url = $.url('http://allmarkedup.com'); // pass in a URI as a string and parse that
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
28 var url = $('#myElement').url(); // extract the URL from the selected element and parse that - will work on any element with a `src`, `href` or `action` attribute.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
29
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
30 /*---- plain JS version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
31 var url = purl(); // parse the current page URL
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
32 var url = purl('http://allmarkedup.com'); // pass in a URI as a string and parse that
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
33 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
34
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
35 URL attributes
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
36 --------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
37
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
38 The `.attr()` method is used to return information on various parts of the URL. For example:
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
39
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
40 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
41 var url = $.url('http://allmarkedup.com/folder/dir/index.html?item=value'); // jQuery version
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
42 var url = purl('http://allmarkedup.com/folder/dir/index.html?item=value'); // plain JS version
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
43 url.attr('protocol'); // returns 'http'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
44 url.attr('path'); // returns '/folder/dir/index.html'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
45 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
46
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
47 The attributes available for querying are:
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
48 <table>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
49 <tr><td>source</td><td>The whole url being parsed</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
50 <tr><td>protocol</td><td>eg. http, https, file, etc</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
51 <tr><td>host</td><td>eg. www.mydomain.com, localhost etc</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
52 <tr><td>port</td><td>eg. 80</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
53 <tr><td>base</td><td>The url base (eg. http://www.mydomain.com, https://www.mydomain.com etc)</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
54 <tr><td>relative</td><td>The relative path to the file including the querystring (eg. /folder/dir/index.html?item=value)</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
55 <tr><td>path</td><td>The path to the file (eg. /folder/dir/index.html)</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
56 <tr><td>directory</td><td>The directory part of the path (eg. /folder/dir/)</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
57 <tr><td>file</td><td>The basename of the file eg. index.html</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
58 <tr><td>query</td><td>The entire query string if it exists, eg. item=value&item2=value2</td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
59 <tr><td>fragment or anchor</td><td>The entire string after the # symbol </td></tr>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
60 </table>
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
61
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
62 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
63 > url = $.url("http://markdown.com/awesome/language/markdown.html?show=all#top");
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
64 > url.attr('source');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
65 "http://markdown.com/awesome/language/markdown.html?show=all#top"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
66
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
67 > url.attr('protocol');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
68 "http"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
69
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
70 > url.attr('host');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
71 "markdown.com"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
72
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
73 > url.attr('relative');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
74 "/awesome/language/markdown.html?show=all#top"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
75
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
76 > url.attr('path');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
77 "/awesome/language/markdown.html"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
78
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
79 > url.attr('directory');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
80 "/awesome/language/"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
81
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
82 > url.attr('file');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
83 "markdown.html"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
84
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
85 > url.attr('query');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
86 "show=all"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
87
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
88 > url.attr('fragment');
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
89 "top"
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
90 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
91
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
92
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
93 There are also a few more obscure ones available too if you want to dig about a bit ;-)
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
94
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
95 If you don't specify an attribute then this method will return an object literal with all the available attribute key:value pairs in it.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
96
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
97 Query string parameters
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
98 -----------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
99
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
100 The `.param()` method is used to return the values of querystring parameters.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
101
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
102 Pass in a string to access that parameter's value:
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
103
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
104 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
105 /*---- jQuery version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
106 $.url('http://allmarkedup.com?sky=blue&grass=green').param('sky'); // returns 'blue'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
107
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
108 /*---- plain JS version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
109 purl('http://allmarkedup.com?sky=blue&grass=green').param('sky'); // returns 'blue'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
110 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
111
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
112 If no argument is passed in it will return an object literal containing a key:value map of all the querystring parameters.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
113
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
114 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
115 /*---- jQuery version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
116 $.url('http://allmarkedup.com?sky=blue&grass=green').param(); // returns { 'sky':'blue', 'grass':'green' }
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
117
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
118 /*---- plain JS version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
119 purl('http://allmarkedup.com?sky=blue&grass=green').param(); // returns { 'sky':'blue', 'grass':'green' }
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
120 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
121
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
122 Note that the `.param()` method will work on both ampersand-split and semicolon-split querystrings.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
123
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
124 *As of version 2.2 the param method now handles array-style query string params.*
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
125
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
126 URL segments
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
127 -----------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
128
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
129 The `.segment()` method is used to return values of individual segments from the URL's path.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
130
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
131 Pass in an integer value to get the value of that segment - note however that the count is *not* zero-indexed like an array - i.e. `.segment(1)` returns the *first* segment, not the second one.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
132
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
133 You can also pass in negative values, in which case it will count back from the end of the path rather than forwards from the start.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
134
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
135 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
136 var url = $.url('http://allmarkedup.com/folder/dir/example/index.html'); // jQuery version
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
137 var url = purl('http://allmarkedup.com/folder/dir/example/index.html'); // plain JS version
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
138 url.segment(1); // returns 'folder'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
139 url.segment(-2); // returns 'example'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
140 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
141 If no argument is passed in it will return an array of all the segments (which will be zero-indexed!).
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
142
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
143 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
144 $.url('http://allmarkedup.com/folder/dir/example/index.html').segment(); // jQuery version - returns ['folder','dir','example','index.html']
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
145 purl('http://allmarkedup.com/folder/dir/example/index.html').segment(); // plain JS version - returns ['folder','dir','example','index.html']
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
146 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
147
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
148 Fragment parameters and/or segments
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
149 -------------------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
150
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
151 Some sites and apps also use the hash fragment to store querystring-style key value pairs (eg. `http://test.com/#sky=blue&grass=green`), or slash-delimited paths (eg. `http://test.com/#/about/us/`).
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
152
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
153 There are two methods available for extracting information from fragments of these types - `.fparam()` and `.fsegment()`, both of which behave indentically to their `.param()` and `.segment()` counterparts but act on the fragment rather than the main URL.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
154
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
155 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
156 /*---- jQuery version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
157 $.url('http://test.com/#sky=blue&grass=green').fparam('grass'); // returns 'green'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
158 $.url('http://test.com/#/about/us/').fsegment(1); // returns 'about'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
159
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
160 /*---- plain JS version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
161 purl('http://test.com/#sky=blue&grass=green').fparam('grass'); // returns 'green'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
162 purl('http://test.com/#/about/us/').fsegment(1); // returns 'about'
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
163 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
164
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
165 Strict mode and relative URLs
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
166 --------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
167
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
168 Internally this plugin uses Steven Levithan's excellent Regex URI parser, which has two modes - loose and strict. This plugin uses the loose mode by default (i.e. strict mode set to `false`), which deviates slightly from the specs but can produce more intuitive results in some situations. However, loose mode will not correctly parse relative URLs, so you can optionally enable strict mode when calling the plugin as follows:
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
169
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
170 ``` javascript
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
171 /*---- jQuery version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
172 var url = $.url(true); // parse the current page URL in strict mode
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
173 var url = $.url('http://allmarkedup.com',true); // pass in a URI as a string and parse that in strict mode
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
174 var url = $('#myElement').url(true); // extract the URL from the selected element and parse that in strict mode
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
175
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
176 /*---- plain JS version -----*/
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
177 var url = purl(true); // parse the current page URL in strict mode
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
178 var url = purl('http://allmarkedup.com',true); // pass in a URI as a string and parse that in strict mode
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
179 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
180
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
181
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
182 A note on improperly encoded URLs
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
183 ---------------------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
184
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
185 If you attempt to use this plugin to parse a URL that has an invalid character encoding in it, it will throw a `URIError` Exception. This will happen if the URL has a percentage sign followed by either a non-numeric character or a numeric value of greater than 80 (i.e. 128 in decimal).
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
186
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
187 If there is a chance you may end up parsing a badly encoded URL you should probably wrap your calls to this plugin in a try/catch block to prevent this causing unforseen problems.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
188
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
189 Thanks to [steve78b](https://github.com/steve78b) for pointing this out.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
190
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
191 Older versions and compatability
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
192 ---------------------------------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
193
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
194 Please note that v2.x is **not** backwards compatible with v1.x of this plugin. v1.1 is still [available for download](https://github.com/allmarkedup/jQuery-URL-Parser/zipball/v1.1) should you need it for some reason.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
195
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
196 Testing
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
197 -------
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
198
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
199 @omarqureshi has kindly contributed some unit tests, which can be run using [http://busterjs.org](buster.js). The tests only currently cover the non-jQuery version.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
200
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
201 To run you'll need to have Buster installed (requires node and npm);
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
202
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
203 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
204 $ npm install -g buster
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
205 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
206
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
207 Once it's installed, just do:
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
208
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
209 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
210 $ cd /path/to/jQuery-URL-Parser
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
211 $ buster static
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
212 ```
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
213
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
214 Buster will then start up a server and give you a url (like `http://localhost:8956`) which you can navigate to with your browser of choice to see the test results.
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
215
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
216
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
217
|
Dirk Wintergruen <dwinter@mpiwg-berlin.mpg.de>
parents:
diff
changeset
|
218
|
