svelte-guard-history-router
v6.1.2
Published
svelte router for SPA (history mode only)
Downloads
3,246
Maintainers
Readme
svelte-guard-history-router
svelte guarded history router
Features
- Named params
article/:id
- Guards to act when entering or leaving a route
- Automatic route ranking (more specific routes have higher priority)
- Routes and keys acting as stores
- Nested Routes with relative paths for route composition (Shared Leave Routes)
- Route values
- Object <=> parameter mapping
- Create links from objects
- Standart
<a href="/home">Home</a>
elements
Shared Leave Routes
<DetailRoute>
<Route path="/detail/:detail"/>
</DetailRoute>
<Router>
<Route path="/subjectA">
<DetailRoute/>
</Route>
<Route path="/subjectB">
<DetailRoute/>
</Route>
</Router>
usage
<script>
import { Router, Route, Outlet, redirectGuard } from "svelte-guard-history-router";
import About from "./About.svelte";
import Categories from "./Categories.svelte";
import Category from "./Category.svelte";
import Articles from "./Articles.svelte";
import Article from "./Article.svelte";
import { enshureSession } from "./main.mjs";
export const enshureSession = redirectGuard("/login", () => !session);
let session = undefined;
</script>
<Router base="/base">
<nav>
<!-- catch all but link to '/' -->
<Route href="/" path="*" component={Home}>Router Example</Route>
<ul class="left">
<li>
<Route path="/about" component={About}>About</Route>
</li>
<li>
<Route path="/article" guards={enshureSession} component={Articles}>
Articles
<Route path="/:artice" component={Article}/>
</Route>
</li>
<li>
<Route path="/category" guards={enshureSession} component={Categories}>
Categories
<Route path="/:category" component={Category}/>
</Route>
</li>
</ul>
</nav>
<main>
<Outlet/>
</main>
</Router>
Sample code
Check out the code in the example folder, or the live example.
To run the sample, clone the repository, install the dependencies, and start:
git clone https://github.com/arlac77/svelte-guard-history-router
cd svelte-guard-history-router
npm install
npm start
then navigate to localhost:5000
run tests
export BROWSER=safari|chrome|...
yarn test
or
npm test
API
Table of Contents
- active
- Key
- BaseRouter
- BaseTransition
- DetailRoute
- Guard
- redirectGuard
- sequenceGuard
- parallelGuard
- MasterRoute
- nullGuard
- RootRoute
- SkeletonRoute
- ValueStoreRoute
- Transition
- findClosestAttribute
- dispatchNavigationEvent
- nameValueStore
- WaitingGuard
active
- See: {Router.updateActive}
Keeps the node active state in sync.
Parameters
node
Elementrouter
Router
Key
Keys also act as svelte stores and can be subscribed.
export const article = derived(
[articles, router.keys.article],
([$articles, $id], set) => {
set($articles.find(a => a.id === $id));
return () => {};
}
);
Type: Object
Properties
BaseRouter
Extends BaseTransition
key subscriptions:
const aKey = router.keys.aKey;
$aKey // fired if value of aKey changes
Parameters
routes
Array<Route> all managed routesbase
string url (optional, defaultnew URL("../",import.meta.url).pathname
)
Properties
linkNodes
Set<Node> nodes having their active state updatedroutes
Array<Route>keys
Object collected keys of all routesparams
Object value mapping from keys (from current route)route
Route currentnested
Transition ongoing nested transitionbase
string url
component
Current component. Either from a nested transition or from the current route
Returns SvelteComponent
value
Value if the current route
Returns any
path
Returns string url path with fragment & query
path
Replace current route.
Parameters
path
string
replace
Replace current route without updating the state.
Parameters
path
string
Returns Object former state
push
Leave current route and enter route for given path. The work is done by a Transition.
Parameters
path
string where to go
Returns Transition running transition
finalizePush
Called from a Transition to manifest the new destination. If path is undefined the Transition has been aborderd.
Parameters
path
string
continue
Continue a transition to its original destination. Shortcut for this.transition.continue(). If there is no transition ongoing and a fallbackPath is present, it will be entered. Otherwise does nothing.
Parameters
fallbackPath
string
abort
Abort a transition. Shortcut for this.transition.abort() If there is no transition ongoing and a fallbackPath is present it will be entered. Otherwise does nothing.
Parameters
fallbackPath
string
subscribe
Router subscription. Changes in the current route will trigger a update
Parameters
subscription
Function
updateActive
Update the active state of a node. A node is considered active if it shared the path prefix with the current route.
Parameters
node
Element
addRoute
Add a new Route.
Parameters
route
Route
routeFor
Find Route for a given value.
Parameters
value
any
Returns Route able to support given value
pathFor
Find path for a given value.
Parameters
value
anysuffix
string to be appended
Returns string path + suffix
BaseTransition
searchParams
Deliver url search params form the current location.
Returns URLSearchParams as extracted from the path
searchParams
Replaces the search part of the path with the given searchParams.
Parameters
searchParams
(URLSearchParams | Object)
nest
Add another transition nesting level. Starts a transition from the given factory.
Parameters
path
stringfactory
Transition
continue
Continue a nested route to its original destination. Does nothing if the transition has not been nested.
abort
Abort the transition.
Parameters
error
Returns Promise<boolean> truen in case there was a nesten transition
DetailRoute
Extends ValueStoreRoute
Route to represent a slice of the masters list of values.
Properties
master
Route route holding the master records
master
Route holding the list ov values
Returns Route our master
first
Returns Promise<any> 1st. entry
last
Returns any last entry
previous
Returns any previous value
next
Returns Promise<any> next value
Guard
Enforces conditions of routes Like the presents of values in the context
enter
Called while entering a route (current outlet is not yet set)
Parameters
transition
Transition
leave
Called before leaving a route
Parameters
transition
Transition
redirectGuard
Redirects to a given path if condition is met.
Parameters
sequenceGuard
Execute guards in a sequence.
Parameters
children
Iterable<Guard>
parallelGuard
Execute guards in a parallel.
Parameters
children
Iterable<Guard>
MasterRoute
Extends SkeletonRoute
Route holding a ordered collection of values.
Parameters
path
options
Properties
value
Array<any>
nullGuard
Default empty guard does nothing.
RootRoute
Route at the root of the tree. This route has no parent. All other routes are below of this one.
hasParams
Are there parameters in the path.
Returns boolean true if route has parameters (:key)
path
Returns string empty as we are the root
propertyMapping
Returns Object empty object
guard
Returns Guard empty guard which does nothing
SkeletonRoute
Extends RootRoute
Route Subscriptions on Routes fire when the route value changes.
Parameters
path
options
(optional, default{}
)
Properties
path
string full path of the Route including all parentscomponent
SvelteComponent target to showlinkComponent
SvelteComponent content for ObjectLinkpropertyMapping
Object Map properties to object attributes Keys are the property names and values are the keys in the resulting object.priority
numberkeys
Array<string> as found in the pathregex
RegExvalue
any
enter
Enter the route from a former one. All parent routes up to the common ancestor are entered first.
Parameters
transition
TransitionuntilRoute
Route the common ancestor with the former route
leave
Leave the route to a new one. All parent routes up to the common ancestor are left.
Parameters
transition
TransitionuntilRoute
Route the common ancestor with the future route
isAcceptable
Check if value and properties are acceptable for the route.
Parameters
value
any to be placed into routeproperties
Object as presented in the route
Returns boolean true if value can be accepted
propertiesFor
Extract properties from a value. All property values must be strings.
Parameters
value
any source of the properties
Returns (Object | undefined) properties extracted from given value
commonAncestor
Find common ancestor with an other Route.
Parameters
other
Route
Returns (Route | undefined) common ancestor Route between receiver and other
valueFor
Deliver value for a given set of properties of the transition. Default implemantation asks the parent route.
Parameters
transition
Transition
Returns any for matching properties
value
Deliver route value. Default implemantation asks the parent route.
Returns any
propertyMapping
Deliver property mapping. Default implemantation asks the parent route.
Returns Object for matching properties
objectInstance
Default implemantation asks the parent route.
ValueStoreRoute
Extends SkeletonRoute
Route holding a single value
Transition
Extends BaseTransition
Transition between routes.
Parameters
router
Routerpath
string new destination
Properties
router
Routerpath
string new destination
start
Start the transition
- leave old route
- find matching target route @see matcher()
- enter new route
- set params
- set current route
end
- See: Router.finalizePush
Cleanup transition. Update Nodes active state
redirect
Halt current transition and go to another route. To proceed with the original route call continue() The original transition will keept in place and can be continued afterwards.
Parameters
path
string new route to enter temporary
abort
Bring back the router into the state before the transition has started. All nested transitions also will be termniated.
Parameters
e
(Exception | undefined)
findClosestAttribute
Walks up the dom tree parents unti a node with a given attribute is found or the root node is reached.
Parameters
dispatchNavigationEvent
Dispatches a NAVIGATION_EVENT with pathname and hash
Parameters
event
Event
nameValueStore
Create a named object which also acts as a store.
Parameters
name
stringvalue
any initial value
Properties
value
any
Returns Store
WaitingGuard
Extends Guard
Shows a component during transition.
Parameters
component
SvelteComponent to show up during th transitionrampUpTime
number initial delay for the componnt to show up (optional, default300
)
install
With npm do:
npm install svelte-guard-history-router
With yarn do:
yarn add svelte-guard-history-router
SPA integrating with a nginx backend
All unresolvable requests are redirected to /sericeBase/index.html
- /deploymantLocation is the location of the frontend in the servers file system
- /serviceBase is the url path as seen from the browser
location /serviceBase {
alias /deploymentLocation;
try_files $uri$args $uri$args/ /serviceBase/index.html;
}
SPA integrating with a netlify
publish a _redirects file into the app root folder
/* /index.html 200
license
BSD-2-Clause