@ramstack/alpinegear-router 1.4.3 → 1.4.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +354 -387
- package/alpinegear-router.esm.js +856 -856
- package/alpinegear-router.esm.min.js +1 -1
- package/alpinegear-router.js +856 -856
- package/alpinegear-router.min.js +1 -1
- package/package.json +9 -3
package/README.md
CHANGED
|
@@ -1,387 +1,354 @@
|
|
|
1
|
-
# @ramstack/alpinegear-router
|
|
2
|
-
[](https://www.npmjs.com/package/@ramstack/alpinegear-router)
|
|
3
|
-
[](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE)
|
|
4
|
-
|
|
5
|
-
`@ramstack/alpinegear-router` is a plugin for [Alpine.js](https://alpinejs.dev/) that provides routing-related directives
|
|
6
|
-
for Alpine.js, enabling client-side navigation and routing functionality.
|
|
7
|
-
|
|
8
|
-
## Installation
|
|
9
|
-
|
|
10
|
-
### Using CDN
|
|
11
|
-
To include the CDN version of this plugin, add the following `<script>` tag before the core `alpine.js` file:
|
|
12
|
-
|
|
13
|
-
```html
|
|
14
|
-
<!-- alpine.js plugin -->
|
|
15
|
-
<script src="https://cdn.jsdelivr.net/npm/@ramstack/alpinegear-router@1/alpinegear-router.min.js" defer></script>
|
|
16
|
-
|
|
17
|
-
<!-- alpine.js -->
|
|
18
|
-
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js" defer></script>
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
### Using NPM
|
|
22
|
-
Alternatively, you can install the plugin via `npm`:
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
npm install --save @ramstack/alpinegear-router
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
Then, initialize it in your project:
|
|
29
|
-
|
|
30
|
-
```js
|
|
31
|
-
import Alpine from "alpinejs";
|
|
32
|
-
import router from "@ramstack/alpinegear-router";
|
|
33
|
-
|
|
34
|
-
Alpine.plugin(router);
|
|
35
|
-
Alpine.start();
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
## Usage
|
|
39
|
-
|
|
40
|
-
```html
|
|
41
|
-
<div x-data x-router>
|
|
42
|
-
<h1>Hello World!</h1>
|
|
43
|
-
|
|
44
|
-
<div>
|
|
45
|
-
<b>Current route:</b>
|
|
46
|
-
<pre x-format>{{ JSON.stringify($route, null, 2) }}</pre>
|
|
47
|
-
</div>
|
|
48
|
-
|
|
49
|
-
<!-- Inline template -->
|
|
50
|
-
<template x-route="/">
|
|
51
|
-
Home page
|
|
52
|
-
</template>
|
|
53
|
-
|
|
54
|
-
<!-- External template -->
|
|
55
|
-
<template x-route="/about" x-route:view="/views/about.html"></template>
|
|
56
|
-
|
|
57
|
-
<nav>
|
|
58
|
-
<a x-router:link href="/">Home</a>
|
|
59
|
-
<a x-router:link.replace href="/about">About</a>
|
|
60
|
-
</nav>
|
|
61
|
-
|
|
62
|
-
<!-- Render the matching route -->
|
|
63
|
-
<main x-router:outlet></main>
|
|
64
|
-
</div>
|
|
65
|
-
```
|
|
66
|
-
🚀 [Live demo | Alpine.js x-router: Basic example](https://jsfiddle.net/rameel/h9mygjcd/)<br />
|
|
67
|
-
🚀 [Live demo | Alpine.js x-router: Nested router](https://jsfiddle.net/rameel/cjoza3ng/)
|
|
68
|
-
|
|
69
|
-
## History modes
|
|
70
|
-
The router can be configured to use different history modes. There are two available modes:
|
|
71
|
-
* `html5`: The default history mode.
|
|
72
|
-
* `hash`: Uses a hash `#` in the URL to manage history.
|
|
73
|
-
|
|
74
|
-
### HTML5 mode
|
|
75
|
-
The `html5` mode uses the browser's history API to manage navigation.
|
|
76
|
-
|
|
77
|
-
```html
|
|
78
|
-
<div x-data x-router:html5>
|
|
79
|
-
...
|
|
80
|
-
</div>
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
Since this mode is the default, there is no need to specify it explicitly:
|
|
84
|
-
|
|
85
|
-
```html
|
|
86
|
-
<!-- HTML5 mode is used by default -->
|
|
87
|
-
<div x-data x-router>
|
|
88
|
-
...
|
|
89
|
-
</div>
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
### Hash mode
|
|
93
|
-
This mode uses a hash `#` in the URL to handle navigation. Unlike `html5` mode, it requires no special server-side
|
|
94
|
-
configuration since the browser does not send the hash portion of the URL to the server.
|
|
95
|
-
```html
|
|
96
|
-
<div x-data x-router:hash>
|
|
97
|
-
...
|
|
98
|
-
</div>
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## Route directive
|
|
102
|
-
Routes are defined using a `<template>` element with the `x-route` attribute.
|
|
103
|
-
|
|
104
|
-
```html
|
|
105
|
-
<div x-router>
|
|
106
|
-
<template x-route="/">
|
|
107
|
-
Home page
|
|
108
|
-
</template>
|
|
109
|
-
|
|
110
|
-
<template x-route="/profile/{username}">
|
|
111
|
-
Profile
|
|
112
|
-
</template>
|
|
113
|
-
|
|
114
|
-
<!-- Render the matching route -->
|
|
115
|
-
<div x-router:outlet></div>
|
|
116
|
-
</div>
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
In this example, two routes are defined: a static `/` route representing the homepage,
|
|
120
|
-
and a dynamic (parameterized) route `/profile/{username}`, where `username` is a route parameter enclosed
|
|
121
|
-
in curly brackets.
|
|
122
|
-
|
|
123
|
-
This means that URLs like `/profile/john` and `/profile/samantha` will both match the same route.
|
|
124
|
-
When a route is matched, the `username` parameter can be accessed via `$route.params.username`.
|
|
125
|
-
|
|
126
|
-
For more details on dynamic (parameterized) routes, refer to the corresponding section below.
|
|
127
|
-
|
|
128
|
-
## Outlet directive
|
|
129
|
-
|
|
130
|
-
The `x-router:outlet` directive is used to render the matching route's content and can be placed anywhere
|
|
131
|
-
within an `x-router` element. If no route matches, `x-router:outlet` will render nothing.
|
|
132
|
-
|
|
133
|
-
```html
|
|
134
|
-
<div x-router>
|
|
135
|
-
<template x-route="/">
|
|
136
|
-
Home page
|
|
137
|
-
</template>
|
|
138
|
-
|
|
139
|
-
<template x-route="/profile/{username}">
|
|
140
|
-
Profile
|
|
141
|
-
</template>
|
|
142
|
-
|
|
143
|
-
<!-- Render the matching route -->
|
|
144
|
-
<div x-router:outlet></div>
|
|
145
|
-
</div>
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
## Link directive
|
|
149
|
-
|
|
150
|
-
```html
|
|
151
|
-
<div x-router:hash>
|
|
152
|
-
...
|
|
153
|
-
<nav>
|
|
154
|
-
<a x-router:link href="/">Home</a>
|
|
155
|
-
<a x-router:link href="/about">About</a>
|
|
156
|
-
</nav>
|
|
157
|
-
</div>
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
The router does not automatically intercept all links. Only links with the `x-router:link` directive
|
|
161
|
-
inside an `x-router` container are handled by the router. Links should always be specified normally,
|
|
162
|
-
regardless of the selected history mode.
|
|
163
|
-
|
|
164
|
-
### Applying `x-router:link` to parent elements
|
|
165
|
-
|
|
166
|
-
You can also apply `x-router:link` to parent elements, such as `<li>`, to enable more flexible markup structures:
|
|
167
|
-
```html
|
|
168
|
-
<li x-router:link :class="{ active: $active }">
|
|
169
|
-
<a href="/about">About</a>
|
|
170
|
-
</li>
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
In this case:
|
|
174
|
-
* `x-router:link` will locate the nested `<a>` element within the parent and use its `href` for routing.
|
|
175
|
-
* The `$active` state will correctly reflect whether the nested link's `href` matches the current route.
|
|
176
|
-
|
|
177
|
-
### Modifier `replace`
|
|
178
|
-
|
|
179
|
-
The `replace` modifier changes the default navigation behavior of the router. When a link with this modifier is clicked,
|
|
180
|
-
it triggers `$router.navigate(href, /* replace */ true)`.
|
|
181
|
-
|
|
182
|
-
Unlike the default behavior, which adds a new entry to the browser's history stack, this option replaces
|
|
183
|
-
the current history entry with the new URL. As a result, the user's navigation history remains unchanged,
|
|
184
|
-
and pressing the **"Back"** button will skip over the replaced entry.
|
|
185
|
-
|
|
186
|
-
```html
|
|
187
|
-
<div x-router:hash>
|
|
188
|
-
...
|
|
189
|
-
<nav>
|
|
190
|
-
<a x-router:link href="/">Home</a>
|
|
191
|
-
<!-- The "replace" modifier ensures that clicking this link
|
|
192
|
-
replaces the current history entry instead of adding a new one -->
|
|
193
|
-
<a x-router:link.replace href="/about">About</a>
|
|
194
|
-
</nav>
|
|
195
|
-
</div>
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
## Inline and External templates
|
|
199
|
-
Routes can be defined using either **inline templates** or **external templates**:
|
|
200
|
-
|
|
201
|
-
**Inline templates:**<br />
|
|
202
|
-
The content of the route is directly written inside the `<template>` element.
|
|
203
|
-
```html
|
|
204
|
-
<template x-route="/">
|
|
205
|
-
Home page
|
|
206
|
-
</template>
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
**External templates:**<br />
|
|
210
|
-
The content of the route is loaded from an external HTML file specified in the `x-route:view` directive.
|
|
211
|
-
```html
|
|
212
|
-
<template x-route="/about" x-route:view="/views/about.html"></template>
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
## Magic functions
|
|
216
|
-
|
|
217
|
-
### Magic `$route`
|
|
218
|
-
Indicates the current active route and contains the following properties:
|
|
219
|
-
|
|
220
|
-
```html
|
|
221
|
-
<dl x-format>
|
|
222
|
-
<dt>Route pattern:</dt>
|
|
223
|
-
<dd>{{ $route.pattern }}</dd>
|
|
224
|
-
|
|
225
|
-
<dt>Route path:</dt>
|
|
226
|
-
<dd>{{ $route.path }}</dd>
|
|
227
|
-
|
|
228
|
-
<dt>Route params:</dt>
|
|
229
|
-
<dd>{{ $route.params.username }}</dd>
|
|
230
|
-
</dl>
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
### Magic `$active`
|
|
234
|
-
Returns `true` or `false`, indicating whether a `x-router:link` corresponds to the active route.
|
|
235
|
-
|
|
236
|
-
```html
|
|
237
|
-
<nav>
|
|
238
|
-
<a x-router:link href="/" class="{ active: $active }">Home</a>
|
|
239
|
-
<a x-router:link href="/about" class="{ active: $active }">About</a>
|
|
240
|
-
</nav>
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
#### Applying active class to parent element
|
|
244
|
-
|
|
245
|
-
```html
|
|
246
|
-
<li x-router:link :class="{ active: $active }">
|
|
247
|
-
<a href="/about">About</a>
|
|
248
|
-
</li>
|
|
249
|
-
```
|
|
250
|
-
The `$active` state will correctly reflect whether the nested link's `href` matches the current route.
|
|
251
|
-
|
|
252
|
-
## Route templates
|
|
253
|
-
|
|
254
|
-
Routes can contain parameters enclosed in `{}` that are dynamically bound when a route is matched.
|
|
255
|
-
Multiple parameters can be used within a route segment, but they must be separated by a static value. For example:
|
|
256
|
-
```
|
|
257
|
-
{controller}{action}
|
|
258
|
-
```
|
|
259
|
-
is invalid because `{controller}` and `{action}` are not separated by a static value.
|
|
260
|
-
Instead, valid routes should use static separators:
|
|
261
|
-
```
|
|
262
|
-
{controller}/{action}
|
|
263
|
-
```
|
|
264
|
-
```
|
|
265
|
-
article/{id}-{title}
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
### Route parameters
|
|
269
|
-
Route parameters must have a name and can also include additional attributes.
|
|
270
|
-
Literal values and path separators (`/`) must match exactly in the URL. Matching is case-insensitive and based
|
|
271
|
-
on the decoded URL representation.
|
|
272
|
-
|
|
273
|
-
#### Optional and Catch-All Parameters
|
|
274
|
-
- **Optional parameters**: Defined with `?`, meaning they are not required. Example: `{id?}`
|
|
275
|
-
- **Catch-all parameters** (`*`): Capture the remaining part of the URL. Example: `blog/{slug*}`
|
|
276
|
-
- Matches any URL starting with `blog/`.
|
|
277
|
-
- The remaining value is assigned to the `slug` parameter.
|
|
278
|
-
- **Required catch-all parameters** (`+`): Like `*`, but at least one segment must match.
|
|
279
|
-
|
|
280
|
-
### Parameter constraints
|
|
281
|
-
Route parameters can have constraints to validate and transform values. Constraints are added using `:` after the parameter name.
|
|
282
|
-
If a constraint requires arguments, they are placed in parentheses.
|
|
283
|
-
|
|
284
|
-
Example:
|
|
285
|
-
```
|
|
286
|
-
blog/{id:int:min(100)}/{article:minlength(10)}
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
- `{id:int:min(100)}` ensures `id` is an integer and at least 100.
|
|
290
|
-
- `{article:minlength(10)}` requires `article` to be at least 10 characters long.
|
|
291
|
-
|
|
292
|
-
Some constraints also transform parameters. For example, `{id:int}` automatically converts `id` to a number.
|
|
293
|
-
|
|
294
|
-
### Default values
|
|
295
|
-
Route parameters can have **default values**, specified similarly to constraints but using `=` or `default`. Example:
|
|
296
|
-
```
|
|
297
|
-
{controller:=(home)}
|
|
298
|
-
```
|
|
299
|
-
is equivalent to:
|
|
300
|
-
```
|
|
301
|
-
{controller:default(home)}
|
|
302
|
-
```
|
|
303
|
-
If no value is provided in the URL, the default is used.
|
|
304
|
-
|
|
305
|
-
### Example route patterns
|
|
306
|
-
|
|
307
|
-
| Route template | URI | Description |
|
|
308
|
-
|------------------------------------------------|-------------------|---------------------------------------------------------------|
|
|
309
|
-
| `hello` | `/hello` | Matches only `/hello`. |
|
|
310
|
-
| `{controller}/{action}/{id?}` | `/product/list` | Matches and sets `controller=product`, `action=list`. |
|
|
311
|
-
| `{controller}/{action}/{id?}` | `/product/list/1` | Matches and sets `controller=product`, `action=list`, `id=1`. |
|
|
312
|
-
| `{controller:=(home)}/{action:=(index)}/{id?}` | `/` | Matches and sets `controller=home`, `action=index`. |
|
|
313
|
-
| `{controller:=(home)}/{action:=(index)}/{id?}` | `/product` | Matches and sets `controller=product`, `action=index`. |
|
|
314
|
-
| `blog/{slug*:=(start/with/new/blog)}` | `/blog` | Matches and sets `slug=[start,with,new,blog]`. |
|
|
315
|
-
|
|
316
|
-
### Route constraints
|
|
317
|
-
|
|
318
|
-
| Constraint | Example | Description |
|
|
319
|
-
|--------------------|-------------------------------|---------------------------------------------------|
|
|
320
|
-
| `int` | `{id:int}` | Matches an integer. |
|
|
321
|
-
| `bool` | `{id:bool}` | Matches `true` or `false` (case-insensitive). |
|
|
322
|
-
| `number` | `{speed:number}` | Matches a valid number. |
|
|
323
|
-
| `alpha` | `{name:alpha}` | Matches alphabetic characters (case-insensitive). |
|
|
324
|
-
| `min(value)` | `{age:min(25)}` | Ensures the value is at least `25`. |
|
|
325
|
-
| `max(value)` | `{age:max(125)}` | Ensures the value is no more than `125`. |
|
|
326
|
-
| `range(min,max)` | `{age:range(25,125)}` | Ensures the value is between `25` and `125`. |
|
|
327
|
-
| `length(value)` | `{file:length(10)}` | Requires exactly `10` characters. |
|
|
328
|
-
| `length(min,max)` | `{file:length(10,20)}` | Requires between `10` and `20` characters. |
|
|
329
|
-
| `minlength(value)` | `{name:minlength(10)}` | Requires at least `10` characters. |
|
|
330
|
-
| `maxlength(value)` | `{name:maxlength(50)}` | Requires no more than `50` characters. |
|
|
331
|
-
| `regex(expr)` | `{id:regex(^\\d{3}-\\d{5}$)}` | Must match a specific regex pattern. |
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
## Source Code
|
|
335
|
-
You can find the source code for this plugin on GitHub:
|
|
336
|
-
|
|
337
|
-
https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/router
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
Provides the `x-template` directive, which allows you to define a template once anywhere in the DOM and reference it by its ID.
|
|
356
|
-
|
|
357
|
-
**[@ramstack/alpinegear-fragment](https://www.npmjs.com/package/@ramstack/alpinegear-fragment)** ([README](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/fragment))<br>
|
|
358
|
-
Provides the `x-fragment` directive, which allows for fragment-like behavior similar to what's available in frameworks
|
|
359
|
-
like `Vue.js` or `React`, where multiple root elements can be grouped together.
|
|
360
|
-
|
|
361
|
-
**[@ramstack/alpinegear-match](https://www.npmjs.com/package/@ramstack/alpinegear-match)** ([README](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/match))<br>
|
|
362
|
-
Provides the `x-match` directive, which functions similarly to the `switch` statement in many programming languages,
|
|
363
|
-
allowing you to conditionally render elements based on matching cases.
|
|
364
|
-
|
|
365
|
-
**[@ramstack/alpinegear-when](https://www.npmjs.com/package/@ramstack/alpinegear-when)** ([README](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/when))<br>
|
|
366
|
-
Provides the `x-when` directive, which allows for conditional rendering of elements similar to `x-if`, but supports multiple root elements.
|
|
367
|
-
|
|
368
|
-
**[@ramstack/alpinegear-destroy](https://www.npmjs.com/package/@ramstack/alpinegear-destroy)** ([README](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/destroy))<br>
|
|
369
|
-
Provides the `x-destroy` directive, which is the opposite of `x-init` and allows you to hook into the cleanup phase
|
|
370
|
-
of any element, running a callback when the element is removed from the DOM.
|
|
371
|
-
|
|
372
|
-
**[@ramstack/alpinegear-hotkey](https://www.npmjs.com/package/@ramstack/alpinegear-hotkey)** ([README](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/hotkey))<br>
|
|
373
|
-
Provides the `x-hotkey` directive, which allows you to easily handle keyboard shortcuts within your Alpine.js components or application.
|
|
374
|
-
|
|
375
|
-
**[@ramstack/alpinegear-dialog](https://www.npmjs.com/package/@ramstack/alpinegear-dialog)** ([README](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/dialog))<br>
|
|
376
|
-
Provides a headless dialog directive for Alpine.js based on the native HTML `<dialog>` element.
|
|
377
|
-
It supports declarative composition, value-based close semantics, and both modal and non-modal dialogs,
|
|
378
|
-
with optional Promise-based imperative control.
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
## Contributions
|
|
382
|
-
Bug reports and contributions are welcome.
|
|
383
|
-
|
|
384
|
-
## License
|
|
385
|
-
This package is released as open source under the **MIT License**.
|
|
386
|
-
|
|
387
|
-
See the [LICENSE](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE) file for more details.
|
|
1
|
+
# @ramstack/alpinegear-router
|
|
2
|
+
[](https://www.npmjs.com/package/@ramstack/alpinegear-router)
|
|
3
|
+
[](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE)
|
|
4
|
+
|
|
5
|
+
`@ramstack/alpinegear-router` is a plugin for [Alpine.js](https://alpinejs.dev/) that provides routing-related directives
|
|
6
|
+
for Alpine.js, enabling client-side navigation and routing functionality.
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
|
|
10
|
+
### Using CDN
|
|
11
|
+
To include the CDN version of this plugin, add the following `<script>` tag before the core `alpine.js` file:
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
<!-- alpine.js plugin -->
|
|
15
|
+
<script src="https://cdn.jsdelivr.net/npm/@ramstack/alpinegear-router@1/alpinegear-router.min.js" defer></script>
|
|
16
|
+
|
|
17
|
+
<!-- alpine.js -->
|
|
18
|
+
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js" defer></script>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Using NPM
|
|
22
|
+
Alternatively, you can install the plugin via `npm`:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install --save @ramstack/alpinegear-router
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then, initialize it in your project:
|
|
29
|
+
|
|
30
|
+
```js
|
|
31
|
+
import Alpine from "alpinejs";
|
|
32
|
+
import router from "@ramstack/alpinegear-router";
|
|
33
|
+
|
|
34
|
+
Alpine.plugin(router);
|
|
35
|
+
Alpine.start();
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Usage
|
|
39
|
+
|
|
40
|
+
```html
|
|
41
|
+
<div x-data x-router>
|
|
42
|
+
<h1>Hello World!</h1>
|
|
43
|
+
|
|
44
|
+
<div>
|
|
45
|
+
<b>Current route:</b>
|
|
46
|
+
<pre x-format>{{ JSON.stringify($route, null, 2) }}</pre>
|
|
47
|
+
</div>
|
|
48
|
+
|
|
49
|
+
<!-- Inline template -->
|
|
50
|
+
<template x-route="/">
|
|
51
|
+
Home page
|
|
52
|
+
</template>
|
|
53
|
+
|
|
54
|
+
<!-- External template -->
|
|
55
|
+
<template x-route="/about" x-route:view="/views/about.html"></template>
|
|
56
|
+
|
|
57
|
+
<nav>
|
|
58
|
+
<a x-router:link href="/">Home</a>
|
|
59
|
+
<a x-router:link.replace href="/about">About</a>
|
|
60
|
+
</nav>
|
|
61
|
+
|
|
62
|
+
<!-- Render the matching route -->
|
|
63
|
+
<main x-router:outlet></main>
|
|
64
|
+
</div>
|
|
65
|
+
```
|
|
66
|
+
🚀 [Live demo | Alpine.js x-router: Basic example](https://jsfiddle.net/rameel/h9mygjcd/)<br />
|
|
67
|
+
🚀 [Live demo | Alpine.js x-router: Nested router](https://jsfiddle.net/rameel/cjoza3ng/)
|
|
68
|
+
|
|
69
|
+
## History modes
|
|
70
|
+
The router can be configured to use different history modes. There are two available modes:
|
|
71
|
+
* `html5`: The default history mode.
|
|
72
|
+
* `hash`: Uses a hash `#` in the URL to manage history.
|
|
73
|
+
|
|
74
|
+
### HTML5 mode
|
|
75
|
+
The `html5` mode uses the browser's history API to manage navigation.
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<div x-data x-router:html5>
|
|
79
|
+
...
|
|
80
|
+
</div>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Since this mode is the default, there is no need to specify it explicitly:
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
<!-- HTML5 mode is used by default -->
|
|
87
|
+
<div x-data x-router>
|
|
88
|
+
...
|
|
89
|
+
</div>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Hash mode
|
|
93
|
+
This mode uses a hash `#` in the URL to handle navigation. Unlike `html5` mode, it requires no special server-side
|
|
94
|
+
configuration since the browser does not send the hash portion of the URL to the server.
|
|
95
|
+
```html
|
|
96
|
+
<div x-data x-router:hash>
|
|
97
|
+
...
|
|
98
|
+
</div>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Route directive
|
|
102
|
+
Routes are defined using a `<template>` element with the `x-route` attribute.
|
|
103
|
+
|
|
104
|
+
```html
|
|
105
|
+
<div x-router>
|
|
106
|
+
<template x-route="/">
|
|
107
|
+
Home page
|
|
108
|
+
</template>
|
|
109
|
+
|
|
110
|
+
<template x-route="/profile/{username}">
|
|
111
|
+
Profile
|
|
112
|
+
</template>
|
|
113
|
+
|
|
114
|
+
<!-- Render the matching route -->
|
|
115
|
+
<div x-router:outlet></div>
|
|
116
|
+
</div>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
In this example, two routes are defined: a static `/` route representing the homepage,
|
|
120
|
+
and a dynamic (parameterized) route `/profile/{username}`, where `username` is a route parameter enclosed
|
|
121
|
+
in curly brackets.
|
|
122
|
+
|
|
123
|
+
This means that URLs like `/profile/john` and `/profile/samantha` will both match the same route.
|
|
124
|
+
When a route is matched, the `username` parameter can be accessed via `$route.params.username`.
|
|
125
|
+
|
|
126
|
+
For more details on dynamic (parameterized) routes, refer to the corresponding section below.
|
|
127
|
+
|
|
128
|
+
## Outlet directive
|
|
129
|
+
|
|
130
|
+
The `x-router:outlet` directive is used to render the matching route's content and can be placed anywhere
|
|
131
|
+
within an `x-router` element. If no route matches, `x-router:outlet` will render nothing.
|
|
132
|
+
|
|
133
|
+
```html
|
|
134
|
+
<div x-router>
|
|
135
|
+
<template x-route="/">
|
|
136
|
+
Home page
|
|
137
|
+
</template>
|
|
138
|
+
|
|
139
|
+
<template x-route="/profile/{username}">
|
|
140
|
+
Profile
|
|
141
|
+
</template>
|
|
142
|
+
|
|
143
|
+
<!-- Render the matching route -->
|
|
144
|
+
<div x-router:outlet></div>
|
|
145
|
+
</div>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Link directive
|
|
149
|
+
|
|
150
|
+
```html
|
|
151
|
+
<div x-router:hash>
|
|
152
|
+
...
|
|
153
|
+
<nav>
|
|
154
|
+
<a x-router:link href="/">Home</a>
|
|
155
|
+
<a x-router:link href="/about">About</a>
|
|
156
|
+
</nav>
|
|
157
|
+
</div>
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The router does not automatically intercept all links. Only links with the `x-router:link` directive
|
|
161
|
+
inside an `x-router` container are handled by the router. Links should always be specified normally,
|
|
162
|
+
regardless of the selected history mode.
|
|
163
|
+
|
|
164
|
+
### Applying `x-router:link` to parent elements
|
|
165
|
+
|
|
166
|
+
You can also apply `x-router:link` to parent elements, such as `<li>`, to enable more flexible markup structures:
|
|
167
|
+
```html
|
|
168
|
+
<li x-router:link :class="{ active: $active }">
|
|
169
|
+
<a href="/about">About</a>
|
|
170
|
+
</li>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
In this case:
|
|
174
|
+
* `x-router:link` will locate the nested `<a>` element within the parent and use its `href` for routing.
|
|
175
|
+
* The `$active` state will correctly reflect whether the nested link's `href` matches the current route.
|
|
176
|
+
|
|
177
|
+
### Modifier `replace`
|
|
178
|
+
|
|
179
|
+
The `replace` modifier changes the default navigation behavior of the router. When a link with this modifier is clicked,
|
|
180
|
+
it triggers `$router.navigate(href, /* replace */ true)`.
|
|
181
|
+
|
|
182
|
+
Unlike the default behavior, which adds a new entry to the browser's history stack, this option replaces
|
|
183
|
+
the current history entry with the new URL. As a result, the user's navigation history remains unchanged,
|
|
184
|
+
and pressing the **"Back"** button will skip over the replaced entry.
|
|
185
|
+
|
|
186
|
+
```html
|
|
187
|
+
<div x-router:hash>
|
|
188
|
+
...
|
|
189
|
+
<nav>
|
|
190
|
+
<a x-router:link href="/">Home</a>
|
|
191
|
+
<!-- The "replace" modifier ensures that clicking this link
|
|
192
|
+
replaces the current history entry instead of adding a new one -->
|
|
193
|
+
<a x-router:link.replace href="/about">About</a>
|
|
194
|
+
</nav>
|
|
195
|
+
</div>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Inline and External templates
|
|
199
|
+
Routes can be defined using either **inline templates** or **external templates**:
|
|
200
|
+
|
|
201
|
+
**Inline templates:**<br />
|
|
202
|
+
The content of the route is directly written inside the `<template>` element.
|
|
203
|
+
```html
|
|
204
|
+
<template x-route="/">
|
|
205
|
+
Home page
|
|
206
|
+
</template>
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
**External templates:**<br />
|
|
210
|
+
The content of the route is loaded from an external HTML file specified in the `x-route:view` directive.
|
|
211
|
+
```html
|
|
212
|
+
<template x-route="/about" x-route:view="/views/about.html"></template>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## Magic functions
|
|
216
|
+
|
|
217
|
+
### Magic `$route`
|
|
218
|
+
Indicates the current active route and contains the following properties:
|
|
219
|
+
|
|
220
|
+
```html
|
|
221
|
+
<dl x-format>
|
|
222
|
+
<dt>Route pattern:</dt>
|
|
223
|
+
<dd>{{ $route.pattern }}</dd>
|
|
224
|
+
|
|
225
|
+
<dt>Route path:</dt>
|
|
226
|
+
<dd>{{ $route.path }}</dd>
|
|
227
|
+
|
|
228
|
+
<dt>Route params:</dt>
|
|
229
|
+
<dd>{{ $route.params.username }}</dd>
|
|
230
|
+
</dl>
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Magic `$active`
|
|
234
|
+
Returns `true` or `false`, indicating whether a `x-router:link` corresponds to the active route.
|
|
235
|
+
|
|
236
|
+
```html
|
|
237
|
+
<nav>
|
|
238
|
+
<a x-router:link href="/" class="{ active: $active }">Home</a>
|
|
239
|
+
<a x-router:link href="/about" class="{ active: $active }">About</a>
|
|
240
|
+
</nav>
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
#### Applying active class to parent element
|
|
244
|
+
|
|
245
|
+
```html
|
|
246
|
+
<li x-router:link :class="{ active: $active }">
|
|
247
|
+
<a href="/about">About</a>
|
|
248
|
+
</li>
|
|
249
|
+
```
|
|
250
|
+
The `$active` state will correctly reflect whether the nested link's `href` matches the current route.
|
|
251
|
+
|
|
252
|
+
## Route templates
|
|
253
|
+
|
|
254
|
+
Routes can contain parameters enclosed in `{}` that are dynamically bound when a route is matched.
|
|
255
|
+
Multiple parameters can be used within a route segment, but they must be separated by a static value. For example:
|
|
256
|
+
```
|
|
257
|
+
{controller}{action}
|
|
258
|
+
```
|
|
259
|
+
is invalid because `{controller}` and `{action}` are not separated by a static value.
|
|
260
|
+
Instead, valid routes should use static separators:
|
|
261
|
+
```
|
|
262
|
+
{controller}/{action}
|
|
263
|
+
```
|
|
264
|
+
```
|
|
265
|
+
article/{id}-{title}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Route parameters
|
|
269
|
+
Route parameters must have a name and can also include additional attributes.
|
|
270
|
+
Literal values and path separators (`/`) must match exactly in the URL. Matching is case-insensitive and based
|
|
271
|
+
on the decoded URL representation.
|
|
272
|
+
|
|
273
|
+
#### Optional and Catch-All Parameters
|
|
274
|
+
- **Optional parameters**: Defined with `?`, meaning they are not required. Example: `{id?}`
|
|
275
|
+
- **Catch-all parameters** (`*`): Capture the remaining part of the URL. Example: `blog/{slug*}`
|
|
276
|
+
- Matches any URL starting with `blog/`.
|
|
277
|
+
- The remaining value is assigned to the `slug` parameter.
|
|
278
|
+
- **Required catch-all parameters** (`+`): Like `*`, but at least one segment must match.
|
|
279
|
+
|
|
280
|
+
### Parameter constraints
|
|
281
|
+
Route parameters can have constraints to validate and transform values. Constraints are added using `:` after the parameter name.
|
|
282
|
+
If a constraint requires arguments, they are placed in parentheses.
|
|
283
|
+
|
|
284
|
+
Example:
|
|
285
|
+
```
|
|
286
|
+
blog/{id:int:min(100)}/{article:minlength(10)}
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
- `{id:int:min(100)}` ensures `id` is an integer and at least 100.
|
|
290
|
+
- `{article:minlength(10)}` requires `article` to be at least 10 characters long.
|
|
291
|
+
|
|
292
|
+
Some constraints also transform parameters. For example, `{id:int}` automatically converts `id` to a number.
|
|
293
|
+
|
|
294
|
+
### Default values
|
|
295
|
+
Route parameters can have **default values**, specified similarly to constraints but using `=` or `default`. Example:
|
|
296
|
+
```
|
|
297
|
+
{controller:=(home)}
|
|
298
|
+
```
|
|
299
|
+
is equivalent to:
|
|
300
|
+
```
|
|
301
|
+
{controller:default(home)}
|
|
302
|
+
```
|
|
303
|
+
If no value is provided in the URL, the default is used.
|
|
304
|
+
|
|
305
|
+
### Example route patterns
|
|
306
|
+
|
|
307
|
+
| Route template | URI | Description |
|
|
308
|
+
|------------------------------------------------|-------------------|---------------------------------------------------------------|
|
|
309
|
+
| `hello` | `/hello` | Matches only `/hello`. |
|
|
310
|
+
| `{controller}/{action}/{id?}` | `/product/list` | Matches and sets `controller=product`, `action=list`. |
|
|
311
|
+
| `{controller}/{action}/{id?}` | `/product/list/1` | Matches and sets `controller=product`, `action=list`, `id=1`. |
|
|
312
|
+
| `{controller:=(home)}/{action:=(index)}/{id?}` | `/` | Matches and sets `controller=home`, `action=index`. |
|
|
313
|
+
| `{controller:=(home)}/{action:=(index)}/{id?}` | `/product` | Matches and sets `controller=product`, `action=index`. |
|
|
314
|
+
| `blog/{slug*:=(start/with/new/blog)}` | `/blog` | Matches and sets `slug=[start,with,new,blog]`. |
|
|
315
|
+
|
|
316
|
+
### Route constraints
|
|
317
|
+
|
|
318
|
+
| Constraint | Example | Description |
|
|
319
|
+
|--------------------|-------------------------------|---------------------------------------------------|
|
|
320
|
+
| `int` | `{id:int}` | Matches an integer. |
|
|
321
|
+
| `bool` | `{id:bool}` | Matches `true` or `false` (case-insensitive). |
|
|
322
|
+
| `number` | `{speed:number}` | Matches a valid number. |
|
|
323
|
+
| `alpha` | `{name:alpha}` | Matches alphabetic characters (case-insensitive). |
|
|
324
|
+
| `min(value)` | `{age:min(25)}` | Ensures the value is at least `25`. |
|
|
325
|
+
| `max(value)` | `{age:max(125)}` | Ensures the value is no more than `125`. |
|
|
326
|
+
| `range(min,max)` | `{age:range(25,125)}` | Ensures the value is between `25` and `125`. |
|
|
327
|
+
| `length(value)` | `{file:length(10)}` | Requires exactly `10` characters. |
|
|
328
|
+
| `length(min,max)` | `{file:length(10,20)}` | Requires between `10` and `20` characters. |
|
|
329
|
+
| `minlength(value)` | `{name:minlength(10)}` | Requires at least `10` characters. |
|
|
330
|
+
| `maxlength(value)` | `{name:maxlength(50)}` | Requires no more than `50` characters. |
|
|
331
|
+
| `regex(expr)` | `{id:regex(^\\d{3}-\\d{5}$)}` | Must match a specific regex pattern. |
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
## Source Code
|
|
335
|
+
You can find the source code for this plugin on GitHub:
|
|
336
|
+
|
|
337
|
+
https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/router
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
## Related packages
|
|
341
|
+
This package is part of **[AlpineGear](https://github.com/rameel/ramstack.alpinegear.js)** —
|
|
342
|
+
a collection of utilities and directives for [Alpine.js](https://alpinejs.dev).
|
|
343
|
+
|
|
344
|
+
You can find the full list of related packages and their documentation here:
|
|
345
|
+
https://github.com/rameel/ramstack.alpinegear.js
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
## Contributions
|
|
349
|
+
Bug reports and contributions are welcome.
|
|
350
|
+
|
|
351
|
+
## License
|
|
352
|
+
This package is released as open source under the **MIT License**.
|
|
353
|
+
|
|
354
|
+
See the [LICENSE](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE) file for more details.
|