Simple parser for URL get & hash params.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
misc
tests
.gitignore
LICENSE
README.md
_config.yml
bower.json
package.json

README.md

UrlDict

Micro lib (less than 2K!) to handle URL params like dictionaries.

Support GET params and Hash (if you want to use Fragment identifier to store a dictionary of values). Reliably build back URLs.

Install

You can install via npm:

npm install urldict

Or bower:

bower install urldict

Or simply download the js files from /dist/ in this repo.

Usage

Lets start with a simple example that covers most of it:

// create a new urlDict object
var urlDict = new UrlDict("www.example.com");

// set url GET param
urlDict.GET.set("a", 123);
urlDict.GET.set("b", 456);

// build url. output will be "www.example.com?a=123&b=456"
alert(urlDict.toUrl());

// now set hash param
urlDict.HASH.set("foo", "bar");

// and now url output will be "www.example.com?a=123&b=456#foo=bar"
alert(urlDict.toUrl());

Or if you want to get params from existing url:

// build new url dict from url with GET and HASH params
var urlDict = new UrlDict("www.example.com?a=123&b=456#foo=bar");

// will output "123":
alert(urlDict.GET.get("a");

// will output "bar"
alert(urlDict.HASH.get("foo");

Note that UrlDict try to parse params using the JSON parser, which means that values like a=true will be returned as a boolean, and b=123 as a number. However, there's a special exception that if the value is not a valid JSON string it will just treat it as string.

Full API

To create a new UrlDict object:

// if 'url' is not provided, will use location.href instead.
var urlDict = new UrlDict(url);

To build the full URL from UrlDict, use toUrl():

var url = urlDict.toUrl();

To get or set just the base URL, without the GET or Hash params, use getBaseUrl() and setBaseUrl():

// set the base url, eg the part before the GET and hash params:
urlDict.setBaseUrl(newBaseUrl);

// get the base url, eg the part before the GET and hash params:
var baseUrl = urlDict.getBaseUrl();

To get a dictionary containing both GET and HASH params (objects are mutable and changing them will affect the urlDict), use asDict():

// get params as dictionary
var params = urlDict.asDict();

// show GET params
console.log(params.GET);

// show HASH params
console.log(params.HASH);

// to add a new GET param to url
params.GET["a"] = 123;

GET and HASH

The main API to set / get URL params is via the GET and HASH objects. They share the same API:

// set url GET param
urlDict.GET.set("a", 123);

// get url GET param
var a = urlDict.GET.get("a");

// remove url GET param
urlDict.GET.remove("a");

// clear all url GET params
urlDict.GET.clear();

The API above is the same for HASH object.

Or you can just get all params as a mutable dictionary (changing this dictionary will change the urlDict object):

// get all url GET params as a dictionary:
var getParams = urlDict.GET.asDict();

// change a url GET param
getParams["a"] = 123;

Tests & Browser support

urldict is fully testes on Node.js, IE7, Edge, Chrome, FireFox and Opera, and have 100% code coverage.

BrowsersSupport

Test in browsers

To test UrlDict in browsers just open the file /tests/test.html with the browser of your choice.

Test in Node.js

To test in nodejs first install qunit-cli:

npm install qunit-cli

Then you can run the following command from the project root:

qunit-cli tests/test.js

License

UrlDict is distributed under the MIT license and is free to use for any personal or commercial purpose.