### URL Utils Sample

This page demonstrates the use of the following URL utilities:

- Spry.Utils.getLocationParamsAsObject - Gets parameters from the current URL.
- Spry.Utils.getLocationHashParamsAsObject - Gets hash values from the current URL
- Spry.Utils.getURLParamsAsObject - Gets parameters from a url variable.
- Spry.Utils.getURLHashParamsAsObject - Gets hash values from a url variable.
- Spry.Utils.urlComponentToObject - Gets values from a partial string.
- Example - These objects in action.

These methods make it easier to extract values from the search params:

    http://www.foo.com/documents.cfm?genre=fiction&offset=0&limit=100#curdoc=35&curpanel=3

or hash params:

http://www.foo.com/documents.cfm?genre=fiction&offset=0&limit=100#curdoc=35&curpanel=3

of a URL. All of the functions mentioned above return an object with properties that have the same names as the names used in the name/value pairs in the URL component. It should be noted that the property names and values stored in the object are URL decoded. It should also be noted that the default type for the value of each property is a string. That said, these functions will attempt to convert any value that is "0" or a string of digits that begins with a non-zero number, into an integer value. In all other cases, it is the responsibility of the developer to convert any values to the appropriate type before using them.

To use one of the functions mentioned above, you must first include SpryURLUtils.js in your page:

    <head>
    <script type="text/javascript" src="lib/spry/includes/SpryURLUtils.js"></script>

    </head>

#### Spry.Utils.getLocationParamsAsObject

This function gets the URL parameters from the current URL.

Spry.Utils.getLocationParamsAsObject is a convenience function, and is roughly the equivalent of calling:

    var params = Spry.Utils.getURLParamsAsObject(window.location);

window.location is the URL that displays in the browser's URL bar. You call it like this:

    var params = Spry.Utils.getLocationParamsAsObject();

#### Spry.Utils.getLocationHashParamsAsObject

This function gets the URL hash values from the current URL.

Spry.Utils.getLocationHashParamsAsObject is a convenience function, and is roughly the equivalent of calling:

    var params = Spry.Utils.getURLHashParamsAsObject(window.location.hash);

window.location is the URL that displays in the browser's URL bar. You call it like this:

    var params = Spry.Utils.getLocationHashParamsAsObject();

Spry.Utils.getLocationHashParamsAsObject also takes the optional paramSeparator and nameValueSeparator:

    var params = Spry.Utils.getLocationHashParamsAsObject(",", ":");

#### Spry.Utils.getURLParamsAsObject

Use Spry.Utils.getURLParamsAsObject to retrieve the search params from a URL:

    var url = "http://www.foo.com/documents.cfm?genre=fiction&offset=0&limit=100#curdoc=35&curpanel=3";

    var params = Spry.Utils.getURLParamsAsObject(url);

    alert(params.genre);  // Alert shows "fiction"
    alert(params.limit);  // Alert shows 100
    alert(params.curdoc); // Alert shows undefined since curdoc is not defined in the search component of the URL.

#### Spry.Utils.getURLHashParamsAsObject

Use Spry.Utils.getURLHashParamsAsObject to retrieve the hash params from a URL:

    var url = "http://www.foo.com/documents.cfm?genre=fiction&offset=0&limit=100#curdoc=35&curpanel=3";

    var params = Spry.Utils.getURLHashParamsAsObject(url);

    alert(params.genre);    // Alert shows undefined since genre is not defined in the hash component of the URL.
    alert(params.curdoc);   // Alert shows 35
    alert(params.curpanel); // Alert shows 3

Since the format of the hash component is up to the developer, Spry.Utils.getURLHashParamsAsObject takes 2 optional arguments after the URL. The 2nd argument (paramSeparator) can be a string or regular expression that defines what the separator is between each name/value pair. The 3rd argument (nameValueSeparator) can be a string or regular expression that defines what separator is between each name and value. By default, the paramSeparator is '&' and the nameValueSeparator is '='.

Here's an example of a URL that uses ':' and ',' within the hash component:

    var url = "http://www.foo.com/documents.cfm?genre=fiction&offset=0&limit=100#curdoc:35,curpanel:3";

    var params = Spry.Utils.getURLHashParamsAsObject(url, ",", ":");

    alert(params.genre);    // Alert shows undefined since genre is not defined in the hash component of the URL.
    alert(params.curdoc);   // Alert shows 35
    alert(params.curpanel); // Alert shows 3

#### Spry.Utils.urlComponentToObject

If you have a string containing name/value pairs, which is not a complete URL, you can convert it into an object with Spry.Utils.urlComponentToObject, which is the same function used internally by Spry.Utils.getURLParamsAsObject and Spry.Utils.getURLHashParamsAsObject.

    var str = "genre=fiction&offset=0&limit=100";

    var params = Spry.Utils.urlComponentToObject(str);

    alert(params.genre);  // Alert shows "fiction"
    alert(params.limit);  // Alert shows 100

Like Spry.Utils.getURLHashParamsAsObject, Spry.Utils.urlComponentToObject has optional paramSeparator and nameValueSeparator args.

    var str = "genre:fiction,offset:0,limit:100";

    var params = Spry.Utils.urlComponentToObject(str, ",", ":");

    alert(params.genre);  // Alert shows "fiction"
    alert(params.limit);  // Alert shows 100

#### Example

Setting a default panel on a Tabbed Panels widget can be done by sending the panel number as a URL parameter. We will grab this param and use the value in the constructor.

- Tab 1
- Tab 2
- Tab 3
- Tab 4

Content 1
Content 2
Content 3
Content 4

Tab 1 | Tab 2 | Tab 3 | Tab 4