From 46094456fed647a26d57af1a52cda7da09296e23 Mon Sep 17 00:00:00 2001 From: Krutie Patel Date: Thu, 25 Aug 2022 19:46:40 +1000 Subject: [PATCH 1/8] docs(api): add definePageMeta util --- .../content/3.api/3.utils/define-page-meta.md | 128 +++++++++++++++++- 1 file changed, 126 insertions(+), 2 deletions(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index f0649cc2b42..89af858e145 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -1,7 +1,131 @@ # `definePageMeta` -::ReadMore{link="/guide/features/routing"} +`definePageMeta` is a compiler macro that you can use to set metadata for each **page** component located in the `pages/` directory. This way you can set custom metadata for each static or dynamic route of your Nuxt application. + +::ReadMore{link="/guide/directory-structure/pages"} :: -::NeedContribution +## Usage + +```vue [pages/some-page.vue] + +``` + +> `definePageMeta` works in both ` +``` + +## Examples + +### Basic usage + +The example below shows how `key` can be a function that returns a value, while `pageType` is a custom property and `keepAlive` property makes sure that the `modal` component is not cached when you change pages. + +```vue [pages/some-page.vue] + +``` + +### Define m**iddleware** + +The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `middleware/` directory. + +```vue [pages/some-page.vue] + +``` + +### Define layout + +You can set the `layout` as a `string` value that matches the layout file located in `layouts/` directory. You can disable the layout by setting the `layout` to `false`. + +```vue [pages/some-page.vue] + +``` + +::ReadMore{link="/guide/features/routing"} :: From 432d032f31ed152c7a11a2a2568357b8f561ff1b Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Thu, 25 Aug 2022 11:40:25 +0100 Subject: [PATCH 2/8] docs: small tweaks --- .../content/3.api/3.utils/define-page-meta.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index 89af858e145..bedf395ccdd 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -34,7 +34,7 @@ Set a static or dynamic name of the layout for each route. This can be set to `f - **middleware**: `string | function` -Define anonymous or named middleware directly within `definePageMeta` under `middleware` key. Learn more about route middleware. +Define anonymous or named middleware directly within `definePageMeta` under `middleware` key. Learn more about [route middleware](/docs/directory-structure/middleware/). - **layoutTransition**: `boolean | TransitionProps` @@ -46,14 +46,14 @@ Set name of the transition to apply for current layout. You can also set this va Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition. - **alias**: `string | string[]` -Set alias to access the same page from different paths. Learn more about alias [alias](https://router.vuejs.org/guide/essentials/redirect-and-alias.html#alias) + +Set alias to access the same page from different paths. Learn more about [alias](https://router.vuejs.org/guide/essentials/redirect-and-alias.html#alias) - **keepalive**: `boolean | KeepAliveProps` -Set to `true` when you want to preserve page state across route changes. -(Learn more about [KeepAlive](https://vuejs.org/api/built-in-components.html#keepalive)) +Set to `true` when you want to preserve page state across route changes. Learn more about [KeepAlive](https://vuejs.org/api/built-in-components.html#keepalive). -Apart from above values, you can set **custom** values in `definePageMeta` as well depending on your use-case. This data can then be accessed throughout your Nuxt application using `route.meta` object as shown below. +Apart from the above values, you can also set **custom** values in `definePageMeta` as well, depending on your use-case. This data can then be accessed throughout your Nuxt application using the `route.meta` object as shown below. ```vue [pages/some-page.vue] ``` -### Define m**iddleware** +### Define middleware The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `middleware/` directory. @@ -104,8 +104,8 @@ The example below shows how the middleware can be defined using a `function` dir ], // string - // middleware: ["auth"] - // or middleware: "auth" + // middleware: ['auth'] + // or middleware: 'auth' }) ``` @@ -117,12 +117,12 @@ You can set the `layout` as a `string` value that matches the layout file locate ```vue [pages/some-page.vue] ``` From c62f8c99394ef5683745be51b1642da1b6445e25 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Thu, 25 Aug 2022 11:41:01 +0100 Subject: [PATCH 3/8] docs: few more tweaks --- docs/content/3.api/3.utils/define-page-meta.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index bedf395ccdd..8d448e4dd75 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -22,6 +22,7 @@ You can set following properties through `definePageMeta` . - **title** - `string` + Set custom title for each route of your application - **key** - `string | function` @@ -79,7 +80,7 @@ The example below shows how `key` can be a function that returns a value, while }, // custom property: pageType - pageType: "Checkout" + pageType: 'Checkout' }) ``` From 1cb86e3b90317f16d15816d5f3b1235791e564a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Thu, 25 Aug 2022 22:30:48 +0200 Subject: [PATCH 4/8] Update define-page-meta.md --- .../content/3.api/3.utils/define-page-meta.md | 159 ++++++++++-------- 1 file changed, 89 insertions(+), 70 deletions(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index 8d448e4dd75..13a4b531a31 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -1,11 +1,6 @@ # `definePageMeta` -`definePageMeta` is a compiler macro that you can use to set metadata for each **page** component located in the `pages/` directory. This way you can set custom metadata for each static or dynamic route of your Nuxt application. - -::ReadMore{link="/guide/directory-structure/pages"} -:: - -## Usage +`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the `pages/` directory (unless [set otherwise](https://v3.nuxtjs.org/api/configuration/nuxt.config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application. ```vue [pages/some-page.vue] ``` -> `definePageMeta` works in both ` +``` +definePageMeta(meta: PageMeta) => void + +interface PageMeta { + pageTransition?: boolean | TransitionProps; + layoutTransition?: boolean | TransitionProps; + key?: false | string | ((route: RouteLocationNormalizedLoaded) => string); + keepalive?: boolean | KeepAliveProps; + layout?: false | LayoutKey | Ref | ComputedRef + middleware?: MiddlewareKey | NavigationGuard | Array + [key: string]: any; +} ``` +## Parameters + +### `meta` + +- **Type**: `PageMeta` + + An object accepting the following page metadata: + + #### `pageTransition` + + - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) + + Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition. + + #### `layoutTransition` + + - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) + + Set name of the transition to apply for current layout. You can also set this value to `false` to disable the layout transition. + + #### `key` + + - **Type**: `false` | `string` | `((route: RouteLocationNormalizedLoaded) => string)` + + Set `key` value when you need more control over when the `` component is re-rendered. + + #### `keepalive` + + - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) + + Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) for a fine-grained control. + + #### `layout` + + - **Type**: `false` | `LayoutKey` | `Ref` | `ComputedRef` + + Set a static or dynamic name of the layout for each route. This can be set to `false` in case the default layout needs to be disabled. + + #### `middleware` + + - **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/NavigationGuard.html#navigationguard) | `Array` + + Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/directory-structure/middleware). + + #### `[key: string]` + + - **Type**: `any` + + Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/guide/directory-structure/pages/#typing-custom-metadata). + ## Examples -### Basic usage +### Basic Usage -The example below shows how `key` can be a function that returns a value, while `pageType` is a custom property and `keepalive` property makes sure that the `modal` component is not cached when you change pages. +The example below demonstrates: +- how `key` can be a function that returns a value; +- how `keepalive` property makes sure that the `` component is not cached when switching between multiple components; +- adding `pageType` as a custom property: ```vue [pages/some-page.vue] ``` -### Define middleware +### Defining Middleware -The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `middleware/` directory. +The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `middleware/` directory: ```vue [pages/some-page.vue] ``` -### Define layout +### Defining Layout -You can set the `layout` as a `string` value that matches the layout file located in `layouts/` directory. You can disable the layout by setting the `layout` to `false`. +You can define the layout that matches the layout's file name located (by default) in the `layouts/` directory. You can also disable the layout by setting the `layout` to `false`: ```vue [pages/some-page.vue] ``` From 494a7f183e6390d7ff78da990724f3cfb0a7c57e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Thu, 25 Aug 2022 22:41:22 +0200 Subject: [PATCH 5/8] Update define-page-meta.md --- .../content/3.api/3.utils/define-page-meta.md | 53 ++++++++++--------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index 13a4b531a31..b29d4dd8697 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -15,7 +15,7 @@ ## Type -``` +```ts definePageMeta(meta: PageMeta) => void interface PageMeta { @@ -37,46 +37,46 @@ interface PageMeta { An object accepting the following page metadata: - #### `pageTransition` + **`pageTransition`** - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition. - - #### `layoutTransition` - + + **`layoutTransition`** + - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) - + Set name of the transition to apply for current layout. You can also set this value to `false` to disable the layout transition. - - #### `key` - + + **`key`** + - **Type**: `false` | `string` | `((route: RouteLocationNormalizedLoaded) => string)` - + Set `key` value when you need more control over when the `` component is re-rendered. - - #### `keepalive` - + + **`keepalive`** + - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) - + Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) for a fine-grained control. - - #### `layout` - + + **`layout`** + - **Type**: `false` | `LayoutKey` | `Ref` | `ComputedRef` - + Set a static or dynamic name of the layout for each route. This can be set to `false` in case the default layout needs to be disabled. - - #### `middleware` - + + **`middleware`** + - **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/NavigationGuard.html#navigationguard) | `Array` - + Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/directory-structure/middleware). - - #### `[key: string]` - + + **`[key: string]`** + - **Type**: `any` - + Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/guide/directory-structure/pages/#typing-custom-metadata). ## Examples @@ -84,6 +84,7 @@ interface PageMeta { ### Basic Usage The example below demonstrates: + - how `key` can be a function that returns a value; - how `keepalive` property makes sure that the `` component is not cached when switching between multiple components; - adding `pageType` as a custom property: From 4ac93aef8888d009eca5af538f38d2d7c26e5e53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Thu, 25 Aug 2022 22:54:25 +0200 Subject: [PATCH 6/8] Update define-page-meta.md --- docs/content/3.api/3.utils/define-page-meta.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index b29d4dd8697..80e6daa54f4 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -36,7 +36,8 @@ interface PageMeta { - **Type**: `PageMeta` An object accepting the following page metadata: - +\ +\ **`pageTransition`** - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) From f1fced9375bc6045608a07410d450e151d568eba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Thu, 25 Aug 2022 23:02:28 +0200 Subject: [PATCH 7/8] Update define-page-meta.md --- docs/content/3.api/3.utils/define-page-meta.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index 80e6daa54f4..cc8bf513ce8 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -36,8 +36,7 @@ interface PageMeta { - **Type**: `PageMeta` An object accepting the following page metadata: -\ -\ + **`pageTransition`** - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) From 490309911186fd703163bd6246640ea8d1e89004 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damian=20G=C5=82owala?= <48835293+DamianGlowala@users.noreply.github.com> Date: Fri, 26 Aug 2022 09:22:45 +0200 Subject: [PATCH 8/8] Update define-page-meta.md --- docs/content/3.api/3.utils/define-page-meta.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/content/3.api/3.utils/define-page-meta.md b/docs/content/3.api/3.utils/define-page-meta.md index cc8bf513ce8..a2606195022 100644 --- a/docs/content/3.api/3.utils/define-page-meta.md +++ b/docs/content/3.api/3.utils/define-page-meta.md @@ -19,13 +19,13 @@ definePageMeta(meta: PageMeta) => void interface PageMeta { - pageTransition?: boolean | TransitionProps; - layoutTransition?: boolean | TransitionProps; - key?: false | string | ((route: RouteLocationNormalizedLoaded) => string); - keepalive?: boolean | KeepAliveProps; + pageTransition?: boolean | TransitionProps + layoutTransition?: boolean | TransitionProps + key?: false | string | ((route: RouteLocationNormalizedLoaded) => string) + keepalive?: boolean | KeepAliveProps layout?: false | LayoutKey | Ref | ComputedRef middleware?: MiddlewareKey | NavigationGuard | Array - [key: string]: any; + [key: string]: any } ``` @@ -112,7 +112,7 @@ The example below shows how the middleware can be defined using a `function` dir definePageMeta({ // define middleware as a function middleware: [ - async function (to, from) { + function (to, from) { const auth = useState('auth') if (!auth.value.authenticated) {