Parses URL query component, lists query params, gets params values, builds query component, and so on
- Ignores case of param names when getting values (on by default)
- Alternative params ('first found of these') value getting available
- URL-encode/decode for both param names and values (on by default)
- Param and value separators configurable
- When parsing/getting, converts some string values (on by default):
'0'to0(number) — to be casted asfalse'true'and'false'to correspondent boolean values'null'and'undefined'to correspondent 'real' Javascript values
- When building query, can skip params with:
- empty param names (on by default)
undefinedvalues (on by default)nullvalues (off by default)
- When building query, can convert
trueto1, andfalseto0(off by default) - Options configurable both globally and per-operation
- Doesn't require any third-party libraries
- And more! (Check out the examples)
First, include q2.js, e.g. add this to the <head> section of your webpage, like this:
<script src="/path/to/q2.js" type="text/javascript"></script>If using HTML5, type attribute can be omitted:
<script src="/path/to/q2.js"></script>To do things, use the methods of _q2 variable (available globally without any initialization). And here we go.
/* Assuming current browser URL is:
http://example.com/?someParam=10&otherParam=someValue#anchorParam=here */
_q2.getQueryParam('someParam'); // => '10'
_q2.getQueryParam('otherParam'); // => 'someValue'
_q2.getQueryParam('noSuchParam'); // => undefined (non-existent param)
_q2.getQueryParam('anchorParam'); // => undefined (non-query parts are ignored)
_q2.listQueryParams(); // => { 'someParam': '10', 'otherParam' => 'someValue' }
// Using custom URL
var myUrl = 'http://example.com/?param1=10¶m2=20';
_q2.getQueryParam('param1', myUrl); // => '10'
_q2.listQueryParams(myUrl); // => { 'param1': '10', 'param2' => '20' }
// Or, just a query part of URL (with or without preceding '?' mark)
var myQuery = 'param1=10¶m2=20';
_q2.getQueryParam('param1', myQuery); // => '10'
_q2.listQueryParams(myQuery); // => { 'param1': '10', 'param2' => '20' }
// Any non-string value will be treated as 'use current browser URL'
_q2.getQueryParam('param1', null); // window.location.href will be used
_q2.listQueryParams(false); // window.location.href will be used
// Building query
var params1 = { first: 10, second: 6.5, last: 'someValue' };
_q2.buildQuery(params1); // => '?first=10&second=6.5&last=someValue'
// If params order is important for you, better use pairs array (objects are sometimes reordered in Javascript)
var params2 = [ ['first', 10], ['second', 6.5], ['last', 'someValue'] ];
_q2.buildQuery(params2); // => '?first=10&second=6.5&last=someValue'
// Undefined values and empty param names are ignored (configurable)
var params3 = { '': 10, second: 6.5, last: undefined };
_q2.buildQuery(params3); // => '?second=6.5'/* Assuming current browser URL is:
http://example.com/?someParam=10&otherParam=someValue */
// Param name case is ignored by default (configurable)
_q2.getQueryParam('otherparam'); // => 'someValue'
_q2.getQueryParam('OthErpARaM'); // => 'someValue'
// Alternative params getting ('first found of these')
_q2.getQueryParam(['someparam', 'otherparam']); // => '10'
_q2.getQueryParam(['otherparam', 'someparam']); // => 'someValue'
_q2.getQueryParam(['noSuchParam', 'someparam']); // => '10'
_q2.getQueryParam(['noSuchParam', 'badparam']); // => undefined
// Smart values conversion (configurable)
var smartVals = 'zero=0&truly=true&falsy=false&nully=null&undef=undefined';
_q2.getQueryParam('zero', smartVals); // => 0 (number, casted as false)
_q2.getQueryParam('truly', smartVals); // => true (boolean)
_q2.getQueryParam('falsy', smartVals); // => false (boolean)
_q2.getQueryParam('nully', smartVals); // => null (real JS value)
_q2.getQueryParam('undef', smartVals); // => undefined (real JS value)
// That also works when listing all params
_q2.listQueryParams(smartVals);
// => { 'zero': 0, 'truly': true, 'falsy': false, 'nully': null, 'undef': undefined }(For full list of options, see Options configurable below)
// Disable case-ignore for param names
var url1 = 'http://example.com/?firstParam=10&lastParam=20';
var opt1 = { paramNameCaseIgnore: false };
_q2.getQueryParam('firstparam', url1); // => 10
_q2.getQueryParam('firstparam', url1, opt1); // => undefined
// Disable conversion of zero and booleans
var url2 = 'http://example.com/?zero=0&falsy=false';
var opt2 = { parseConvertZero: false, parseConvertBool: false };
_q2.getQueryParam('zero', url2); // => 0 (number, casted as false)
_q2.getQueryParam('zero', url2, opt2); // => '0' (string, casted as true)
_q2.getQueryParam('falsy', url2); // => false (boolean value)
_q2.getQueryParam('falsy', url2, opt2); // => 'false' (string, casted as true)
// List params as pairs array (safer for keeping params order, duplicate param names, JS special property names, etc)
var url3 = 'http://example.com/?first=1&second=2&last=3';
var opt3 = { listParamsAsPairs: true };
_q2.listQueryParams(url3); // => { 'first': '1', 'second': '2', 'last': '3' }
_q2.listQueryParams(url3, opt3); // => [ ['first', '1'], ['second', '2'], ['last', '3'] ]
// Using custom params separators
var url4 = 'http://example.com/?first=1;second=2;last=3';
var opt4 = { paramSeparator: ';' };
_q2.listQueryParams(url4, opt4); // => { 'first': '1', 'second': '2', 'last': '3' }
// And custom value separators, too
var url5 = 'first:1,second:2,last:3';
var opt5 = { paramSeparator: ',', valueSeparator: ':' };
_q2.listQueryParams(url5, opt5); // => { 'first': '1', 'second': '2', 'last': '3' }
// Adjust params skipping when building query
var params = {
normal: 'someValue',
'': 'otherValue',
'nully': null,
'undef': undefined
};
var opt6 = {
skipEmptyParamNames: false,
buildSkipNull: true,
buildSkipUndefined: false
};
_q2.buildQuery(params); // '?normal=someValue&nully=null'
_q2.buildQuery(params, opt6); // '?normal=someValue&=otherValue&undef=undefined'
// Setting global options
// (no need to pass them each time; also speeds up some operations)
var myOptions = {
paramSeparator: ';'.
paramNameCaseIgnore: false,
skipEmptyParamNames: false,
buildSkipNull: true
};
// Use these values for all future operations
_q2.setOptions(myOptions);Current options values can be listed with _q2.listOptions() or _q2.getOptions() (these are synonyms).
Here is the full list of options and their default values:
- paramSeparator (String, defaults to
'&')
A string separating one query param from another - valueSeparator (String, defaults to
'=')
A string separating param name from its value - urlEncodeAndDecode (Boolean, defaults to
true)
URL-encode and decode param names and values when parsing/building - trimWhitespaces (Boolean, defaults to
false)
Remove leading/trailing\sin param names and values when parsing/building - skipEmptyParamNames (Boolean, defaults to
true)
Skip''name when building query, and&&,&=&and&=someValue&when parsing - paramNameCaseIgnore (Boolean, defaults to
true)
getQueryParam()ignores case for both input and URL query params - parseConvertZero (Boolean, defaults to
true)
Convert'0'string value to0(number) when parsing query - parseConvertBool (Boolean, defaults to
true)
Convert'true'and'false'string values to correspondent boolean values when parsing query - parseConvertYesNo (Boolean, defaults to
false)
Convert'yes'and'no'string values totrue/falseboolean values when parsing query - parseConvertNull (Boolean, defaults to
true)
Convert'null'string value to correspondent Javascript value when parsing query - parseConvertUndefined (Boolean, defaults to
true)
Convert'undefined'string value to correspondent Javascript value when parsing query - specialValueCaseIgnore (Boolean, defaults to
false)
Ignore value case when converting'true','false','yes','no','null'and'undefined'values - listParamsAsPairs (Boolean, defaults to
false)
listQueryParams()returns pairs array instead of object - specialValueCaseIgnore (Boolean, defaults to
false)
Ignore value case when converting'true','false','yes','no','null'and'undefined'values - buildSkipNull (Boolean, defaults to
false)
Skip params withnullvalue when building query - buildSkipUndefined (Boolean, defaults to
true)
Skip params withundefinedvalue when building query - buildConvertBoolToNum (Boolean, defaults to
false)
Convert boolean values to0and1when building query - separateEmptyValues (Boolean, defaults to
true)
Add value separator after param name even if its value is empty (e.g.a=&b=) - queryQuestionMark (Boolean|String, defaults to
'auto')
Add '?' mark before query built (true: always,false: never;'auto': non-empty result only)
You can do whatever you want with q2.js, it is MIT-licenced.
Also, no warranty provided, so use this software at your own risk.
For full licence text, see the LICENCE file included.