Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/girardinsamuel/masonite-js-routes
Use your Masonite named routes in Javascript
https://github.com/girardinsamuel/masonite-js-routes
masonite masonite-package python ziggy
Last synced: 2 months ago
JSON representation
Use your Masonite named routes in Javascript
- Host: GitHub
- URL: https://github.com/girardinsamuel/masonite-js-routes
- Owner: girardinsamuel
- License: mit
- Created: 2020-09-23T21:08:01.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-09-04T22:13:22.000Z (over 1 year ago)
- Last Synced: 2024-08-09T03:10:41.555Z (5 months ago)
- Topics: masonite, masonite-package, python, ziggy
- Language: Python
- Homepage:
- Size: 319 KB
- Stars: 6
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
## Introduction
Use your Masonite named routes in Javascript.
This package provides a helper that inject your Masonite application routes definition into your views. It will export a JavaScript object of your application's named routes, keyed by their names (aliases).
You can combine it with [ziggy-js](https://github.com/tighten/ziggy) library as to get a global `route()` helper function which you can use to access your routes in your JavaScript.
## Features
- Avoid hard-coding urls client-side
- Generate once your routes file
- Compatible with client-side route helper `ziggy-js`
- Possibility to filter routes to include client-side
## Official Masonite Documentation
New to Masonite ? Please first read the [Official Documentation](https://docs.masoniteproject.com/).
Masonite strives to have extremely comprehensive documentation 😃. It would be wise to go through the tutorials there.
If you find any discrepencies or anything that doesn't make sense, be sure to comment directly on the documentation to start a discussion!
Hop on [Masonite Discord Community](https://discord.gg/TwKeFahmPZ) to ask any questions you need!
## Installation
```bash
pip install masonite-js-routes
```
## Configuration
Add JSRoutesProvider to your project in `config/providers.py`:
```python
# config/providers.py
# ...
from masonite.js_routes import JSRoutesProvider
# ...
PROVIDERS = [
# ...
# Third Party Providers
JSRoutesProvider,
# ...
]
```
Then you can publish the configuration file in your project if you need to change some parameters:
```bash
python craft package:publish js_routes
```
## Usage
⚠️ The routes must have a name, else the package won't pick up your routes ! Ensure you're using `Route.get()...name("some_name")`.
1. [Using `routes` view helper](#1.-using-routes-view-helper): routes will be generated at each request and included client-side in the page.
2. [Generating routes as Javascript file](#2.-generating-routes-as-javascript-file): routes are generated once in a file and you load this file client-side. When you update your routes, you must regenerate the file.
### 1. Using `routes` view helper
1. In your views, just add this helper where you want to get `Ziggy` routes as a Javascript object (e.g. in `` or at the end of body).
```html
{{ routes() }}
```
#### Basic filtering
Only the routes matching a list of name patterns will be included:
```python
FILTERS = {
"only": ["welcome.*"],
}
```
Only the routes which does not match a list of name patterns will be included:
```python
FILTERS = {
"except": ["admin.*"],
}
```
**Note: You have to choose one or the other. Setting both `only` and `except` will disable filtering altogether and simply return the default list of routes.**
#### Filtering using Groups
Only the routes matching a group or a list of groups will be included if
groups are passed to the helpers
```python
FILTERS = {
"groups": {
"app": ["app.*"],
"api": ["api.*"],
}
}
```
and in your view :
```html
{{ routes('app') }}
```
or a list of group names
```html
{{ routes(['app', 'api']) }}
```
**Note: Passing group names to the `routes` helper will always take precedence over your other only or except settings.**
### 2. Generating routes as Javascript file
You can also generate once the routes as a Javascript file. For now it generates a file exporting
`Ziggy` object routes as it is made to use it with `ziggy-js`.
To generate the routes, run the craft command (it takes an optional `--path` argument to change the output path):
```bash
python craft js_routes:generate
```
(You could add this into a pipeline, to regenerate it whenever needed).
You will get a file like this:
```js
var Ziggy = {
routes: {
home: { uri: "", methods: ["GET", "HEAD"], domain: null },
login: { uri: "login", methods: ["GET", "HEAD"], domain: null },
},
url: "http://ziggy.test",
port: null,
defaults: {},
};
export { Ziggy };
```
## Client-side usage
Then to be able to use it client-side you can refer to [ziggy-js documentation](https://github.com/tighten/ziggy#advanced-setup).
(Note that you don't have to use this library you can use the routes objects as you like.)
### Quick explanation with Vue.js
Install the library:
```bash
npm install ziggy-js
```
Then in your Vue.js entrypoint you could for example define a global `route()` mixin (using the `route()` method from `ziggy-js`).
- With the **option 1**, `Ziggy` will be available in the global javascript `window` scope
```javascript
// app.js
import { createApp, h } from "vue";
import route from "ziggy-js";
import App from "./App.vue";
const app = createApp(App).mixin({
methods: {
route(name, params = {}, absolute = true) {
return route(name, params, absolute, window.Ziggy);
},
},
});
// App.vue
// ...
this.route("users", 2); // == http://ziggy.test/users/2
```
- With the **option 2**, the routes config must be imported from the generated file (instead of the `window` object)
```javascript
// app.js
import { createApp, h } from "vue";
import route from "ziggy-js";
import { Ziggy } from "./routes";
import App from "./App.vue";
const app = createApp(App).mixin({
methods: {
route(name, params = {}, absolute = true) {
return route(name, params, absolute, Ziggy);
},
},
});
// App.vue
// ...
this.route("users", 2); // == http://ziggy.test/users/2
```
## Content Security Policy
A Content Security Policy may block unsafe inline scripts which Ziggy uses to pass the routes to JavaScript. By adding a nonce to your CSP you can allow certain inlined scripts. To add this nonce to Ziggy you can pass it as the second argument to the helper:
```html
{{ routes(false, '[YOUR_NONCE]') }}
```
## Contributing
Please read the [Contributing Documentation](CONTRIBUTING.md) here.
## Maintainers
- [Samuel Girardin](https://www.github.com/girardinsamuel)
## License
Masonite JS Routes is open-sourced software licensed under the [MIT license](LICENSE).