Skip to content

Latest commit

 

History

History
216 lines (185 loc) · 9.58 KB

README.md

File metadata and controls

216 lines (185 loc) · 9.58 KB
Raw

q2.js: Javascript URL Query Tools

Parses URL query component, lists query params, gets params values, builds query component, and so on

Features:

  • 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' to 0 (number) — to be casted as false
    • '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)
    • undefined values (on by default)
    • null values (off by default)
  • When building query, can convert true to 1, and false to 0 (off by default)
  • Options configurable both globally and per-operation
  • Doesn't require any third-party libraries
  • And more! (Check out the examples)

Usage 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.

Basic usage:

/* 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&param2=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&param2=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'

Demonstrating some cool features:

/* 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 }

Using options:

(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);

Options configurable:

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 \s in 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 to 0 (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 to true/false boolean 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 with null value when building query
  • buildSkipUndefined (Boolean, defaults to true)
    Skip params with undefined value when building query
  • buildConvertBoolToNum (Boolean, defaults to false)
    Convert boolean values to 0 and 1 when 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)

Licence:

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.