Skip to content

Commit 43d65a2

Browse files
MattCCCMattCCC
committed
Initialize Router
1 parent e9ebcef commit 43d65a2

12 files changed

+1753
-12
lines changed

‎README.md‎

Lines changed: 148 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,36 @@
11
# NativeScript Vue Router
2+
[npm-url]: https://npmjs.org/package/nativescript-vue-router-extended
3+
[npm-image]: http://img.shields.io/npm/v/nativescript-vue-router-extended.svg
4+
5+
[![NPM version][npm-image]][npm-url] [![Blazing Fast](https://badgen.now.sh/badge/speed/blazing%20%F0%9F%94%A5/green)](https://github.com/MattCCC/nativescript-vue-router-extended) [![Code Coverage](https://badgen.now.sh/badge/coverage/0.00/blue)](https://github.com/MattCCC/nativescript-vue-router-extended) [![npm downloads](https://img.shields.io/npm/dm/nativescript-vue-router-extended.svg?style=flat-square)](http://npm-stat.com/charts.html?package=nativescript-vue-router-extended) [![install size](https://packagephobia.now.sh/badge?p=nativescript-vue-router-extended)](https://packagephobia.now.sh/result?p=nativescript-vue-router-extended)
26

37
[nativescript-vue-router-extended](https://github.com/mattCCC/nativescript-vue-router-extended)
48

59
NativeScript Vue Router brings easier routing handling to mobile apps, with an API compatibility with web version of Vue Router.
610

711
Please file an issue or make a PR if you spot any problems or you have any further requests regarding the functionality.
812

13+
## Table of Contents
14+
15+
- [Features](#features)
16+
- [Todo](#todo)
17+
- [Prerequisites / Requirements](#prerequisites-requirements)
18+
- [Installation](#installation)
19+
- [Usage & Examples](#usage-examples)
20+
- [New hooks for pages](#new-hooks-for-pages)
21+
- [API & Limitations](#api-limitations)
22+
23+
## Features
24+
- Same hooks and guards for mobile and web
25+
- Additional action dispatcher to dispatch actions to store automatically when changing routes
26+
- Vue-Router 4 API compatibility
27+
- NativeScript-Vue compatible
28+
- TypeScript Support out of the box
29+
30+
## Todo
31+
- Test coverage
32+
- More compatibility (PRs and issues are welcomed so don't hesistate to report please)
33+
934
## Prerequisites / Requirements
1035

1136
Nativescript 7.1+ is required for the plugin to run properly. It might be working on previous NS6 although the plugin is no longer officially supported for NativeScript 6.
@@ -24,11 +49,131 @@ or
2449
yarn add nativescript-vue-router-extended
2550
```
2651

27-
## Usage
28-
2952
[nativescript-vue-router-extended](https://www.npmjs.com/package/nativescript-vue-router-extended)
3053

31-
Currently under development.
54+
## Usage & Examples
55+
56+
To use this plugin you need to import it and initialize the router using `createRouter()` function. Global and per component Vue-Router hooks and guards are supported.
57+
58+
```javascript
59+
import Vue from "nativescript-vue";
60+
import { createRouter } from "nativescript-vue-router-extended";
61+
62+
// Initialize Example Routes
63+
import moviesPage from "./pages/movies.vue";
64+
65+
const routes = [
66+
{
67+
path: "/movies",
68+
component: moviesPage,
69+
meta: {
70+
isVertical: true,
71+
store: {
72+
showNavigationButtons: false,
73+
},
74+
},
75+
},
76+
];
77+
78+
// Initialize Router
79+
// Vue-Router settings are in 1st argument. 2nd one is used for extra NativeScript related settings
80+
const router = createRouter(
81+
{ routes },
82+
{
83+
// Optional settings below
84+
85+
// Set first page to redirect to when there's no page to redirect back to
86+
routeBackFallbackPath: "/movies",
87+
88+
// Do something straight before navigation or adjust NS routing settings
89+
routeToCallback: (to, options) => {
90+
// For example, change page navigation transition for the vertical on iOS
91+
if (to.meta.isVertical) {
92+
options.transition = {
93+
name: "fade",
94+
};
95+
}
96+
},
97+
98+
// Do something straight before navigation or adjust NS routing settings
99+
routeBackCallback: (_to, options) => {
100+
//
101+
},
102+
103+
// Set Vue Instance (Vue.prototype by default)
104+
vm: Vue.prototype,
105+
106+
// Set a custom logger (console.log by default)
107+
logger: console.log,
108+
109+
// Set custom frame, by default it's taken from @nativescript/core/ui/frame
110+
frame: Frame,
111+
}
112+
);
113+
114+
// From now on you can access this.$router, this.$routeBack and special this.$routeTo inside of the components
115+
116+
// Register a global guard (optional)
117+
router.beforeEach((to) => {
118+
// For example, verify per route access rules
119+
if (!canAccessRoute(to)) {
120+
return false;
121+
}
122+
123+
return true;
124+
});
125+
126+
// You can also use global router.beforeResolve guard and router.afterEach hook
127+
```
128+
129+
## New hooks for pages
130+
131+
You can use hooks directly on particular pages. It is discouraged to use them inside of mixins or components for the time being. Example below:
132+
133+
```javascript
134+
<template>
135+
<Page>
136+
</Page>
137+
</template>
138+
139+
<script>
140+
141+
export default {
142+
name: 'movies',
143+
144+
beforeRouteEnter(to, from, next) {
145+
// Do something before to enter to the route
146+
next((vm) => {
147+
// Do something once navigation is done
148+
// Instead of `this`, use `vm`
149+
});
150+
},
151+
152+
beforeRouteLeave() {
153+
// Do something before to leave the route
154+
// You can use `this` inside of this hook
155+
},
156+
157+
beforeRouteUpdate() {
158+
// Do something before to leave the route
159+
// before redirecting to another route with same path
160+
// You can use `this` inside of this hook
161+
},
162+
};
163+
</script>
164+
```
165+
166+
| NS Event | Mapped as | Description |
167+
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
168+
| navigatingFrom | `beforeRouteLeave` | Before user leaves the route |
169+
| navigatingTo | `beforeRouteEnter` | Before user enters a route |
170+
| - | `beforeRouteUpdate` | Before route is changed but view remains the same. This can happen when path is exactly the same but you change e.g. passed prop to the route. Please refer to Vue-Router docs for more details. |
171+
| navigatedTo | `beforeRouteEnter` | To trigger it properly you need to access component instance. You can use `next(vm => ...)` callback within `beforeRouteEnter()`. Please check Vue-Router docs for more details. |
172+
| navigatedFrom | - | This event is tricky to control for developers. There is no exact mapping of it in the router. For store state cleanup use build-in meta dispatcher instead. For component state you could opt for using `beforeRouteLeave()`. You could potentially use `navigatedFrom` directly inside of the page but you |
173+
174+
## API & Limitations
175+
176+
This plugin aims for compatibility with Vue Router 3+ and Vue Router 4+. Both should be easily supported. Please refer to [Vue Router Docs](https://next.router.vuejs.org/guide/) for more information. There are some obvious limitations like lack of DOM accessibility and related events, or lack of <router-link /> component.
32177

33178
## License
34179

0 commit comments

Comments
 (0)