Skip to Content
Vuesho

Views

Add pages from a plugin, rendered by a Vue component of its theme.

A view is a page that a plugin adds outside your content. The view of the plugin returns the props of the page, and a component of a theme renders it. A page of your own site is a custom page instead, a .vue file with its props in definePage().

A plugin adds views with createView() in its routes hook. This one adds a /releases page that lists the pages of the site:

releases-plugin.ts
import type { AppShape, Plugin } from "vuesho/config";

export interface ReleasesProps {
  releases: { title: string; url: string }[];
}

export function releasesPlugin<C extends AppShape>(): Plugin<
  C,
  { views: { releases: ReleasesProps } }
> {
  return {
    name: "acme:releases",
    routes({ createView }) {
      createView({
        path: "/releases",
        data: { title: "Releases" },
        view: ({ lang }) => ({
          type: "releases",
          props: {
            releases: this.getPages(lang).map((page) => ({ title: page.url, url: page.url })),
          },
        }),
      });
    },
  };
}

view receives the params of the URL and its lang, and returns the type of the view with its props. this is the context of the site. The plugin declares the props of its views in its types, so createView() takes only those types with their props, and the site has them in its types. C is the site the plugin is added to, so the hooks receive its pages and languages.

Components

The server can't send a component, so the component of a view is in a theme, by the name of the view. A plugin package ships a theme with the components of its views, see Plugins with UI:

theme.ts
import type { PluginTheme } from "vuesho/client";
import type { ReleasesProps } from "./releases-plugin";

export default {
  name: "releases",
  views: { releases: () => import("./Releases.vue") },
} satisfies PluginTheme<{ views: { releases: ReleasesProps } }>;

The component receives the page as its page prop, with the props of the view in page.props, and renders the whole page with its own layout. The home layout has the navbar of the site:

Releases.vue
<script setup lang="ts">
import { Link, type ViewPageOf } from "vuesho/client";
import HomeLayout from "vuesho/layouts/home";
import type { ReleasesProps } from "./releases-plugin";

defineProps<{ page: ViewPageOf<{ releases: ReleasesProps }, "releases"> }>();
</script>

<template>
  <HomeLayout>
    <div class="mx-auto w-full max-w-(--fd-layout-width) px-4 py-12">
      <h1 class="mb-6 text-2xl font-semibold">{{ page.pageData.title }}</h1>
      <ul class="flex flex-col gap-2">
        <li v-for="release in page.props.releases" :key="release.url">
          <Link :href="release.url" class="block rounded-lg border p-4 hover:bg-fd-accent">
            {{ release.title }}
          </Link>
        </li>
      </ul>
    </div>
  </HomeLayout>
</template>

The site adds the theme of the plugin to extends, and can give a view a component of its own in views:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import releasesTheme from "acme-releases/theme";

export default defineTheme({ extends: [defaultTheme, releasesTheme] });

The props are sent to the browser, so every value must be serializable, like strings, numbers, lists and plain objects. ViewPageOf has the props as JSON: a Date is a string there. A view without a component fails to render, with an error that names it.

A URL has one page, as for custom pages. A view at the URL of a content page, or two views at one path, fail when the site starts, naming both. A view with params answers the URLs that have no page of their own: /guide/[name] renders /guide/other, while /guide/install stays the page of content/guide/install.md. A custom page at the path of a view replaces it, so a site can change a page of a plugin.

Params

A view path takes params like an API route, and the most specific view at a URL renders it. view receives their values in params, and returns nothing for a page that doesn't exist, which shows the not found page:

const posts: Record<string, string> = { hello: "Hello", bye: "Bye" };

createView({
  path: "/blog/[slug]",
  staticPaths: Object.keys(posts),
  view: ({ params: { slug } }) =>
    slug && posts[slug] ? { type: "post", props: { title: posts[slug] } } : undefined,
});

Render Mode

A view without params, or with staticPaths, is generated at build time, like the pages of a static source, and the sitemap lists its pages. A view with params generates one page per entry of staticPaths, an object of the values by name with several params, and renders only those pages: a view that returns nothing for one of them fails the build.

A view with params and without staticPaths renders on demand at every path it matches, and so does a view with render: "dynamic". Both need a server deployment. A view with params and render: "static" needs staticPaths, or the site fails to start, naming the view and its plugin. A view that reads your content follows its render mode with render: this.getContentRender(), so it renders on demand when a page it reads does. A route rule with prerender: false renders a page of a view on demand too.

A view that renders on demand receives the request of the page in the env of view and data, like its headers and cookies. A page generated at build time has none, on the dev server too.

Page Data

data of a view sets the data of its pages, like the title and description of their <head>. The component of the view reads it in page.pageData.

For data that differs per page, like the title of each post, data is a function. It receives the params, lang and request of the page, and returns undefined for a page that doesn't exist:

createView({
  path: "/blog/[slug]",
  staticPaths: Object.keys(posts),
  data: ({ params: { slug } }) =>
    slug && posts[slug] ? { title: posts[slug], description: "A post of the blog" } : undefined,
  view: ({ params: { slug } }) =>
    slug && posts[slug] ? { type: "post", props: { title: posts[slug] } } : undefined,
});

Languages

On a site with languages, a view exists in every language, with the language prefix before its path: /releases is also /cn/releases. view receives the language in lang, to list the pages of that language with this.getPages(lang).

To add a view in one language only, pass lang to createView():

createView({
  path: "/newsletter",
  lang: "en",
  view: () => ({ type: "newsletter", props: {} }),
});