Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/erikringsmuth/app-router

Router for Web Components
https://github.com/erikringsmuth/app-router

Last synced: about 2 months ago
JSON representation

Router for Web Components

Lists

README 

        
## Router for Web Components

> Works with [Polymer](https://www.polymer-project.org/), [X-Tag](http://www.x-tags.org/), and natively.

>

> [erikringsmuth.github.io/app-router](https://erikringsmuth.github.io/app-router/)



Manage page state. Lazy-load content. Data-bind path variables and query parameters. Use multiple layouts. Navigate with `hashchange` and HTML5 `pushState`. Animate transitions using `core-animated-pages`.



[Download](https://github.com/erikringsmuth/app-router/archive/master.zip) or run `bower install app-router --save`.



## Configuration



Define how URLs map to pages.



```html



  

    App Router

    

  

  

    

      

      



      

      



      

      



      

      



      

      

    

  



```



## Navigation



Click links or call `router.go()`.



```html



Home



Home



  document.querySelector('app-router').go('/home');



```



The router listens to `popstate` and `hashchange` events. Changing the URL will find the first `app-route` that matches, load the element or template, and replace the current view.



#### hashchange

Clicking `Home` will fire a `hashchange` event and tell the router to load the first route that matches `/home`. You don't need to handle the event in your Javascript. Hash paths `#/home` match routes without the hash ``.



#### pushState

You can use the [pushstate-anchor](https://github.com/erikringsmuth/pushstate-anchor) or [html5-history-anchor](https://github.com/erikringsmuth/html5-history-anchor) to extend `` tags with the HTML5 history API.



```html

Home

```



This will call `pushState()` and dispatch a `popstate` event.



#### go(path, options)

You can call the router from Javascript to navigate imperatively.



```js

document.querySelector('app-router').go('/home');

// or

document.querySelector('app-router').go('/home', {replace: true});

```



If you use `go(path, options)` you should also set the mode to `hash` or `pushstate` on the router.



```html



  



```



## Data Binding

Path variables and query parameters automatically attach to the element's attributes.



``` html



Order 123



```



If you're using Polymer, you can also bind path variables and query parameters to templates.

```html



  

    
Your order number is {{orderId}}


  



```



See it in action [here](https://erikringsmuth.github.io/app-router/#/databinding/1337?queryParam1=Routing%20with%20Web%20Components!).



## <app-route> options



#### import a custom element

Lazy-load a custom element.



```html



```



You only need to set the `element` attribute if the element's name is different than the file name.



#### pre-loaded custom element

Include the `element="element-name"` attribute on the route to use a pre-loaded custom element. This is how you use bundled (vulcanized) custom elements.



```html



  



  



```



#### import template

You can import a `` instead of a custom element. Just include the `template` attribute.



```html



```



#### inline template

Finally, you can in-line a `` like this.



```html



  

    
Inline template FTW!


  



```



#### regular expressions

Include the `regex` attribute to match on a regular expression. The format is the same as a JavaScript regular expression.



```html



```



#### redirect

A route can redirect to another path.



```html



  

  



```



When you use `redirect` you should also set `mode="hash|pushstate"` on the `app-router`.



## <app-router> options



#### mode

One set of routes will match regular paths `/` and hash paths `#/`. You can force a specific mode with `mode="auto|hash|pushstate"`.



```html



  



```



When left in `auto`, redirects and `go(path, options)` will use hash paths.



#### trailing slashes

By default `/home` and `/home/` are treated as separate routes. You can configure the router to ignore trailing slashes with `trailingSlash="ignore"`.

```html



  

  



```



## Demo Site & Example Setup

Check out the `app-router` in action at [erikringsmuth.github.io/app-router](https://erikringsmuth.github.io/app-router/).



You can download an example setup here https://github.com/erikringsmuth/app-router-examples to get running locally.



Examples showing `app-router` and `flatiron-director` versus no router https://github.com/erikringsmuth/polymer-router-demos.



## Breaking Changes

Check the [change log](https://github.com/erikringsmuth/app-router/blob/master/changelog.md) for breaking changes in major versions.



## Build, Test, and Debug [![Build Status](https://travis-ci.org/erikringsmuth/app-router.png?branch=master)](https://travis-ci.org/erikringsmuth/app-router)

Source files are under the `src` folder. The build process writes to the root directory. The easiest way to debug is to include the source script rather than the minified HTML import.

```html



```



To build:

- Run `bower install` and `npm install` to install dev dependencies

- Lint, test, build, and minify code with `gulp`

- Manually run functional tests in the browser by starting a static content server (node `http-server` or `python -m SimpleHTTPServer`) and open [http://localhost:8080/tests/functional-tests/](http://localhost:8080/tests/functional-tests/)