Dynamically Updating Links

HashRouter automatically parses link tags in your document looking for hash tag links to convert to the route structure. This allows for link tags to be specified in any order, or only for part of the page.

There are four ways to specify links:

Additionally there are a couple of options for variables inside of links:

Single Hash - Set a Variable

The single hash tag is used to update a value in the URL without interfering with other URL values. For example if the current url is:

http://example.com/#!/page:list/sort:student/direction:down

The user might click on 'student' column header to sort it a different direction. This can easily be specified with this anchor tag: <a href="#direction:up">student</a>

The automatic parser will convert this link to the following url:

Without Routes: <a href="#!/page:list/sort:student/direction:up">student</a> With Routes: <a href="#!/list/student/up">student</a>

You can list any number of variables to update in the link tag. You can optionally use routes to specify the links as well. (But we recommend specifying the variable names for easy maintenance.)

When resetting the URL, HashRouter may use default values automatically to fill in gaps in the routing structure.

Double Hash - Override The URL

The double hash tag is used to update the entire url, removing any values not specified. For example if the current url is:

http://example.com/#!/page:list/sort:student/direction:down

And the user wishes to navigate to a particular student, the sort column and direction won't be useful on the student page. <a href="##page:view/studentID:44">view student 44</a>

The automatic parser will convert this link to the following url:

Without Routes: <a href="#!/page:view/studentID:44">view student 44</a> With Routes: <a href="#!/view/44">view student 44</a>

With Bang (Exclamation Point) - Force a Refresh

Normally when a user clicks on a hash tag link that is identical to the current url the browser will not update the url, and therefore no bound events are called. Sometimes it is desirable to cause events to trigger even if the url hasn't changed. For example this site uses these type of links for scrolling to a particular location on the page. (This is accomplished with the jQuery.scrollTo plugin. )

You can choose to use a single or a double hash depending on the need for resetting other page variables.

Links specified with exclamation points are bound with a click event that causes the url to re-trigger. Don't worry, they still work properly for use with tabbed browsing.

The exclamation point must come after the one or two hash symbols.

<a href="##!page:view/scrollTo:name">view student name</a> <a href="#!scrollTo:name">view student name</a>

With Callback - Dynamically Set a Variable

To specify that a value should be dynamically generated every time that the url is parsed, specify a callback function. This function must be in the global scope, or qualified by other members that are in the global scope.

The callback function is supplied two arguments: the name of the variable, and the values of the other variables that have been decoded in the link's url.

<script> window.utilities = { dayOfWeek : function(variable, values) { var dayNames = ["Sunday","Monday","Tuesday","Wednesday" ,"Thursday","Friday","Saturday"]; return dayNames[(new Date).getDay()]; } } </script> <a href="#viewDay:[utilities.dayOfWeek]">view Today</a>

Keep a Variable

To keep some variables the same when overriding, use empty brackets [] and the double pound sign. For example you may have a classroom selected and need to add a student to it:

<a href="##action:addStudent/classroomId:[]">Add a student</a>

Remove a Variable

To remove only one variable and keep the rest exactly the same, use: [null] and a single pound. For example, if you have a dialog window and want to close the window but not change the rest of the page:

<a href="#dialog:[null]">Close Dialog</a>