UsefulJS.Query

The Query module provides methods to parse and build query strings and may optionally parse location.search, exposing the parsed value through the UsefulJS.Query.parameters object.

Anatomy of a query string

The following might be the query string supplied to an online pizza ordering application:

?pickup&size=14&topping=pepperoni&topping=extra+cheese&coupon=0144732

The query part of the URL is denoted by '?'. The invidual items in the query string are separated by '&' and the keys and values are separated by '='. Certain characters need to be escaped (note "extra+cheese", where '+' is the escaped value for ' '). The general form of an escaped character is "%XY", where "XY" is the hexadecimal representation of the character code value. A key with no associated value is a simple boolean flag.

UsefulJS.Query.parse method will turn the above string into the following value:

{
    pickup : true,
    size : 14,
    topping : ["pepperoni", "extra cheese"],
    coupon : "0144732"
}

Static methods

parse

Parses a query string into a JavaScript Object

Syntax

UsefulJS.Query.parse(s)

Parameters

• s String
  The query string to parse.

Returns: Object The parsed query parameters.

Description

The input string is parsed according to the following rules:

• If there is a key but no associated value, the output property is boolean true
• If the value looks like a number (String(parseInt(v, 10)) === v)), the output property is a Number
• For other values, the output property is a String
• If a key appears more than once in the input string, the output property is promoted to an Array.

append

Used to build up a query string one key-value pair at a time

Syntax

UsefulJS.Query.append(s, n, v)

Parameters

• s String
  The existing query string to append to.
• n String
  The name of the key to add.
• v Boolean|String|Number|Array
  The value associated with the key.

Returns: String The modified query string.

Description

The value to add may be one of the following types:

• Boolean true: appends just the key
• String, Number: appends "key=value"
• Array: appends "key=value[0]&key=value[1]..."

The appended key-value pair is correctly URI-encoded.

Usage

// Outputs size=14&topping=pepperoni&topping=extra%20cheese
var q = UsefulJS.Query,
    queryStr = q.append(q.append("", "size", 14), "topping", ["pepperoni", "extra cheese"]);

build

Convenience method to assemble a query string in one go.

Syntax

UsefulJS.Query.build(params)

Parameters

• params Object
  A collection of keys and values to to turn into a query string

Returns: String The assembled query string.

Description

Each value in the params Object must be Boolean true, a String, a Number or an Array as with the v parameter to the append method. The return value will be correctly URI-encoded.

Usage

// Outputs pickup&size=14&topping=pepperoni&topping=extra%20cheese
var q = UsefulJS.Query,
    params = { pickup : true, size : 14, topping : ["pepperoni", "extra cheese"] },
    queryStr = q.build(params);

UsefulJS.Query.parameters

This property is an interface to the query parameters for the current page. It provides three methods to manage the query string.

parse

Parses location.search.

Syntax

UsefulJS.Query.parameters.parse()

get

Gets the value of a parameter.

Syntax

UsefulJS.Query.parameters.get(prop, def)

Parameters

• prop String
  The name of the desired parameter
• def Any
  The value to return if prop is not found in the query parameters

Returns: Any The value associated with the parameter or def if the property is not found.

all

Clones the parsed query parameters for the page and returns them. Modifications to the return value will not affect the original parameters object.

Syntax

UsefulJS.Query.parameters.all()

Usage

// Are we running in debug mode?
var qparams = UsefulJS.Query.parameters,
    logLevel = 0;
qparams.parse();
if (qparams.get("debug", false)) {
    logLevel = qparams.get("verbose", 1);
}

Fixes

The fixes for the Query module are defined in the _query namespace of the fix options.

parse

The parse fix parses any query string supplied to the current page. It is enabled by default. The property set in the return value is a boolean value called "parsed".