# sparouter
> A router developed with TypeScript
Latest version **3.3.0** (published 2017-02-02) · MIT license · 0 weekly downloads
## Install
```sh
npm install sparouter
pnpm add sparouter
yarn add sparouter
bun add sparouter
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 3.3.0 |
| Published | 2017-02-02 |
| First published | 2017-01-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | romagny13 |
| Maintainers | romagny13 |
| Keywords | spa, sparouter, router |
## Links
- npm: https://www.npmjs.com/package/sparouter
- Repository: https://github.com/romagny13/sparouter
- Homepage: https://github.com/romagny13/sparouter#readme
- Issues: https://github.com/romagny13/sparouter/issues
- npm.io page: https://npm.io/package/sparouter
## Alternatives
- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads
## Recent versions
- 3.3.0 (latest) — 2017-02-02
- 3.2.1 — 2017-02-02
- 3.2.0 — 2017-02-01
- 3.1.0 — 2017-01-31
- 3.0.2 — 2017-01-26
- 3.0.1 — 2017-01-26
- 3.0.0 — 2017-01-26
- 2.5.8 — 2017-01-23
- 2.5.7 — 2017-01-23
- 2.5.6 — 2017-01-22
- 2.5.5 — 2017-01-22
- 2.5.4 — 2017-01-21
- 2.5.3 — 2017-01-21
- 2.5.2 — 2017-01-18
- 2.5.1 — 2017-01-17
- … 11 more at https://npm.io/package/sparouter/versions
## README
# Spa Router v3
A router developed with TypeScript with :
- 2 modes : html5 history,hash
- page animation/transition with css or js
- active elements
- route guards
- child routes
- actions
[](https://travis-ci.org/romagny13/sparouter) [](https://badge.fury.io/js/sparouter)
## Installation
```
npm i sparouter -S
```
## Workflow
### With TypeScript / es6
We could use a starter kit.
### With es5
Its possible. Reference the lib in the main page.
```html
```
```js
new SpaRouter.Router().map([
{ path: "/", action: function () { return SpaRouter.render({ selector: "#main", template: "Home
" }); } },
{ path: "**", redirectTo: "/" }
]).run();
```
## Router & route configs
Router config| Description
-------- | --------
mode | hash (by default) and html5 history.
scroll | handle navigation to fragment (true by default)
Route config | Description
-------- | --------
path | the path pattern ("/posts" or "posts/:id" or "/posts/:id([a-z]+)" for example)
name | route name
action | an action
actions | an array of actions
data | extra data to pass
canActivate | route guards
canDeactivate | route guards
redirectTo | redirect to route url
children | nested routes
```js
import { Router } from "sparouter";
const routes = [
{ path: "/", action: () => document.querySelector("#main").innerHTML = "Home
" },
{ path: "/posts", action: () => render({ selector: "#main", templateUrl: "views/posts.html" }) },
{ path: "/posts/:id", canActivate: [MyGuard], action: ({route, router}) => console.log("Activate post details") },
{ path: "**", redirectTo: "/" },
];
new Router({
mode: "html5"
}).map(routes).run((route) => {
// on route change success
}, (err) => {
// route change error ("aborted" with a guard or "notfound" if no matched route found)
});
```
With html5 history mode (uris without '#'), the server have to redirect to index page.
The base tag with html5 history mode allow to set the base path. Examples:
```html
```
or
```html
```
## Param regex (number by default)
Example:
```js
const routes =[
{ path: "/posts/:id([a-z]+)", /* etc. */ }
];
```
## Named routes:
```js
const routes = [
{ name: "home", path: "/", /* etc. */ },
{ name: "posts", path: "/posts", /* etc. */ }
];
```
## Route with actions (array of functions)
```js
const routes = [
{
path: "/",
actions: [
() => document.querySelector("#main").innerHTML = "Home
",
({ route, router }) => console.log("Activate home", route, router),
/* other actions */
]
}
];
```
Its possible to pass an "action result" to the next action
```js
const routes = [
{
path: "/", actions: [
() => { return ["a", "b", "c"]; },
({ result, router }) => { console.log(result); }
]
}
];
```
... Or with a promise
```js
const routes = [
{
path: "/", actions: [
() => {
return new Promise((resolve) => {
resolve(["a", "b", "c"]);
});
},
({ result, router }) => { console.log(result); }
]
}
];
```
### children
```js
const routes = [
{ path: "/", templateUrl: "src/views/home.html" },
{
path: "posts",
children: [
{ path: "", action: () => { /* do something */ } },
{ path: ":id", actions: [ /* do things */ ] }
]
}
];
```
### Links
With hash mode
```html
Home
Posts
With parameter
Query and fragment
```
With to attribute: the best way to switch easilly between "hash" and "html5 history"
```html
Home
Posts
With parameter
Query and fragment
```
Active attributes
- active-class the css class to add if active
```html
Posts
```
```css
.active {
color:red
}
````
- active-path allow to set a regex pattern or to add on any element ("li" for example)
```html
```
- active-exact the css class is only added if path + query + fragment equal to link href or active-path
```html
Details
Details
```
### Navigate programmatically
Navigate by route name
```js
router.navigateTo("home");
// with parameter
router.navigateTo("post-detail",{ id: 10});
// with query and fragment
router.navigateTo("post-detail",{ id: 10},{ q: "news" },"section1");
```
Navigate by url
```js
router.navigateToUrl("/");
// with parameter
router.navigateToUrl("/posts/10");
// with query and fragment
router.navigateToUrl("/posts/10?q=news#section1");
```
Go back
```js
router.goBack();
```
Go forward
```js
router.goForward();
```
## render function
Allow to render content in an HTMLElement, and create an instance of a vm and pass args.
```js
import { render } from "sparouter";
class PostDetail {
onActivate(route, router,scope) {
// route with params, query, fragment and data
}
}
const routes = [
{ path: "/posts", action: () => render({ selector: "#main", templateUrl: "views/posts.html" }) },
{ path: "/posts/:id", action: ({ route, router }) => render({ selector: "#main", templateUrl: "views/post-detail.html", vm: PostDetail, args: [route, router] }) }
];
```
## Async await or promises
Allow to wait the end of the action before reach the next
Example with async await
```js
function doSomething() {
return new Promise((resolve) => {
setTimeout(function () {
console.log("Completed");
resolve();
}, 5000);
});
}
const routes = [{ path: "/", action: async() => {
await doSomething();
}}];
```
Example with promise
```js
const routes = [{
path: "/", action: () => {
return new Promise((resolve) => {
setTimeout(function () {
console.log("Completed");
resolve();
}, 5000);
});
}
}];
```
## Page transition
### with navigate function
Animation "leave" and "enter" (could be played simultaneously)
Example simple , a slide in / slide out
```js
const routes = [
{ path: "/", action: () => navigate({ selector: "#main", template: "Home
", enter: "slideInRight", leave: "slideOutLeft" }) }
];
```
Other example "Shuffle" on the container and
```js
const routes = [
{ path: "/", action: () => navigate({ selector: "#main", template: "Home
", enter: "navInPrev", leave: "navOutPrev", simultaneous: true }) }
];
```
## Before each and after each
Usefull for page animations with javaScript (SVG for example)
```js
var router = new SpaRouter.Router().map(routes).beforeEach((next) => {
next();
}).afterEach(() => {
}).run();
```
## Route guards
```js
class PostDetail {
checkDeactivate() {
return confirm("Leave this page?");
}
}
class MyGuard implements CanActivate, CanDeactivate {
canActivate(route, next) {
let result = confirm("Navigate?");
next(result);
}
canDeactivate(activeVms, route, next) {
let vm = activeVms["PostDetail"];
let result = vm && vm.checkDeactivate ? vm.checkDeactivate() : true;
next(result);
}
}
```
Example route with guard:
```js
const routes = [
{ path:"/posts/:id", canActivate: [MyGuard], canDeactivate: [MyGuard], /* etc. */ }
]);
```
Or register with injector
```js
injector.registerSecure("MyGuard",MyGuard);
const routes = [
{ path:"/posts/:id", canActivate: ["MyGuard"], /* etc. */ }
]);
```
### injector
Allow to inject services
Example
Create and register a service
```js
function MyService() {
this.getAll = function () {
// return some data
}
}
injector.register("MyService", MyService);
```
Inject the service
```js
function MyVM(myService) { }
injector.register("MyVM", MyVM, ["MyService"]);
```
Register a secure service (service is not returned with getInstance/ getNewInstance and cannot be removed)
```js
injector.registerSecure("MySecureService", MySecureService);
```
Chaining registrations
```js
injector
.register("MyService1", MyService1)
.register("MyService2", MyService2);
```
Get an instance (create or get a cached instance)
```js
let instance = injector.getInstance("MyService");
```
Get a new instance
```js
let instance = injector.getNewInstance("MyService");
```
Invoke a function with Injector
```js
injector.invoke(myFunc);
```
### View usefull functions
Allow to select and animate HTML elements.
```js
import { qs, qsa } from "sparouter";
qs(".box").changeContent("New content
");
qs(".box").animate("fadeIn",() => {
// completed
});
```
---
_Source: https://npm.io/package/sparouter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._