@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-admin-ui/using-other-frameworks/index.md

@@ -0,0 +1,205 @@
+---
+title: 'Using Other Frameworks'
+weight: 1
+---
+
+From version 2.1.0, Admin UI extensions can be written in either Angular or React. Prior to v2.1.0, only Angular was natively supported. 
+
+It is, however, possible to extend the Admin UI using other frameworks such as Vue, Svelte, Solid etc. Note that the extension experience is much more limited than with Angular or React, but depending on your needs it may be sufficient.
+
+:::info
+For working examples of a UI extensions built with **Vue**, see the [real-world-vendure ui extensions](https://github.com/vendurehq/real-world-vendure/tree/master/src/ui-extensions)
+:::
+
+There is still a small amount of Angular "glue code" needed to let the compiler know how to integrate your extension, so let's take a look at how this is done.
+
+## 1. Install `@vendure/ui-devkit`
+
+To create UI extensions, you'll need to install the `@vendure/ui-devkit` package. This package contains a compiler for building your customized version of the Admin UI, as well as the Angular dependencies you'll need to create your extensions.
+
+```bash
+yarn add @vendure/ui-devkit
+
+# or
+
+npm install @vendure/ui-devkit
+```
+
+## 2. Create the folder structure
+
+In this example, we will work with the following folder structure, and use Create React App our example.
+
+```text
+src
+└─plugins
+  └─ my-plugin
+    └─ ui
+      ├─ routes.ts
+      └─ vue-app
+        └─ (directory created by `vue create`, for example)
+```
+
+## 3. Create an extension module
+
+Here's the Angular code needed to tell the compiler where to find your extension:
+
+```ts title="src/plugins/my-plugin/ui/routes.ts"
+import { hostExternalFrame } from '@vendure/admin-ui/core';
+
+export default [
+    hostExternalFrame({
+        path: '',
+
+        // You can also use parameters which allow the app
+        // to have dynamic routing, e.g.
+        // path: ':slug'
+        // Then you can use the getActivatedRoute() function from the
+        // UiDevkitClient in order to access the value of the "slug"
+        // parameter.
+
+        breadcrumbLabel: 'Vue App',
+        // This is the URL to the compiled React app index.
+        // The next step will explain the "assets/react-app" path.
+        extensionUrl: './assets/vue-app/index.html',
+        openInNewTab: false,
+    })
+];
+```
+
+## 4. Define the AdminUiExtension config
+
+Next we will define an [AdminUiExtension](/reference/admin-ui-api/ui-devkit/admin-ui-extension/) object which is passed to the `compileUiExtensions()` function in your Vendure config:
+
+```ts title="src/vendure-config.ts"
+import path from 'path';
+import { VendureConfig } from '@vendure/core';
+import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        AdminUiPlugin.init({
+            route: 'admin',
+            port: 3002,
+            app: compileUiExtensions({
+                outputPath: path.join(__dirname, '../admin-ui'),
+                extensions: [{
+                    // Points to the path containing our Angular "glue code" module
+                    extensionPath: path.join(__dirname, 'plugins/my-plugin/ui'),
+                    routes: [{ route: 'vue-ui', filePath: 'routes.ts' }],
+                    staticAssets: [
+                        // This is where we tell the compiler to copy the compiled Vue app
+                        // artifacts over to the Admin UI's `/static` directory. In this case we
+                        // also rename "build" to "vue-app". This is why the `extensionUrl`
+                        // in the module config points to './assets/vue-app/index.html'.
+                        {path: path.join(__dirname, 'plugins/my-plugin/ui/vue-app/dist'), rename: 'vue-app'},
+                    ],
+                }],
+                devMode: true,
+            }),
+        }),
+    ]
+};
+```
+
+## 5. Build your extension
+
+To ensure things are working we can now build our Vue app by running `yarn build` in the `vue-app` directory. This will build and output the app artifacts to the `vue-app/build` directory - the one we pointed to in the `staticAssets` array above.
+
+Once build, we can start the Vendure server.
+
+The `compileUiExtensions()` function returns a `compile()` function which will be invoked by the AdminUiPlugin upon server bootstrap. During this compilation process, a new directory will be generated at `/admin-ui` (as specified by the `outputPath` option) which will contains the un-compiled sources of your new Admin UI app.
+
+Next, these source files will be run through the Angular compiler, the output of which will be visible in the console.
+
+Now go to the Admin UI app in your browser and log in. You should now be able to manually enter the URL `http://localhost:3000/admin/extensions/vue-ui` and you should see the Vue app rendered in the Admin UI.
+
+## Integrate with the Admin UI
+
+### Styling
+The `@vendure/admin-ui` package (which will be installed alongside the ui-devkit) provides a stylesheet to allow your extension to fit visually with the rest of the Admin UI.
+
+If you have a build step, you can import it into your app like this:
+
+```ts
+import '@vendure/admin-ui/static/theme.min.css';
+```
+
+If your extension does not have a build step, you can still include the theme stylesheet as a local resource:
+
+```HTML
+<!-- src/ui-extension/plain-js-app/index.html -->
+<head>
+  <link rel="stylesheet" href="../../theme.min.css" />
+</head>
+```
+
+### UiDevkitClient
+
+The `@vendure/ui-devkit` package provides a number of helper methods which allow your extension to seamlessly interact with the underlying Admin UI infrastructure, collectively known as the [UiDevkitClient](/reference/admin-ui-api/ui-devkit/ui-devkit-client/). The client allows your extension to:
+
+* Make GraphQL queries & mutations, without the need for your own HTTP or GraphQL client, with full integration with the Admin UI client-side GraphQL cache.
+* Display toast notifications.
+
+#### setTargetOrigin
+
+The UiDevkitClient uses the browser's [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to communicate between the Admin UI app and your extension. For security reasons this communication channel is restricted to a specific domain (where your extension app will be running from). To configure this, use the [setTargetOrigin](/reference/admin-ui-api/ui-devkit/ui-devkit-client/#settargetorigin) function:
+
+```ts
+import { setTargetOrigin } from '@vendure/ui-devkit';
+
+setTargetOrigin('http://my-domain.com');
+
+```
+
+If this is mis-configured you will see an error along the lines of "Failed to execute 'postMessage' on 'DOMWindow'".
+
+For apps with a build step, you can use these functions like this:
+
+```ts
+import { graphQlMutation, notify } from '@vendure/ui-devkit';
+
+// somewhere in your component
+const disableProduct = (id: string) => {
+  graphQlMutation(`
+    mutation DisableProduct($id: ID!) {
+      updateProduct(input: { id: $id, enabled: false }) {
+        id
+        enabled
+      }
+    }`, { id }).then(result => {
+     notify({
+       message: 'Updated Product',
+     });
+  })
+}
+```
+
+If your extension does not have a build step, you can still include the UiDevkitClient as a local resource, which will expose a `VendureUiClient` global object:
+
+```html
+<!-- src/ui-extension/plain-js-app/index.html -->
+<head>
+  <script src="../devkit/ui-devkit.js"></script>
+</head>
+<script>
+  const disableProduct = id => {
+    VendureUiClient.graphQlMutation(`
+      mutation DisableProduct($id: ID!) {
+        updateProduct(input: { id: $id, enabled: false }) {
+          id
+          enabled
+        }
+      }`, { id }).then(result => {
+       VendureUiClient.notify({
+         message: 'Updated Product',
+       });
+    })
+  }
+</script>
+```
+
+## Next Steps
+
+Now you have created your extension, you need a way for your admin to access it. See [Adding Navigation Items](/guides/extending-the-admin-ui/nav-menu/)

package/docs/guides/extending-the-dashboard/alerts/index.md

@@ -0,0 +1,89 @@
+---
+title: 'Alerts'
+---
+
+Alerts allow you to display important information to the administrators who use the Dashboard. They can be used to notify users about 
+pending tasks, system status, or any conditions that require attention.
+
+:::info
+This API is further documented in the [DashboardAlertDefinition API reference](/reference/dashboard/extensions-api/alerts)
+:::
+
+## Creating a Custom Alert
+
+To create a custom alert, you need to define a `DashboardAlertDefinition` object and register it with the Dashboard.
+
+![Alert example](./alert.webp)
+
+### Example: Pending Search Index Updates Alert
+
+Let's take the built-in "pending search index updates" as an example, since it demonstrates many features you'll also use
+in your own custom alerts.
+
+```tsx title="pending-updates-alert.tsx"
+import { graphql } from '@/gql';
+import { api, DashboardAlertDefinition } from '@vendure/dashboard';
+import { toast } from 'sonner';
+
+const pendingSearchIndexUpdatesDocument = graphql(`
+    query GetPendingSearchIndexUpdates {
+        pendingSearchIndexUpdates
+    }
+`);
+
+export const runPendingSearchIndexUpdatesDocument = graphql(`
+    mutation RunPendingSearchIndexUpdates {
+        runPendingSearchIndexUpdates {
+            success
+        }
+    }
+`);
+
+export const pendingSearchIndexUpdatesAlert: DashboardAlertDefinition<number> = {
+    id: 'pending-search-index-updates',
+    // The `check` function is called periodically based on the `recheckInterval`.
+    // It will typically do something like checking an API for data. The result
+    // of this function is then used to decide whether an alert needs to be
+    // displayed.
+    check: async () => {
+        const data = await api.query(pendingSearchIndexUpdatesDocument);
+        return data.pendingSearchIndexUpdates;
+    },
+    recheckInterval: 10_000,
+    // Determines whether to display the alert. In our case, we want to display
+    // and alert if there are one or more pendingSearchIndexUpdates
+    shouldShow: data => data > 0,
+    title: data => `${data} pending search index updates`,
+    description: 'Runs all pending search index updates',
+    // The severity (info, warning, error) can be a static string, or can
+    // be dynamically set based on the data returned by the `check` function.
+    severity: data => (data < 10 ? 'info' : 'warning'),
+    // Actions allow the administrator to take some action based on the
+    // alert.
+    actions: [
+        {
+            label: `Run pending updates`,
+            onClick: async ({ dismiss }) => {
+                await api.mutate(runPendingSearchIndexUpdatesDocument, {});
+                toast.success('Running pending search index updates');
+                // Calling this function will immediately dismiss
+                // the alert.
+                dismiss();
+            },
+        },
+    ],
+};
+```
+
+This alert is the registered in your dashboard extensions extry point:
+
+```ts
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { pendingSearchIndexUpdatesAlert } from './pending-updates-alert';
+
+defineDashboardExtension({
+    alerts: [pendingSearchIndexUpdatesAlert],
+});
+```
+

package/docs/guides/extending-the-dashboard/creating-pages/detail-pages.md

@@ -0,0 +1,316 @@
+---
+title: 'Creating Detail Pages'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Setup
+
+:::info
+This guide assumes you have a `CmsPlugin` with an `Article` entity, as covered in the [Extending the Dashboard: Plugin Setup](/guides/extending-the-dashboard/extending-overview/#plugin-setup) guide.
+:::
+
+Detail pages can be created for any entity which has been exposed via the Admin API. Following the
+above setup of the `CmsPlugin` will result in the following additions to your API schema:
+
+```graphql
+type Article implements Node {
+    id: ID!
+    createdAt: DateTime!
+    updatedAt: DateTime!
+    slug: String!
+    title: String!
+    body: String!
+    isPublished: Boolean!
+}
+
+type Query {
+    # ...
+    article(id: ID!): Article
+}
+
+type Mutation {
+    # ...
+    createArticle(input: CreateArticleInput!): Article!
+    updateArticle(input: UpdateArticleInput!): Article!
+    deleteArticle(id: ID!): DeletionResponse!
+}
+```
+
+## Simple Detail Pages
+
+Now let's create a detail page so we can start adding articles.
+
+We'll begin with the simplest approach, where the form will be auto-generated for us based on the GraphQL schema
+using the [DetailPage](/reference/dashboard/detail-views/detail-page) component.
+This is useful for quickly getting started, but you can also to customize the form later on.
+
+Create a new file called `article-detail.tsx` in the `./src/plugins/cms/dashboard` directory:
+
+```tsx title="src/plugins/cms/dashboard/article-detail.tsx"
+import { DashboardRouteDefinition, DetailPage, detailPageRouteLoader } from '@vendure/dashboard';
+import { graphql } from '@/gql';
+
+const articleDetailDocument = graphql(`
+    query GetArticleDetail($id: ID!) {
+        article(id: $id) {
+            id
+            createdAt
+            updatedAt
+            isPublished
+            title
+            slug
+            body
+            customFields
+        }
+    }
+`);
+
+const createArticleDocument = graphql(`
+    mutation CreateArticle($input: CreateArticleInput!) {
+        createArticle(input: $input) {
+            id
+        }
+    }
+`);
+
+const updateArticleDocument = graphql(`
+    mutation UpdateArticle($input: UpdateArticleInput!) {
+        updateArticle(input: $input) {
+            id
+        }
+    }
+`);
+
+export const articleDetail: DashboardRouteDefinition = {
+    path: '/articles/$id',
+    loader: detailPageRouteLoader({
+        queryDocument: articleDetailDocument,
+        breadcrumb: (isNew, entity) => [
+            { path: '/articles', label: 'Articles' },
+            isNew ? 'New article' : entity?.title,
+        ],
+    }),
+    component: route => {
+        return (
+            <DetailPage
+                pageId="article-detail"
+                queryDocument={articleDetailDocument}
+                createDocument={createArticleDocument}
+                updateDocument={updateArticleDocument}
+                route={route}
+                title={article => article?.title ?? 'New article'}
+                setValuesForUpdate={article => {
+                    return {
+                        id: article?.id ?? '',
+                        isPublished: article?.isPublished ?? false,
+                        title: article?.title ?? '',
+                        slug: article?.slug ?? '',
+                        body: article?.body ?? '',
+                    };
+                }}
+            />
+        );
+    },
+};
+```
+
+Now we can register this route in our `index.tsx` file:
+
+```tsx title="src/plugins/cms/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { articleList } from './article-list';
+// highlight-next-line
+import { articleDetail } from './article-detail';
+
+defineDashboardExtension({
+    routes: [
+        articleList,
+        // highlight-next-line
+        articleDetail,
+    ],
+});
+```
+
+You should now be able to click on the "New article" button in the list view, and see the detail page:
+![Detail Page](../getting-started/detail-view.webp)
+
+Congratulations! You can now add, edit and delete articles in the dashboard.
+
+![List view with entries](../getting-started/list-view-full.webp)
+
+## Customizing the detail page
+
+The auto-generated [DetailPage](/reference/dashboard/detail-views/detail-page) is a great way to get started and quickly be able
+to interact with your entities. But let's now see how we can fully customize the layout and form fields.
+
+```tsx title="src/plugins/cms/dashboard/article-detail.tsx"
+import {
+    DashboardRouteDefinition,
+    detailPageRouteLoader,
+    useDetailPage,
+    Page,
+    PageTitle,
+    PageActionBar,
+    PageActionBarRight,
+    PermissionGuard,
+    Button,
+    PageLayout,
+    PageBlock,
+    FormFieldWrapper,
+    DetailFormGrid,
+    Switch,
+    Input,
+    RichTextInput,
+    CustomFieldsPageBlock,
+} from '@vendure/dashboard';
+import { AnyRoute, useNavigate } from '@tanstack/react-router';
+import { toast } from 'sonner';
+
+import { graphql } from '@/gql';
+
+const articleDetailDocument = graphql(`
+    query GetArticleDetail($id: ID!) {
+        article(id: $id) {
+            id
+            createdAt
+            updatedAt
+            isPublished
+            title
+            slug
+            body
+            customFields
+        }
+    }
+`);
+
+const createArticleDocument = graphql(`
+    mutation CreateArticle($input: CreateArticleInput!) {
+        createArticle(input: $input) {
+            id
+        }
+    }
+`);
+
+const updateArticleDocument = graphql(`
+    mutation UpdateArticle($input: UpdateArticleInput!) {
+        updateArticle(input: $input) {
+            id
+        }
+    }
+`);
+
+export const articleDetail: DashboardRouteDefinition = {
+    path: '/articles/$id',
+    loader: detailPageRouteLoader({
+        queryDocument: articleDetailDocument,
+        breadcrumb: (isNew, entity) => [
+            { path: '/articles', label: 'Articles' },
+            isNew ? 'New article' : entity?.title,
+        ],
+    }),
+    component: route => {
+        return <ArticleDetailPage route={route} />;
+    },
+};
+
+function ArticleDetailPage({ route }: { route: AnyRoute }) {
+    const params = route.useParams();
+    const navigate = useNavigate();
+    const creatingNewEntity = params.id === 'new';
+
+    const { form, submitHandler, entity, isPending, resetForm } = useDetailPage({
+        queryDocument: articleDetailDocument,
+        createDocument: createArticleDocument,
+        updateDocument: updateArticleDocument,
+        setValuesForUpdate: article => {
+            return {
+                id: article?.id ?? '',
+                isPublished: article?.isPublished ?? false,
+                title: article?.title ?? '',
+                slug: article?.slug ?? '',
+                body: article?.body ?? '',
+            };
+        },
+        params: { id: params.id },
+        onSuccess: async data => {
+            toast('Successfully updated article');
+            resetForm();
+            if (creatingNewEntity) {
+                await navigate({ to: `../$id`, params: { id: data.id } });
+            }
+        },
+        onError: err => {
+            toast('Failed to update article', {
+                description: err instanceof Error ? err.message : 'Unknown error',
+            });
+        },
+    });
+
+    return (
+        <Page pageId="article-detail" form={form} submitHandler={submitHandler}>
+            <PageTitle>{creatingNewEntity ? 'New article' : (entity?.title ?? '')}</PageTitle>
+            <PageActionBar>
+                <PageActionBarRight>
+                    <PermissionGuard requires={['UpdateProduct', 'UpdateCatalog']}>
+                        <Button
+                            type="submit"
+                            disabled={!form.formState.isDirty || !form.formState.isValid || isPending}
+                        >
+                            Update
+                        </Button>
+                    </PermissionGuard>
+                </PageActionBarRight>
+            </PageActionBar>
+            <PageLayout>
+                <PageBlock column="side" blockId="publish-status">
+                    <FormFieldWrapper
+                        control={form.control}
+                        name="isPublished"
+                        label="Is Published"
+                        render={({ field }) => (
+                            <Switch checked={field.value} onCheckedChange={field.onChange} />
+                        )}
+                    />
+                </PageBlock>
+                <PageBlock column="main" blockId="main-form">
+                    <DetailFormGrid>
+                        <FormFieldWrapper
+                            control={form.control}
+                            name="title"
+                            label="Title"
+                            render={({ field }) => <Input {...field} />}
+                        />
+                        <FormFieldWrapper
+                            control={form.control}
+                            name="slug"
+                            label="Slug"
+                            render={({ field }) => <Input {...field} />}
+                        />
+                    </DetailFormGrid>
+                    <FormFieldWrapper
+                        control={form.control}
+                        name="body"
+                        label="Content"
+                        render={({ field }) => (
+                            <RichTextInput value={field.value ?? ''} onChange={field.onChange} />
+                        )}
+                    />
+                </PageBlock>
+                <CustomFieldsPageBlock column="main" entityType="Article" control={form.control} />
+            </PageLayout>
+        </Page>
+    );
+}
+```
+
+In the above example, we have:
+
+- Used the [Page](/reference/dashboard/page-layout/page), [PageTitle](/reference/dashboard/page-layout/page-title),
+  [PageActionBar](/reference/dashboard/page-layout/page-action-bar) and [PageLayout](/reference/dashboard/page-layout) components to create a layout for our page.
+- Used [PageBlock](/reference/dashboard/page-layout/page-block) components to structure the page into blocks.
+- Used [FormFieldWrapper](/reference/dashboard/form-components/form-field-wrapper) around form components for consistent styling and
+  layout of inputs.
+- Used custom form components (such as the [RichTextInput](/reference/dashboard/form-components/rich-text-input)) to better represent the data.