js-request-parameters

Manipulate URL parameters with vanilla JS (no jQuery needed).

Getting started

Just add js-url-paramters.js to your page and you are ready to go, no other dependecies required.

Examples

Initialize an object to interact with URL parameters...

let params = UrlParams.init();
params.get('count');

...or just use the convenience function urlParam(key) built in for this...

urlParam('count');

Get value of a parameter (returns undefined if not set).

let count = params.get('count').value();
//or
count = urlParam('count').value();

Get value of a parameter, if it is set.

let count;
if(params.get('count').isSet()) {
    count = urlParam('count').value();
} else {
    count = //whatever
}

Set value of a parameter.

params.get('answerToLifeUniverseAndEverything').value(42);

//or directly affect the way the api sets the parameter (see API documentation)
urlParam('answerToLifeUniverseAndEverything').value(42, {
    push: true,
    state: {
        page: 1,
        user: 'algoristic'
    }
})

Remove a parameter from an URL.

params.get('count').remove();

Listen for value changes on an URL parameter.

params.get('count').onChange((value, oldValue, key) => {
    console.log(`param '${key}' changed -> [old=${oldVal}, new=${val}]`);
});

Define custom functions, depending on a parameter's current state.

for(key of [ 'count', 'msg', 'foo' ]) {
    params.get(key).check({
        callbackIfExists: (value) => {
            console.log(`param: '${key}' exists (value='${value}')`);
        },
        callbackIfNotExists: () => {
            console.log(`param: '${key}' does not exist`);
        }
    });
}

UrlParam API

UrlParams.init() .get( key ) or urlParam( key ) return an UrlParam object, no matter if the parameter is set or not. UrlParam offers the following methods:

value( )

Returns the value of the parameter or undefined if it is not set.

value( value )

Sets the value of the parameter, if value !== undefined (use UrlParam::remove for that purpose).

value( value, options )

The UrlParam API makes use of the History API. If you are already familiar to manipulate the states via history.pushState and history.replaceState you can directly affect the way the UrlParam API sets the parameter values, for a greater control over the browser behaviour. The options object can consist of the following values:

• push: ( boolean ) If true, use history.pushState to manipulate the URL parameters.
• state: ( object ) Represents the current state (default is history.replaceState).
• title: ( string ) Represents the title for the current state.
• callback: ( function ) Function to be called, when the parameter has been manipulated successfully.

isSet( )

Returns true, if the parameter is set, otherwise false.

remove( )

Removes the parameter and its value from the URL.

remove( options )

Removes the parameter and its value from the URL. For the options to perform this operation, see value( value, options ).

onchange( callback )

Registers a function( newValue, oldValue, parameterKey ) to be called, when the value assigned to the parameter gets changed. Multiple callbacks can e registered for one parameter. The callbacks keep memorized, even when the parameter gets deleted from the URL.

check( )

Called with no parameters check() will return the same as isSet().

check( options )

Checks if a parameter is present in the current URL and what value is assigned to it. The options object can consist of the following values:

• callbackIfExists: ( function( value ) ) Function to be called, if the parameter exists.
• callbackIfNotExists: ( function ) Function to be called, if the parameter does not exist.