v1.x: support html5 history (hash-free routing)

[x1B]

Users may want to avoid hash-based routing for good reasons, such as:

• using hashes for other purposes (anchors)
• SEO
• forward/backward compatibility with server-side rendering

To activate hash-free routing, LaxarJS needs to:

• configure the $locationProvider (add a LaxarJS config option for this)
• augment the flow definition at runtime, to include an additional, configurable, prefix (e.g. index/ or debug/), otherwise projects cannot set the required base tag (see below).

Projects will need to:

• rewrite requests (e.g. ^/index(/.*)?$ to /index.html, and ^debug(/.*)?$ to /debug.html, or serve all place URLs in some other way
• add a base tag to their index.html and debug.html
• configure LaxarJS to use HTML 5 routing

[x1B]

Implemented on master-1.x (v1.3.0).

Upgrade Information

It is now possible to use the HTML5 pushState API to navigate an application using URLs without '#'.
This way, the server can "see" what content was initially requested, and regular fragment-links can be used to link to individual elements on a page.
Also, this may benefit SEO since crawlers can reliably determine what URLs constitute separate pages.

To use the feature so that your application can be visited at /app/index,

• the web-server needs to rewrite all requests starting with the entry URL /app/index so that the application HTML page (e.g. /app/index.html) is served,
• also, the HTML must contain a base tag with href (e.g. /app/) so that assets can be referenced from sub-places and places with parameters such as /app/index/some-place/paramValue

The LaxarJS application must also be configured appropriately:

• the flow.router.base needs to match your rewrite-prefix without base tag URL. In the example, index/ would be used,
• the flow.router.html5Mode option must be set to true.

Configure the development server

For development, the corresponding steps must be taken (replacing index with debug everywhere). To serve requests using the grunt-connect server employed by the LaxarJS Grunt tasks,

• npm install --save-dev http-rewrite-middleware
• add some configuration to the Gruntfile.js:

var connectOptions = grunt.config( 'connect.options' ) || {};
connectOptions.middleware = function( connect, options, middlewares ) {
   // Support non-hash routing:
   // rewrite all index/... requests to index.html
   // rewrite all debug/... requests to debug.html
   var rewrite = require( 'http-rewrite-middleware' );
   options.base.forEach( function() {
      middlewares.unshift( rewrite.getMiddleware( [
         { from: '^/index(/.*)?$', to: '/index.html' },
         { from: '^/debug(/.*)?$', to: '/debug.html' }
      ] ) );
   } );
   return middlewares;
};
grunt.config( 'connect.options', connectOptions );

• finally, the development server must be restarted.