Skip to content

Latest commit

 

History

History
168 lines (121 loc) · 4.44 KB

README.md

File metadata and controls

168 lines (121 loc) · 4.44 KB
Raw

jsurl

Lightweight URL manipulation with JavaScript. Minified and gzipped 1.4KB

Goal

To have a convenient way working with URLs in JavaScript. From time to time there are usual tasks when it is required to add or remove some parameters to some basic URL or change some other URL parts.

There is no easy standard way to do it in JavaScript.

This small library intended to fix that problem

Supported Browsers

This library was tested under:

  • IE 7,8,9,10
  • Chrome 25, 26
  • Opera 12.15
  • Firefox 20
  • Android browser 2.3.4, 2.3.5, 4.1.3

Theoretically it should work fine with newer or older versions of these browsers, but it was not fully tested yet. If you'll find any compatibility issues, please, let me know by leaving a bug report here: https://github.com/Mikhus/jsurl/issues

You can run basic tests for your browser here: http://ru.smart-ip.net/jsurl/test.html or run test.html from this repository locally. If any test has not been passed, please, open a bug report as described above providing browser and OS version on each test which has been failed.

How To Use

First of all it is required to include Url class on the page. It can be simply done as

<script src="url.min.js"></script>

Then any time it's required to do some work over the URL string, it's just required to instantiate the Url object and work with that object instead of initial string. See API description below to get a clue.

Install with JAM

It is possible also to install jsurl via JAM repository (http://jamjs.org/). Could be simply done as:

$ jam install jsurl

Install with Bower

It is also possible now to install jsurl using Bower package repository. Could be done simply as:

$ bower install jsurl

API

Methods:

Url( strURL) Constructor. If strURL is not passed curent document URL will be used.

toString() Converts URL to string representation. As far as it's spesial method, any time string operations is performed over Url objects this method is automatically called

Properties:

protocol - protocol part of URL, everything between the beginning of the URL string and "://" delimiter (if specified)

user - auth user name (if specified)

pass - auth user password (if specified)

host - host name (if specified)

port - port number (if specified)

path - document path

query - QueryString object. It's a simple Javascript object with automatic string mapping. String representation contains everything after "?" and to the end of QueryString

hash - Anchor part of the URL. Everything after "#" and to the end of anchor

Usage Examples

var u  = new Url; // curent document URL will be used
// or we can instantiate as
var u2 = new Url( "http://example.com/some/path?a=b&c=d#someAnchor");
// it should support relative URLs also
var u3 = new Url( "/my/site/doc/path?foo=bar#baz");

// get the value of some query string parameter
alert( u2.query.a);
// or
alert( u3.query["foo"]);

// Manupulating query string parameters
u.query.a = [1, 2, 3]; // adds/replaces in query string params a=1&a=2&a=3
u.query.b = 'woohoo';  // adds/replaces in query string param b=woohoo

if (u.query.a instanceof Array) { // the way to add a parameter
  u.query.a.push(4); // now it's "a=1&a=2&a=3&a=4&b=woohoo"
}

else { // if not an array but scalar value here is a way how to convert to array
  u.query.a = [u.query.a];
  u.query.a.push(8)
}


// The way to remove the parameter:
delete u.query.a
// or:
delete u.query["a"]

// If you need to remove all query string params:
u.query.clear();
alert( u);

// Lookup URL parts:
alert(
    'protocol = ' + u.protocol + '\n' +
    'user = ' + u.user + '\n' +
    'pass = ' + u.pass + '\n' +
    'host = ' + u.host + '\n' +
    'port = ' + u.port + '\n' +
    'path = ' + u.path + '\n' +
    'query = ' + u.query + '\n' +
    'hash = ' + u.hash
);

// Manipulating URL parts
u.path = '/some/new/path'; // the way to change URL path
u.protocol = 'https' // the way to force https protocol on the source URL

// inject into string
var str = '<a href="' + u + '">My Cool Link</a>';

// or use in DOM context
var a = document.createElement('a');
a.href = u;
a.innerHTML = 'test';
document.body.appendChild( a);

// Stringify
u += '';
String(u);
u.toString();
// NOTE, that usually it will be done automatically, so only in special
//       cases direct stringify is required

License

This code is available under MIT license. Feel free to do what you want.