@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-admin-ui/creating-detail-views/index.md

@@ -0,0 +1,332 @@
+---
+title: 'Creating Detail Views'
+---
+
+# Creating Detail Views
+
+The two most common type of components you'll be creating in your UI extensions are list components and detail components.
+
+In Vendure, we have standardized the way you write these components so that your ui extensions can be made to fit seamlessly into the rest of the app.
+
+:::note
+The specific pattern described here is for Angular-based components. It is also possible to create detail views using React components, but 
+in that case you won't be able to use the built-in Angular-specific components.
+:::
+
+## Example: Creating a Product Detail View
+
+Let's say you have a plugin which adds a new entity to the database called `ProductReview`. You have already created a [list view](/guides/extending-the-admin-ui/creating-list-views/), and
+now you need a detail view which can be used to view and edit individual reviews.
+
+### Extend the TypedBaseDetailComponent class
+
+The detail component itself is an Angular component which extends the [BaseDetailComponent](/reference/admin-ui-api/list-detail-views/base-detail-component/) or [TypedBaseDetailComponent](/reference/admin-ui-api/list-detail-views/typed-base-detail-component) class.
+
+This example assumes you have set up your project to use code generation as described in the [GraphQL code generation guide](/guides/how-to/codegen/#codegen-for-admin-ui-extensions).
+
+```ts title="src/plugins/reviews/ui/components/review-detail/review-detail.component.ts"
+import { ResultOf } from '@graphql-typed-document-node/core';
+import { ChangeDetectionStrategy, Component, OnInit, OnDestroy } from '@angular/core';
+import { FormBuilder } from '@angular/forms';
+import { TypedBaseDetailComponent, LanguageCode, NotificationService, SharedModule } from '@vendure/admin-ui/core';
+
+// This is the TypedDocumentNode & type generated by GraphQL Code Generator
+import { graphql } from '../../gql';
+
+export const reviewDetailFragment = graphql(`
+  fragment ReviewDetail on ProductReview {
+    id
+    createdAt
+    updatedAt
+    title
+    rating
+    text
+    authorName
+    productId
+  }
+`);
+
+export const getReviewDetailDocument = graphql(`
+  query GetReviewDetail($id: ID!) {
+    review(id: $id) {
+      ...ReviewDetail
+    }
+  }
+`);
+
+export const createReviewDocument = graphql(`
+  mutation CreateReview($input: CreateProductReviewInput!) {
+    createProductReview(input: $input) {
+      ...ReviewDetail
+    }
+  }
+`);
+
+export const updateReviewDocument = graphql(`
+  mutation UpdateReview($input: UpdateProductReviewInput!) {
+    updateProductReview(input: $input) {
+      ...ReviewDetail
+    }
+  }
+`);
+
+@Component({
+    selector: 'review-detail',
+    templateUrl: './review-detail.component.html',
+    styleUrls: ['./review-detail.component.scss'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    standalone: true,
+    imports: [SharedModule],
+})
+export class ReviewDetailComponent extends TypedBaseDetailComponent<typeof getReviewDetailDocument, 'review'> implements OnInit, OnDestroy {
+    detailForm = this.formBuilder.group({
+        title: [''],
+        rating: [1],
+        authorName: [''],
+    });
+
+    constructor(private formBuilder: FormBuilder, private notificationService: NotificationService) {
+        super();
+    }
+
+    ngOnInit() {
+        this.init();
+    }
+
+    ngOnDestroy() {
+        this.destroy();
+    }
+
+    create() {
+        const { title, rating, authorName } = this.detailForm.value;
+        if (!title || rating == null || !authorName) {
+            return;
+        }
+        this.dataService
+            .mutate(createReviewDocument, {
+                input: { title, rating, authorName },
+            })
+            .subscribe(({ createProductReview }) => {
+                if (createProductReview.id) {
+                    this.notificationService.success('Review created');
+                    this.router.navigate(['extensions', 'reviews', createProductReview.id]);
+                }
+            });
+    }
+
+    update() {
+        const { title, rating, authorName } = this.detailForm.value;
+        this.dataService
+            .mutate(updateReviewDocument, {
+                input: { id: this.id, title, rating, authorName },
+            })
+            .subscribe(() => {
+                this.notificationService.success('Review updated');
+            });
+    }
+
+    protected setFormValues(entity: NonNullable<ResultOf<typeof getReviewDetailDocument>['review']>, languageCode: LanguageCode): void {
+        this.detailForm.patchValue({
+            title: entity.name,
+            rating: entity.rating,
+            authorName: entity.authorName,
+            productId: entity.productId,
+        });
+    }
+}
+```
+
+### Create the template
+
+Here is the standard layout for detail views:
+
+```html
+<vdr-page-block>
+    <vdr-action-bar>
+        <vdr-ab-left></vdr-ab-left>
+        <vdr-ab-right>
+            <button
+                class="button primary"
+                *ngIf="isNew$ | async; else updateButton"
+                (click)="create()"
+                [disabled]="detailForm.pristine || detailForm.invalid"
+            >
+                {{ 'common.create' | translate }}
+            </button>
+            <ng-template #updateButton>
+                <button
+                    class="btn btn-primary"
+                    (click)="update()"
+                    [disabled]="detailForm.pristine || detailForm.invalid"
+                >
+                    {{ 'common.update' | translate }}
+                </button>
+            </ng-template>
+        </vdr-ab-right>
+    </vdr-action-bar>
+</vdr-page-block>
+
+<form class="form" [formGroup]="detailForm">
+    <vdr-page-detail-layout>
+        <!-- The sidebar is used for displaying "metadata" type information about the entity -->
+        <vdr-page-detail-sidebar>
+            <vdr-card *ngIf="entity$ | async as entity">
+                <vdr-page-entity-info [entity]="entity" />
+            </vdr-card>
+        </vdr-page-detail-sidebar>
+
+        <!-- The main content area is used for displaying the entity's fields -->
+        <vdr-page-block>
+            <!-- The vdr-card is the container for grouping items together on a page -->
+            <!-- it can also take an optional [title] property to display a title -->
+            <vdr-card>
+                <!-- the form-grid class is used to lay out the form fields -->
+                <div class="form-grid">
+                    <vdr-form-field label="Title" for="title">
+                        <input id="title" type="text" formControlName="title" />
+                    </vdr-form-field>
+                    <vdr-form-field label="Rating" for="rating">
+                        <input id="rating" type="number" min="1" max="5" formControlName="rating" />
+                    </vdr-form-field>
+
+                    <!-- etc -->
+                </div>
+            </vdr-card>
+        </vdr-page-block>
+    </vdr-page-detail-layout>
+</form>
+```
+
+### Route config
+
+Here's how the routing would look for a typical list & detail view:
+
+```ts title="src/plugins/reviews/ui/routes.ts"
+import { registerRouteComponent } from '@vendure/admin-ui/core';
+
+import { ReviewDetailComponent, getReviewDetailDocument } from './components/review-detail/review-detail.component';
+import { ReviewListComponent } from './components/review-list/review-list.component';
+
+export default [
+    // List view
+    registerRouteComponent({
+        path: '',
+        component: ReviewListComponent,
+        breadcrumb: 'Product reviews',
+    }),
+    // highlight-start
+    // Detail view
+    registerRouteComponent({
+        path: ':id',
+        component: ReviewDetailComponent,
+        query: getReviewDetailDocument,
+        entityKey: 'productReview',
+        getBreadcrumbs: entity => [
+            {
+                label: 'Product reviews',
+                link: ['/extensions', 'product-reviews'],
+            },
+            {
+                label: `#${entity?.id} (${entity?.product.name})`,
+                link: [],
+            },
+        ],
+    }),
+    // highlight-end
+]
+```
+
+## Supporting custom fields
+
+From Vendure v2.2, it is possible for your [custom entities to support custom fields](/guides/developer-guide/database-entity/#supporting-custom-fields).
+
+If you have set up your entity to support custom fields, and you want custom fields to be available in the Admin UI detail view,
+you need to add the following to your detail component:
+
+```ts title="src/plugins/reviews/ui/components/review-detail/review-detail.component.ts"
+// highlight-next-line
+import { getCustomFieldsDefaults } from '@vendure/admin-ui/core';
+
+@Component({
+    selector: 'review-detail',
+    templateUrl: './review-detail.component.html',
+    styleUrls: ['./review-detail.component.scss'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    standalone: true,
+    imports: [SharedModule],
+})
+export class ReviewDetailComponent extends TypedBaseDetailComponent<typeof getReviewDetailDocument, 'review'> implements OnInit, OnDestroy {
+
+    // highlight-next-line
+    customFields = this.getCustomFieldConfig('ProductReview');
+
+    detailForm = this.formBuilder.group({
+        title: [''],
+        rating: [1],
+        authorName: [''],
+        // highlight-next-line
+        customFields: this.formBuilder.group(getCustomFieldsDefaults(this.customFields)),
+    });
+
+    protected setFormValues(entity: NonNullable<ResultOf<typeof getReviewDetailDocument>['review']>, languageCode: LanguageCode): void {
+        this.detailForm.patchValue({
+            title: entity.name,
+            rating: entity.rating,
+            authorName: entity.authorName,
+            productId: entity.productId,
+        });
+        // highlight-start
+        if (this.customFields.length) {
+            this.setCustomFieldFormValues(this.customFields, this.detailForm.get('customFields'), entity);
+        }
+        // highlight-end
+    }
+}
+```
+
+Then add a card for your custom fields to the template:
+
+```html title="src/plugins/reviews/ui/components/review-detail/review-detail.component.html"
+<form class="form" [formGroup]="detailForm">
+    <vdr-page-detail-layout>
+        <!-- The sidebar is used for displaying "metadata" type information about the entity -->
+        <vdr-page-detail-sidebar>
+            <vdr-card *ngIf="entity$ | async as entity">
+                <vdr-page-entity-info [entity]="entity" />
+            </vdr-card>
+        </vdr-page-detail-sidebar>
+
+        <!-- The main content area is used for displaying the entity's fields -->
+        <vdr-page-block>
+            <!-- The vdr-card is the container for grouping items together on a page -->
+            <!-- it can also take an optional [title] property to display a title -->
+            <vdr-card>
+                <!-- the form-grid class is used to lay out the form fields -->
+                <div class="form-grid">
+                    <vdr-form-field label="Title" for="title">
+                        <input id="title" type="text" formControlName="title" />
+                    </vdr-form-field>
+                    <vdr-form-field label="Rating" for="rating">
+                        <input id="rating" type="number" min="1" max="5" formControlName="rating" />
+                    </vdr-form-field>
+
+                    <!-- etc -->
+                </div>
+            </vdr-card>
+            // highlight-start
+            <vdr-card
+                    formGroupName="customFields"
+                    *ngIf="customFields.length"
+                    [title]="'common.custom-fields' | translate"
+            >
+                <vdr-tabbed-custom-fields
+                        entityName="ProductReview"
+                        [customFields]="customFields"
+                        [customFieldsFormGroup]="detailForm.get('customFields')"
+                ></vdr-tabbed-custom-fields>
+            </vdr-card>
+            // highlight-end
+        </vdr-page-block>
+    </vdr-page-detail-layout>
+</form>
+```

package/docs/guides/extending-the-admin-ui/creating-list-views/index.md

@@ -0,0 +1,331 @@
+---
+title: 'Creating List Views'
+---
+
+The two most common type of components you'll be creating in your UI extensions are list components and detail components.
+
+In Vendure, we have standardized the way you write these components so that your ui extensions can be made to fit seamlessly into the rest of the app.
+
+:::note
+The specific pattern described here is for Angular-based components. It is also possible to create list views using React components, but 
+in that case you won't be able to use the built-in data table & other Angular-specific components.
+:::
+
+## Example: Creating a Product Reviews List
+
+Let's say you have a plugin which adds a new entity to the database called `ProductReview`. You want to create a new list view in the Admin UI which displays all the reviews submitted.
+
+### Use the PaginatedList interface
+
+To use the standardized list component, you need to make sure your plugin exposes this list in the GraphQL API following the [PaginatedList interface](/reference/typescript-api/common/paginated-list/):
+
+```graphql
+type ProductReview implements Node {
+  id: ID!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+  title: String!
+  rating: Int!
+  text: String!
+  authorName: String!
+  product: Product!
+  productId: ID!  
+}
+
+type ProductReviewList implements PaginatedList {
+  items: [ProductReview!]!
+  totalItems: Int!
+}
+```
+
+:::info
+See the [Paginated Lists guide](/guides/how-to/paginated-list/) for details on how to implement this in your server plugin code.
+:::
+
+### Create the list component
+
+The list component itself is an Angular component which extends the [BaseListComponent](/reference/admin-ui-api/list-detail-views/base-list-component/) or [TypedBaseListComponent](/reference/admin-ui-api/list-detail-views/typed-base-list-component) class.
+
+This example assumes you have set up your project to use code generation as described in the [GraphQL code generation guide](/guides/how-to/codegen/#codegen-for-admin-ui-extensions).
+
+```ts title="src/plugins/reviews/ui/components/review-list/review-list.component.ts"
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { TypedBaseListComponent, SharedModule } from '@vendure/admin-ui/core';
+// This is the TypedDocumentNode generated by GraphQL Code Generator
+import { graphql } from '../../gql';
+
+const getReviewListDocument = graphql(`
+  query GetReviewList($options: ReviewListOptions) {
+    reviews(options: $options) {
+      items {
+        id
+        createdAt
+        updatedAt
+        title
+        rating
+        text
+        authorName
+        productId
+      }
+      totalItems
+    }
+  }
+`);
+
+@Component({
+    selector: 'review-list',
+    templateUrl: './review-list.component.html',
+    styleUrls: ['./review-list.component.scss'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    standalone: true,
+    imports: [SharedModule],
+})
+export class ReviewListComponent extends TypedBaseListComponent<typeof getReviewListDocument, 'reviews'> {
+
+    // Here we set up the filters that will be available
+    // to use in the data table
+    readonly filters = this.createFilterCollection()
+        .addIdFilter()
+        .addDateFilters()
+        .addFilter({
+            name: 'title',
+            type: {kind: 'text'},
+            label: 'Title',
+            filterField: 'title',
+        })
+        .addFilter({
+            name: 'rating',
+            type: {kind: 'number'},
+            label: 'Rating',
+            filterField: 'rating',
+        })
+        .addFilter({
+            name: 'authorName',
+            type: {kind: 'text'},
+            label: 'Author',
+            filterField: 'authorName',
+        })
+        .connectToRoute(this.route);
+
+    // Here we set up the sorting options that will be available
+    // to use in the data table
+    readonly sorts = this.createSortCollection()
+        .defaultSort('createdAt', 'DESC')
+        .addSort({name: 'createdAt'})
+        .addSort({name: 'updatedAt'})
+        .addSort({name: 'title'})
+        .addSort({name: 'rating'})
+        .addSort({name: 'authorName'})
+        .connectToRoute(this.route);
+
+    constructor() {
+        super();
+        super.configure({
+            document: getReviewListDocument,
+            getItems: data => data.reviews,
+            setVariables: (skip, take) => ({
+                options: {
+                    skip,
+                    take,
+                    filter: {
+                        title: {
+                            contains: this.searchTermControl.value,
+                        },
+                        ...this.filters.createFilterInput(),
+                    },
+                    sort: this.sorts.createSortInput(),
+                },
+            }),
+            refreshListOnChanges: [this.filters.valueChanges, this.sorts.valueChanges],
+        });
+    }
+}
+```
+
+### Create the template
+
+This is the standard layout for any list view. The main functionality is provided by the [DataTable2Component](/reference/admin-ui-api/components/data-table2component/).
+
+```html title="src/plugins/reviews/ui/components/review-list/review-list.component.html"
+<!-- optional if you want some buttons at the top -->
+<vdr-page-block>
+    <vdr-action-bar>
+        <vdr-ab-left></vdr-ab-left>
+        <vdr-ab-right>
+            <a class="btn btn-primary" *vdrIfPermissions="['CreateReview']" [routerLink]="['./', 'create']">
+                <clr-icon shape="plus"></clr-icon>
+                Create a review
+            </a>
+        </vdr-ab-right>
+    </vdr-action-bar>
+</vdr-page-block>
+
+<!-- The data table -->
+<vdr-data-table-2
+        id="review-list"
+        [items]="items$ | async"
+        [itemsPerPage]="itemsPerPage$ | async"
+        [totalItems]="totalItems$ | async"
+        [currentPage]="currentPage$ | async"
+        [filters]="filters"
+        (pageChange)="setPageNumber($event)"
+        (itemsPerPageChange)="setItemsPerPage($event)"
+>
+    <!-- optional if you want to support bulk actions -->
+    <vdr-bulk-action-menu
+            locationId="review-list"
+            [hostComponent]="this"
+            [selectionManager]="selectionManager"
+    />
+    
+    <!-- Adds a search bar -->
+    <vdr-dt2-search
+            [searchTermControl]="searchTermControl"
+            searchTermPlaceholder="Filter by title"
+    />
+    
+    <!-- Here we define all the available columns -->
+    <vdr-dt2-column id="id" [heading]="'common.id' | translate" [hiddenByDefault]="true">
+        <ng-template let-review="item">
+            {{ review.id }}
+        </ng-template>
+    </vdr-dt2-column>
+    <vdr-dt2-column
+            id="created-at"
+            [heading]="'common.created-at' | translate"
+            [hiddenByDefault]="true"
+            [sort]="sorts.get('createdAt')"
+    >
+        <ng-template let-review="item">
+            {{ review.createdAt | localeDate : 'short' }}
+        </ng-template>
+    </vdr-dt2-column>
+    <vdr-dt2-column
+            id="updated-at"
+            [heading]="'common.updated-at' | translate"
+            [hiddenByDefault]="true"
+            [sort]="sorts.get('updatedAt')"
+    >
+        <ng-template let-review="item">
+            {{ review.updatedAt | localeDate : 'short' }}
+        </ng-template>
+    </vdr-dt2-column>
+    <vdr-dt2-column id="title" heading="Title" [optional]="false" [sort]="sorts.get('title')">
+        <ng-template let-review="item">
+            <a class="button-ghost" [routerLink]="['./', review.id]"
+            ><span>{{ review.title }}</span>
+                <clr-icon shape="arrow right"></clr-icon>
+            </a>
+        </ng-template>
+    </vdr-dt2-column>
+    <vdr-dt2-column id="rating" heading="Rating" [sort]="sorts.get('rating')">
+        <ng-template let-review="item"><my-star-rating-component [rating]="review.rating"    /></ng-template>
+    </vdr-dt2-column>
+    <vdr-dt2-column id="author" heading="Author" [sort]="sorts.get('authorName')">
+        <ng-template let-review="item">{{ review.authorName }}</ng-template>
+    </vdr-dt2-column>
+</vdr-data-table-2>
+```
+
+### Route config
+
+```ts title="src/plugins/reviews/ui/routes.ts"
+import { registerRouteComponent } from '@vendure/admin-ui/core';
+
+import { ReviewListComponent } from './components/review-list/review-list.component';
+
+export default [
+    // highlight-start
+    registerRouteComponent({
+        path: '',
+        component: ReviewListComponent,
+        breadcrumb: 'Product reviews',
+    }),
+    // highlight-end
+]
+```
+
+## Supporting custom fields
+
+From Vendure v2.2, it is possible for your [custom entities to support custom fields](/guides/developer-guide/database-entity/#supporting-custom-fields).
+
+If you have set up your entity to support custom fields, and you want custom fields to be available in the Admin UI list view,
+you need to add the following to your list component:
+
+```ts title="src/plugins/reviews/ui/components/review-list/review-list.component.ts"
+@Component({
+    selector: 'review-list',
+    templateUrl: './review-list.component.html',
+    styleUrls: ['./review-list.component.scss'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    standalone: true,
+    imports: [SharedModule],
+})
+export class ReviewListComponent extends TypedBaseListComponent<typeof getReviewListDocument, 'reviews'> {
+
+    // highlight-next-line
+    customFields = this.getCustomFieldConfig('ProductReview');
+
+    readonly filters = this.createFilterCollection()
+        .addIdFilter()
+        .addDateFilters()
+        .addFilter({
+            name: 'title',
+            type: {kind: 'text'},
+            label: 'Title',
+            filterField: 'title',
+        })
+        .addFilter({
+            name: 'rating',
+            type: {kind: 'number'},
+            label: 'Rating',
+            filterField: 'rating',
+        })
+        .addFilter({
+            name: 'authorName',
+            type: {kind: 'text'},
+            label: 'Author',
+            filterField: 'authorName',
+        })
+        // highlight-next-line
+        .addCustomFieldFilters(this.customFields)
+        .connectToRoute(this.route);
+
+    readonly sorts = this.createSortCollection()
+        .defaultSort('createdAt', 'DESC')
+        .addSort({name: 'createdAt'})
+        .addSort({name: 'updatedAt'})
+        .addSort({name: 'title'})
+        .addSort({name: 'rating'})
+        .addSort({name: 'authorName'})
+        // highlight-next-line
+        .addCustomFieldSorts(this.customFields)
+        .connectToRoute(this.route);
+    
+    // rest of class omitted for brevity
+}
+```
+
+and then add the `vdr-dt2-custom-field-column` component to your data table:
+
+```html title="src/plugins/reviews/ui/components/review-list/review-list.component.html"
+<vdr-data-table-2
+    id="review-list"
+    [items]="items$ | async"
+    [itemsPerPage]="itemsPerPage$ | async"
+    [totalItems]="totalItems$ | async"
+    [currentPage]="currentPage$ | async"
+    [filters]="filters"
+    (pageChange)="setPageNumber($event)"
+    (itemsPerPageChange)="setItemsPerPage($event)"
+>
+    <!-- rest of data table omitted for brevity -->
+    // highlight-start
+    <vdr-dt2-custom-field-column
+            *ngFor="let customField of customFields"
+            [customField]="customField"
+            [sorts]="sorts"
+    />
+    // highlight-end
+</vdr-data-table-2>
+```