How to implement required Facets

[michaelbromley]

In the video Vendure extensibility: Advanced custom fields & UI extensions I demonstrate a UI extension that helps admins to ensure that products always include the expected facets.

This solution is not open source (it's just part of one of my own projects) but since a lot of people asked about it, I'm dumping the code required to implement:

Custom fields

You need to define the following custom fields on Facet:

Facet: [
        {
            name: 'required',
            label: [{ languageCode: LanguageCode.en, value: 'Required for all products' }],
            type: 'boolean',
            nullable: true,
            public: false,
        },
        {
            name: 'requiredIf',
            label: [{ languageCode: LanguageCode.en, value: 'Required depending on' }],
            type: 'relation',
            entity: FacetValue,
            list: true,
            public: false,
            ui: { component: 'facet-value-form-input' },
        },
    ],

Admin API extension

The ui component uses this custom query on the Admin API:

export const adminApiExtensions = gql`
    extend type Query {
        requiredFacets: [Facet!]!
    }
`;

admin.resolver.ts

import { Query, Resolver } from '@nestjs/graphql';
import {
    Allow,
    Ctx,
    Facet,
    Permission,
    RequestContext,
    TransactionalConnection,
    TranslatorService,
} from '@vendure/core';

@Resolver()
export class AdminResolver {
    constructor(private connection: TransactionalConnection, private translator: TranslatorService) {}

    @Query()
    @Allow(Permission.ReadFacet, Permission.ReadCatalog, Permission.ReadProduct)
    async requiredFacets(@Ctx() ctx: RequestContext): Promise<Facet[]> {
        const qb = this.connection
            .getRepository(ctx, Facet)
            .createQueryBuilder('facet')
            .leftJoinAndSelect('facet.values', 'value')
            .leftJoinAndSelect('facet.customFields.requiredIf', 'dependencies')
            .leftJoinAndSelect('facet.translations', 'ft')
            .leftJoinAndSelect('value.translations', 'vt')
            .leftJoinAndSelect('value.facet', 'value_facet')
            .leftJoinAndSelect('value_facet.translations', 'vft')
            .groupBy('facet.id')
            .addGroupBy('value.id')
            .addGroupBy('value_facet.id')
            .addGroupBy('ft.id')
            .addGroupBy('vt.id')
            .addGroupBy('vft.id')
            .addGroupBy('dependencies.id')
            .having('count(dependencies.id) > 0')
            .orHaving('facet.customFields.required = true');

        return qb.getMany().then((facets) => {
            for (const facet of facets) {
                this.translator.translate(facet, ctx, ['values', ['values', 'facet']]);
            }
            return facets;
        });
    }
}

UI Component

The ui component files:

required-facets.component.html

<ng-container *ngIf="requiredFacets$ | async as requiredFacets">
    <ng-container *ngIf="status$ | async as status">
        <clr-accordion>
            <clr-accordion-panel [clrAccordionPanelOpen]='status === "incomplete"'>
                <clr-accordion-title>
                    <div class="flex center">
                        <span class="">Required Facets</span>
                        <div class='flex-spacer'></div>
                        <vdr-chip colorType="success" *ngIf="status === 'complete'; else incomplete">
                            <cds-icon shape="check-circle"></cds-icon>
                            complete</vdr-chip
                        >
                        <ng-template #incomplete>
                            <vdr-chip colorType="warning">
                                <cds-icon shape="exclamation-triangle"></cds-icon>
                                incomplete</vdr-chip
                            >
                        </ng-template>
                    </div>
                </clr-accordion-title>
                <clr-accordion-content *clrIfExpanded>
                    <div *ngFor="let entry of requiredFacets" class="flex center facet-row">
                        <div class="facet-name">{{ entry.facet.name }}</div>
                        <ng-select
                            [items]="entry.facet.values"
                            [ngModel]="entry.selectedValues"
                            [addTag]="false"
                            [hideSelected]="true"
                            (add)="addFacetValue($event)"
                            (remove)="removeFacetValue($event)"
                            multiple="true"
                            appendTo="body"
                            bindLabel="name"
                        >
                            <ng-template ng-label-tmp let-item="item" let-clear="clear">
                                <vdr-facet-value-chip
                                    [facetValue]="item"
                                    [removable]="!readonly"
                                    (remove)="clear(item)"
                                ></vdr-facet-value-chip>
                            </ng-template>
                            <ng-template ng-option-tmp let-item="item">
                                <vdr-facet-value-chip
                                    [facetValue]="item"
                                    [removable]="false"
                                ></vdr-facet-value-chip>
                            </ng-template>
                        </ng-select></div
                ></clr-accordion-content>
            </clr-accordion-panel>
        </clr-accordion>
    </ng-container>
</ng-container>

required-facets.component.ts

import { CustomDetailComponent, DataService, ModalService } from '@vendure/admin-ui/core';
import { FormGroup } from '@angular/forms';
import { combineLatest, Observable } from 'rxjs';
import { map, startWith } from 'rxjs/operators';
import { Component, OnInit } from '@angular/core';
import { unique } from '@vendure/common/lib/unique';
import { shareReplay } from 'rxjs/operators';
import { GET_REQUIRED_FACETS } from './required-facets.graphql';
import { GetRequiredFacetsQuery, GetRequiredFacetsQueryVariables } from '../../generated-types';

type RequiredFacetValueStatus = 'complete' | 'incomplete';
type RequiredFacetWithValues = GetRequiredFacetsQuery['requiredFacets'][number];

@Component({
    selector: 'kb-required-facets',
    templateUrl: `./required-facets.component.html`,
    styleUrls: [`./required-facets.component.scss`],
})
export class RequiredFacetsComponent implements CustomDetailComponent, OnInit {
    detailForm: FormGroup;
    entity$: Observable<any>;
    status$: Observable<RequiredFacetValueStatus>;
    requiredFacets$: Observable<
        Array<{ facet: RequiredFacetWithValues; selectedValues: RequiredFacetWithValues['values'] }>
    >;

    constructor(private dataService: DataService, private modalService: ModalService) {}

    ngOnInit() {
        const selectedFacetValueIds$ = this.detailForm
            .get(['product', 'facetValueIds'])!
            .valueChanges.pipe(startWith(this.detailForm.get(['product', 'facetValueIds'])!.value));
        const possiblyRequiredFacets$ = this.dataService
            .query<GetRequiredFacetsQuery, GetRequiredFacetsQueryVariables>(
                GET_REQUIRED_FACETS,
                {},
                'cache-first',
            )
            .single$.pipe(
                map(({ requiredFacets }) =>
                    requiredFacets.filter(
                        ({ customFields }) =>
                            customFields?.required === true || customFields?.requiredIf?.length,
                    ),
                ),
            );
        this.requiredFacets$ = combineLatest(possiblyRequiredFacets$, selectedFacetValueIds$).pipe(
            shareReplay(1),
            map(([facets, selectedFacetValueIds]) => {
                return facets
                    .filter(
                        ({ customFields }) =>
                            customFields?.required === true ||
                            customFields?.requiredIf?.find((f) => selectedFacetValueIds.includes(f.id)),
                    )
                    .map((facet) => ({
                        facet,
                        selectedValues: facet.values.filter((value) =>
                            selectedFacetValueIds.includes(value.id),
                        ),
                    }));
            }),
        );
        this.status$ = this.requiredFacets$.pipe(
            map((items) => (items.every((i) => 0 < i.selectedValues.length) ? 'complete' : 'incomplete')),
        );
    }

    addFacetValue(facetValue: RequiredFacetWithValues['values'][number]) {
        const productGroup = this.getProductFormGroup();
        const currentFacetValueIds: string[] = productGroup.value.facetValueIds;
        productGroup.patchValue({
            facetValueIds: unique([...currentFacetValueIds, facetValue.id]),
        });
        productGroup.markAsDirty();
    }

    removeFacetValue({ value: facetValue }: { value: RequiredFacetWithValues['values'][number] }) {
        const productGroup = this.getProductFormGroup();
        const currentFacetValueIds: string[] = productGroup.value.facetValueIds;
        productGroup.patchValue({
            facetValueIds: unique([...currentFacetValueIds.filter((id) => id !== facetValue.id)]),
        });
        productGroup.markAsDirty();
    }

    private getProductFormGroup(): FormGroup {
        return this.detailForm.get('product') as FormGroup;
    }
}

required-facets.component.scss

.facet-row {
    width: 100%;
    margin-bottom: 6px;
}
.facet-name {
    min-width: 120px;
}
ng-select {
    width: 100%;
}
::ng-deep {
    .clr-accordion-header-button {
        display: flex;
        align-items: center;
    }
    .clr-accordion-title {
        width: 100%;
    }
}

required-facets.graphql.ts

import { gql } from 'apollo-angular';

export const GET_REQUIRED_FACETS = gql`
    query GetRequiredFacets {
        requiredFacets {
            id
            name
            customFields {
                required
                requiredIf {
                    id
                }
            }
            values {
                id
                name
                facet {
                    id
                    name
                }
            }
        }
    }
`;

Then register the component in your ui extension module

registerCustomDetailComponent({
  locationId: 'product-detail',
  component: RequiredFacetsComponent,
}),

[buisine]

@michaelbromley
Thanks for sharing, i'm getting this to work but stucked with this :

import { GetRequiredFacetsQuery, GetRequiredFacetsQueryVariables } from '../generated-types';

it cannot be found, i assume it has to be generated prior api launch by some tool from graphQl schema ?
I already made my facets as required with custom fields before activation of the plugin.
Thank you.

[buisine]

export interface GetRequiredFacetsQuery {
  requiredFacets: Array<RequiredFacetWithValues>;
}

export interface RequiredFacetWithValues {
  id: string;
  name: string;
  customFields: {
    required: boolean;
    requiredIf: Array<{
      id: string;
    }>;
  };
  values: Array<{
    id: string;
    name: string;
    facet: {
      id: string;
      name: string;
    };
  }>;
}

export interface GetRequiredFacetsQueryVariables {
  // No variables are used in this query
}

[michaelbromley]

Hi,

Yes you are correct - codegen is needed to create those TS types. Is this now working for you?

[buisine]

Hi thank you.
Yes it looks good for customs fields, but i am now stucked with the admin UI, compilation goes well, but browser rendering triggers an error in the console and the added ui is not displayed at all.

The console error as to do with the async pipe, that has something to do with the commonModule...i remain stucked there with these customisations.

[buisine]

This is the error i got into the browser console :

the terminal goes well

I cannot find a way to fix, i'm not used to angular, do you have an idea ?
That facet ui implementation is great and really needed for any project

Angular CLI: 16.2.10
Node: 20.9.0 (Unsupported)
Package Manager: yarn 1.22.19
OS: linux x64

Angular: undefined
...

Package Version

@angular-devkit/architect 0.1602.10
@angular-devkit/core 16.2.10
@angular-devkit/schematics 16.2.10
@schematics/angular 16.2.10
typescript 4.9.5

[buisine]

I'm on latest vendure 2.1.3

Got rid of the unsupported node version :

Angular CLI: 16.2.10
Node: 18.18.2
Package Manager: yarn 1.22.19
OS: linux x64

Angular: undefined
...

Package Version

@angular-devkit/architect 0.1602.10
@angular-devkit/core 16.2.10
@angular-devkit/schematics 16.2.10
@schematics/angular 16.2.10
typescript 4.9.5

Same Error

[Julian-Dumitrascu]

I've just tried to open that video. It won't render.
We can talk about Vendure. We'll see when we can use it or recommend it.

[michaelbromley]

Hi, do you mean the youtube video isn't working for you? I just checked and seems ok to me.

[Julian-Dumitrascu]

This time I was able to listen to you.

1. I wouldn't try to find the cause of this new error now, but a topic has become really big: A computer user is faced with so many challenges! We can discuss at least:
   1.1 overcoming challenges that software poses in our interactions.
   Example: I prefer GitHub to Slack.
   You can invite me to your Slack instance for talks.
   If there's no challenge in this, we simply use these means and methods.
   1.2 overcoming challenges that your software poses.
   I haven't found any because I am yet to try your software.
2. What are your views on, and procedure for, building (business) relationships?
   As a part of this: How do you make someone, e.g. me, consider your services?

[michaelbromley]

I don't fully understand your message. Is it related to the topic at hand (implementing required facets)? If no, and you just want to talk about general topics, then I invite you to join our Discord: https://vendure.io/community

[martijnvdbrug]

At Pinelab we've had this feature request quite often. It's such a useful feature for most shops that @dalyathan packaged this feature into a plugin: https://pinelab-plugins.com/plugin/vendure-plugin-facet-suggestions/

Now you can just install it without having to implement and maintain it.

*️⃣ The plugin version is slightly different from the feature in the video, in that facets are suggested and never mandatory.

[michaelbromley]

Nice work @dalyathan! Let's add this to the plugins listings.

[hieunguyendac]

Hi @martijnvdbrug , please add localization feature to your plugin, thank you a lot!

[martijnvdbrug]

Good suggestion @hieunguyendac. We are a little short on time though, so PR's are welcome!

[alihussain575]

I have an issue here I want to populate the product data with my custom input fields how can I achieve that?

import { FormBuilder, FormGroup } from "@angular/forms";
import { Observable } from "rxjs";
import { SharedModule, CustomDetailComponent, DataService, ModalService } from "@vendure/admin-ui/core";
import { CreatePageDocument, GetPageDocument, GetPagesDocument, GetPagesQuery, PageFragment, UpdatePageDocument } from "../generated-admin-types";
import { CustomComponentPropsWithRef } from "react";

@Component({
    templateUrl: `./product-type.component.html`,
    standalone: true,
    imports: [SharedModule],
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ProductTypeComponent implements CustomDetailComponent, OnInit {
    entity$: Observable<any>
    detailForm: FormGroup

    // detailForm = this.formBuilder.group<{
    //     slogan: String
    //     alternateName: String
    //     additionalType: String
    //     disambiguatingDescription: String
    //     oneWordName: String
    //     isService: Boolean,
    //     serviceOutput: String
    //     serviceType: String
    //     repetitions: Number,
    //     duration: Number,
    //     durationUnit: 'Days' | 'Weeks' | "Months",
    //     meta_title: String
    //     meta_keyword: String
    //     meta_description: String
    // }>({
    //     slogan: '',
    //     alternateName: '',
    //     additionalType: '',
    //     disambiguatingDescription: '',
    //     oneWordName: '',
    //     isService: false,
    //     serviceOutput: '',
    //     serviceType: '',
    //     repetitions: 0,
    //     duration: 0,
    //     durationUnit: 'Days',
    //     meta_title: '',
    //     meta_keyword: '',
    //     meta_description: '',
    // });

    constructor(private dataService: DataService, private modalService: ModalService) {
        
    }

    ngOnInit() { 

        console.log(this.detailForm.get('product'))

    }

    protected setFormValues(entity: any, languageCode: any): void {
        this.detailForm.patchValue({
			slogan: entity.slogan,
			additionalType: entity.additionalType,
			alternateName: entity.alternateName,
			disambiguatingDescription: entity.disambiguatingDescription,
			duration: entity.duration,
			durationUnit: entity.durationUnit,
			isService: entity.isService,
			meta_description: entity.meta_description,
			meta_title: entity.meta_title,
			meta_keyword: entity.meta_keyword,
            oneWordName : entity.oneWordName,
            repetitions: entity.repetitions,
            serviceOutput : entity.serviceOutput,
            serviceType: entity.serviceType
        })
        console.log(this.detailForm)
    }

    private getProductFormGroup(): FormGroup {
        return this.detailForm.get('product') as FormGroup | any;
    }

}

  
    <!-- 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 -->
      <!-- 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 title="Additional Details">
        <!-- the form-grid class is used to lay out the form fields -->
        <div class="form-grid">
          <vdr-form-field label="Slogan" for="slogan">
            <input id="slogan" type="text" formControlName="slogan" />
          </vdr-form-field>

          <vdr-form-field label="Alternate Name" for="alternateName">
            <input id="alternateName" formControlName="alternateName" />
          </vdr-form-field>

          <vdr-form-field label="Additional Type" for="additionalType">
            <input type="text" formControlName="additionalType" id="additionalType" />
          </vdr-form-field>

          <vdr-form-field label="Disambiguating Description" for="disambiguatingDescription">
              <input formControlName="disambiguatingDescription" id="disambiguatingDescription" />
            </vdr-form-field>
            <vdr-form-field label="One Word Name " for="oneWordName " class="form-grid-span" >
              <input formControlName="oneWordName" id="oneWordName " />
            </vdr-form-field>
        </div>
        <vdr-form-field label="Is Service" for="isService">
          <clr-toggle-wrapper>
            <input type="checkbox" clrToggle name="status" formControlName="status" />
            <!-- <label>{{ detailForm.get('isService')?.value === 'draft' ? "Draft" : "Publish" }}</label> -->
          </clr-toggle-wrapper>
        </vdr-form-field>
      </vdr-card>

      <vdr-card title="Service">
          <div class="form-grid">
            <vdr-form-field label="Service Output" for="serviceOutput">
              <input id="serviceOutput" type="text" formControlName="serviceOutput" />
            </vdr-form-field>
  
            <vdr-form-field label="Service Type" for="serviceType">
              <input id="serviceType" formControlName="serviceType" />
            </vdr-form-field>
  
            <vdr-form-field label="Repetitions" for="repetitions">
              <input type="number" formControlName="repetitions" id="repetitions" />
            </vdr-form-field>
  
            <vdr-form-field label="disambiguatingDescription" for="disambiguatingDescription">
                <input type="number" formControlName="disambiguatingDescription" id="repetitions" />
              </vdr-form-field>
              <vdr-form-field label="Duration" for="duration">
                <input type="number" formControlName="duration" id="duration" />
              </vdr-form-field>
              <vdr-form-field label="Duration Unit" for="durationUnit">
                  <select id="parent" formControlName="parent">
                    <option value="Days">Days</option>
                    <option value="Weeks">Weeks</option>
                    <option value="Months">Months</option>
                  </select>
                </vdr-form-field>
              <!-- <vdr-form-field label="Duration Unit" for="durationUnit">
                <input type="number" formControlName="durationUnit" id="durationUnit" />
              </vdr-form-field> -->
          </div>
        </vdr-card>


      <vdr-card title="Meta Details for SEO" style="margin-bottom: 20px;">
        <div class="form-grid">
          <vdr-form-field label="Page Title" for="pageTitle">
            <input id="pageTitle" type="text" formControlName="pageTitle" />
          </vdr-form-field>

          <vdr-form-field label="Meta Description" for="metaDescription">
            <input id="metaDescription" type="text" formControlName="metaDescription" />
          </vdr-form-field>

          <vdr-form-field label="Keyword" for="keyword" class="form-grid-span">
            <input id="keyword" formControlName="keyword" class="w-full" />
          </vdr-form-field>
        </div>
      </vdr-card>
</form>```