Skip to content
/ fryr Public

Command window.location.hash like a cook in the kitchen

License

Notifications You must be signed in to change notification settings

wearefine/fryr

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

74 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Fryr

Fryr is the fry cook you never knew you needed to turn that ugly, frozen hash into pretty, delectably digestable params. Not only does it make params accessible for use on the client-side, it also adds, removes, and updates them.

// visit mysite.com/#?tankhood=gill,deb,bloat

// define new instance of Fryr with callback
var fry = new Fryr(callback);

// callback is called on hashchange
function callback() {
  // do something with this.params, like refreshing content
};
// or access params outside of the callback
fry.params;
// => { 'tankhood' : 'gill,deb,bloat' }

// then update params at will
fry.update('home', 'reef');
// => ...com/#?tankhood=gill,deb,bloat&home=reef
fry.append('tankhood', 'nemo');
// => ...com/#?tankhood=gill,deb,bloat,nemo&home=reef

Initialization

var fry = new Fryr(hashChangeCallback, defaults, call_on_init);
Arg Type Default Description
hashChangeCallback function Called on every hashchange (first argument is the updated params)
defaults object {} Key/value pairs for values that should be added on init. Pass {} to skip to next argument
call_on_init boolean true Execute callback on initialization. Always true if defaults is supplied

The hashChangeCallback executes everytime the hash is changed. Commonly, this function updates the view and regenerates filtered items, uncommonly, it is used to print frustrated messages to the console, and very rarely it is used to sort the recyclables. It accepts one argument - the new params (as an object) that have been parsed.

Example

function myFilteringCallbackFunction(params) {
  console.table(params);
};
var fry = new Fryr(myFilteringCallbackFunction);

Functions

.update

Arg Type Default Description
key string param key to query against
value mixed value for param key
key_is_required boolean false if the key is not required, it will be removed from the hash

The meat and potatoes of Fryr, this modifies the hash to your explicit purposes.

Examples

Add a key

fry.update('character', 'marlin');
// => ...com/#?character=marlin

Add a different key

// /#?character=marlin
fry.update('home', 'reef');
// => /#?character=marlin&home=reef

Replace key's value

// /#?character=marlin
fry.update('character', 'nemo', false, true);
// => /#?character=nemo

Remove key

// /#?character=marlin
fry.update('character', '');
// => /#

Remove value but keep key

// /#?character=marlin
fry.update('character', '', true);
// => /#?character=

.append

Arg Type Default Description
key string param key to query against
value mixed value for param key

Near identical to .update, this function is designed to add values as a list and not be a uniform replace-value.

Example

// /#?character=marlin
fry.append('character', 'nemo');
// => /#?character=marlin,nemo

.param

Arg Type Description
key string the param to query

Query a key in the hash directly, and don't even bother re-parsing it. In just about every instance, accessing .params.<key> is the better decision here. Returns string.

Example

// #?can_speak_whale=dory
fry.param('can_speak_whale')
// => 'dory'

.paramPresent

Arg Type Description
key string the param to query

Determine if a param exists or has a blank value.

Examples

// #?boat=touched
fry.paramPresent('boat');
// => true

// #?boat=
fry.paramPresent('boat');
// => false

// #?bomb=touched
fry.paramPresent('boat');
// => false

.parse

Update Fryr's Fryr.params object with a fresh batch of updated key/values. This occurs on every hashChange event anyway, but sometimes you just want to be that guy. Returns object.

.convert

Turn a JSON object into a string. Returns a string (without leading #) or false if the param is not an object or a string.

Arg Type Description
obj object OR string object to convert

Example

var obj = { 'support_group' : ['bruce', 'anchor', 'chum'], 'location' : 'submarine' };

fry.convert(obj);
// => '?support_group=bruce,anchor,chum&location=submarine'

.merge

Wipe out or selectively replace keys and values. Returns a string but also updates the hash.

Arg Type Default Description
obj object OR string query to replace
replace_all boolean false blast existing params away or replace only changed keys

Examples

// /#?destination=sydney&directions=over_the_trench
var obj = { 'directions' : 'through_the_trench' };
fry.merge(obj);
// => /#?destination=sydney&directions=through_the_trench

With replace_all

// /#?destination=sydney
var obj = { 'directions' : 'through_the_trench' };
fry.merge(obj, true);
// => /#?directions=through_the_trench

.destroy

Destroy current initialization, unbind hashchange listener, and reset the hash to an empty state.

Arg Type Default Description
retain_hash boolean false preserve hash state

Examples

// /#?destination=sydney&directions=over_the_trench
fry.destroy();
// => /


// /#?destination=sydney&directions=over_the_trench
fry.destroy(true);
// => /#?destination=sydney&directions=over_the_trench

Access

.params

Grab the key/value hash of the parsed version of window.location.hash. Returns object.

Testing

Install all dependencies:

npm install --save-dev