Adding Custom Fields to Vendure Entities

Adding Custom Fields to Vendure Entities | Vendure Docs

Graphql

mutation {    updateProduct(input: {        id: 1        customFields: {        infoUrl: "https://some-url.com",        downloadable: true,        }        translations: [        { languageCode: en, customFields: { shortName: "foo" } }        ]        }) {        id        name        customFields {            infoUrl            downloadable            shortName        }    }}

Graphql

query {    products(options: {    filter: {        infoUrl: { contains: "new" },        downloadable: { eq: true }        },        sort: {            infoUrl: ASC        }        }) {        items {            id            name            customFields {                infoUrl                downloadable                shortName            }        }    }}

Type	Description	Example
`string`	Short string data	url, label
`localeString`	Localized short strings	localized url
`text`	Long text data	extended product info, json config object
`localeText`	Localized long text	localized extended product info
`int`	Integer	product weight, customer loyalty points, monetary values
`float`	Floating point number	product review rating
`boolean`	Boolean	isDownloadable flag on product
`datetime`	A datetime	date that variant is back in stock
`struct`	Structured json-like data	Key-value attributes with additional data for products
`relation`	A relation to another entity	Asset used as a customer avatar, related Products

const config = {    // ...    customFields: {        Customer: [            {                name: 'avatar',                type: 'relation', // [!code highlight]                entity: Asset, // [!code highlight]            },        ],    },};

Graphql

mutation {    updateCustomer(input: {        id: 1        customFields: {            avatarId: 42,        }    }) {        id        customFields {            avatar {                id                name                preview            }        }    }}

src/vendure-config.ts

import { VendureConfig } from '@vendure/core';const config: VendureConfig = {    // ...    customFields: {        Customer: [            { name: 'externalId', type: 'string' },            { name: 'avatar', type: 'relation', entity: Asset },        ],    },};

const customer = await this.connection.getRepository(ctx, Customer).findOne({    where: { id: 1 },    relations: {        customFields: {            avatar: true,        }    }});console.log(customer.avatar);

const customer = await this.connection.getRepository(ctx, Customer).createQueryBuilder('customer')    .leftJoinAndSelect('customer.customFields.avatar', 'avatar')    .where('customer.id = :id', { id: 1 })    .getOne();console.log(customer.avatar);

const customer = await this.connection.getRepository(ctx, Customer).findOne({    where: { id: 1 },});// No join needed to access the id of the related Assetconsole.log(customer.customFields.avatarId);

Graphql

query {    activeCustomer {        customFields {            avatar {                id                preview            }            # or, when only the id is needed:            avatarId        }    }}

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'infoUrl', // [!code highlight]                type: 'string'            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'infoUrls',                type: 'string',                list: true, // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { LanguageCode } from '@vendure/core';const config = {    // ...    customFields: {        Product: [            {                name: 'infoUrl',                type: 'string',                label: [ // [!code highlight]                    { languageCode: LanguageCode.en, value: 'Info URL' }, // [!code highlight]                    { languageCode: LanguageCode.de, value: 'Info-URL' }, // [!code highlight]                    { languageCode: LanguageCode.es, value: 'URL de información' }, // [!code highlight]                ], // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { LanguageCode } from '@vendure/core';const config = {    // ...    customFields: {        Product: [            {                name: 'infoUrl',                type: 'string',                description: [ // [!code highlight]                    { languageCode: LanguageCode.en, value: 'A URL to more information about the product' }, // [!code highlight]                    { languageCode: LanguageCode.de, value: 'Eine URL zu weiteren Informationen über das Produkt' }, // [!code highlight]                    { languageCode: LanguageCode.es, value: 'Una URL con más información sobre el producto' }, // [!code highlight]                ], // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'profitMargin',                type: 'int',                public: false, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'profitMargin',                type: 'int',                readonly: true, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        OrderLine: [            {                name: 'referralId',                type: 'string',                internal: true, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'reviewRating',                type: 'float',                defaultValue: 0, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'reviewRating',                type: 'float',                nullable: false, // [!code highlight]                defaultValue: 0, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Customer: [            {                name: 'externalId',                type: 'string',                unique: true, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'externalReference',                type: 'string',                index: true, // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { LanguageCode } from '@vendure/core';const config = {    // ...    customFields: {        Product: [            {                name: 'infoUrl',                type: 'string',                validate: (value: any) => { // [!code highlight]                    if (!value.startsWith('http')) { // [!code highlight]                        // If a localized error message is not required, a simple string can be returned. // [!code highlight]                        // return 'The URL must start with "http"'; // [!code highlight] // [!code highlight]                        // If a localized error message is required, return an array of LocalizedString objects. // [!code highlight]                        return [ // [!code highlight]                            { languageCode: LanguageCode.en, value: 'The URL must start with "http"' }, // [!code highlight]                            { languageCode: LanguageCode.de, value: 'Die URL muss mit "http" beginnen' }, // [!code highlight]                            { languageCode: LanguageCode.es, value: 'La URL debe comenzar con "http"' }, // [!code highlight]                        ]; // [!code highlight]                    } // [!code highlight]                }, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'partCode',                type: 'string',                validate: async (value, injector, ctx) => { // [!code highlight]                    const partCodeService = injector.get(PartCodeService); // [!code highlight]                    const isValid = await partCodeService.validateCode(value); // [!code highlight]                    if (!isValid) { // [!code highlight]                        return `Part code ${value} is not valid`; // [!code highlight]                    } // [!code highlight]                }, // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { Permission } from '@vendure/core';const config = {    // ...    customFields: {        Product: [            {                name: 'internalNotes',                type: 'text',                requiresPermission: Permission.SuperAdmin, // [!code highlight]            },            {                name: 'shippingType',                type: 'string',                // You can also use an array of permissions,  // [!code highlight]                // and the user must have at least one of the permissions // [!code highlight]                // to access the field. // [!code highlight]                requiresPermission: [ // [!code highlight]                    Permission.SuperAdmin, // [!code highlight]                    Permission.ReadShippingMethod, // [!code highlight]                ], // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'oldField',                type: 'string',                deprecated: true, // [!code highlight]            },            {                name: 'legacyUrl',                type: 'string',                deprecated: 'Use the new infoUrl field instead', // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'gtin',                type: 'string',                pattern: '^\d{8}(?:\d{4,6})?$', // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { LanguageCode } from '@vendure/core';const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'condition',                type: 'string',                options: [ // [!code highlight]                    { value: 'new', label: [{ languageCode: LanguageCode.en, value: 'New' }] }, // [!code highlight]                    { value: 'used', label: [{ languageCode: LanguageCode.en, value: 'Used' }] }, // [!code highlight]                ], // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'partCode',                type: 'string',                length: 20, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'reviewRating',                type: 'int',                min: 0, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'reviewRating',                type: 'int',                max: 5, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'reviewRating',                type: 'int',                step: 0.5, // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'releaseDate',                type: 'datetime',                min: '2019-01-01T00:00:00.000Z', // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'releaseDate',                type: 'datetime',                max: '2019-12-31T23:59:59.999Z', // [!code highlight]            },        ]    }};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            {                name: 'dimensions',                type: 'struct',                fields: [ // [!code highlight]                    { name: 'length', type: 'int' }, // [!code highlight]                    { name: 'width', type: 'int' }, // [!code highlight]                    { name: 'height', type: 'int' }, // [!code highlight]                ], // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { LanguageCode } from '@vendure/core';const config = {    // ...    customFields: {        OrderLine: [            {                name: 'customizationOptions',                type: 'struct',                fields: [                    {                        name: 'color',                        type: 'string',                        options: [ // [!code highlight]                            { value: 'red', label: [{ languageCode: LanguageCode.en, value: 'Red' }] }, // [!code highlight]                            { value: 'blue', label: [{ languageCode: LanguageCode.en, value: 'Blue' }] }, // [!code highlight]                        ], // [!code highlight]                    },                    {                        name: 'engraving',                        type: 'string',                        validate: (value: any) => { // [!code highlight]                            if (value.length > 20) { // [!code highlight]                                return 'Engraving text must be 20 characters or fewer'; // [!code highlight]                            } // [!code highlight]                        }, // [!code highlight]                    },                    {                        name: 'notifyEmailAddresses',                        type: 'string',                        list: true, // [!code highlight]                    }                ],            },        ]    }};

src/vendure-config.ts

import { Product } from '\@vendure/core';const config = {    // ...    customFields: {        Product: [            {                name: 'relatedProducts',                list: true,                type: 'relation', // [!code highlight]                entity: Product, // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { Product } from '\@vendure/core';const config = {    // ...    customFields: {        Product: [            {                name: 'relatedProducts',                list: true,                type: 'relation',                entity: Product,                eager: true, // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { CmsArticle } from './entities/cms-article.entity';const config = {    // ...    customFields: {        Product: [            {                name: 'blogPosts',                list: true,                type: 'relation',                entity: CmsArticle,                graphQLType: 'BlogPost', // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { Product } from '\@vendure/core';import { ProductReview } from './entities/product-review.entity';const config = {    // ...    customFields: {        Product: [            {                name: 'reviews',                list: true,                type: 'relation',                entity: ProductReview,                inverseSide: (review: ProductReview) => review.product, // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { Product } from '\@vendure/core';import { ProductReview } from './entities/product-review.entity';const config = {    // ...    customFields: {        Product: [            {                name: 'reviews',                list: true,                type: 'relation',                entity: ProductReview,                cascade: ['insert', 'update'], // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { Product } from '\@vendure/core';import { ProductReview } from './entities/product-review.entity';const config = {    // ...    customFields: {        Product: [            {                name: 'reviews',                list: false,                type: 'relation',                entity: ProductReview,                onDelete: 'SET NULL', // [!code highlight]            },        ]    }};

src/vendure-config.ts

import { Product } from '\@vendure/core';import { ProductReview } from './entities/product-review.entity';const config = {    // ...    customFields: {        Product: [            {                name: 'reviews',                list: false,                type: 'relation',                entity: ProductReview,                onUpdate: 'CASCADE', // [!code highlight]            },        ]    }};

Type	Form input component
`string`, `localeString`	`text-form-input` or, if options are defined, `select-form-input`
`text`, `localeText`	`textarea-form-input`
`int`, `float`	`number-form-input`
`boolean`	`boolean-form-input`
`datetime`	`date-form-input`
`relation`	Depends on related entity, defaults to `relation-form-input` if no specific component exists

src/vendure-config.ts

const config = {    // ...    customFields: {        ProductVariant: [            {                name: 'rrp',                type: 'int',                ui: { component: 'currency-form-input' }, // [!code highlight]            },        ]    }}

import { LanguageCode, VendureConfig } from '@vendure/core';const config: VendureConfig = {    // ...    customFields: {        Product: [            // Rich text editor            { name: 'additionalInfo', type: 'text', ui: { component: 'rich-text-form-input' } },            // JSON editor            { name: 'specs', type: 'text', ui: { component: 'json-editor-form-input' } },            // Numeric with suffix            {                name: 'weight',                type: 'int',                ui: { component: 'number-form-input', suffix: 'g' },            },            // Currency input            {                name: 'RRP',                type: 'int',                ui: { component: 'currency-form-input' },            },            // Select with options            {                name: 'pageType',                type: 'string',                ui: {                    component: 'select-form-input',                    options: [                        { value: 'static', label: [{ languageCode: LanguageCode.en, value: 'Static' }] },                        { value: 'dynamic', label: [{ languageCode: LanguageCode.en, value: 'Dynamic' }] },                    ],                },            },            // Text with prefix            {                name: 'link',                type: 'string',                ui: {                    component: 'text-form-input',                    prefix: 'https://',                },            },        ],    },};

src/vendure-config.ts

const config = {    // ...    customFields: {        Product: [            { name: 'additionalInfo', type: 'text', ui: { component: 'rich-text-form-input' } },            { name: 'specs', type: 'text', ui: { component: 'json-editor-form-input' } },            { name: 'width', type: 'int', ui: { tab: 'Shipping' } },            { name: 'height', type: 'int', ui: { tab: 'Shipping' } },            { name: 'depth', type: 'int', ui: { tab: 'Shipping' } },            { name: 'weight', type: 'int', ui: { tab: 'Shipping' } },        ],    },}

import { RequestContext, TransactionalConnection, ID, Product } from '@vendure/core';export class MyService {    constructor(private connection: TransactionalConnection) {    }    async getInfoUrl(ctx: RequestContext, productId: ID) {        const product = await this.connection            .getRepository(ctx, Product)            .findOne(productId);        return product.customFields.infoUrl;    }                           // ^ TS2339: Property 'infoUrl'}                             // does not exist on type 'CustomProductFields'.

// types.ts// Note: we are using a deep import here, rather than importing from `@vendure/core` due to// a possible bug in TypeScript (https://github.com/microsoft/TypeScript/issues/46617) which// causes issues when multiple plugins extend the same custom fields interface.import { CustomProductFields } from '@vendure/core/dist/entity/custom-entity-fields';declare module '@vendure/core/dist/entity/custom-entity-fields' {    interface CustomProductFields {        infoUrl: string;        downloadable: boolean;        shortName: string;    }}

Custom Fields

Defining custom fields

Custom Fields

Defining custom fields

Available custom field types

Relations

Accessing custom fields in TypeScript

Relation ids

Custom field config properties

Common properties

name

type

list

label

description

public

readonly

internal

defaultValue

nullable

unique

index

validate

requiresPermission

deprecated

Properties for string fields

pattern

options

length

Properties for localeString fields

pattern

length

Properties for int & float fields

min

max

step

Properties for datetime fields

min

max

step

Properties for struct fields

fields

Properties for relation fields

entity

eager

graphQLType

inverseSide

cascade

onDelete

onUpdate

Custom Field UI

Default form inputs

Specifying the input component

Custom form input components

Tabbed custom fields

TypeScript Typings

Special cases

OrderLine custom fields

Order custom fields

ShippingMethod custom fields

PaymentMethod custom fields

Customer custom fields

Properties for `string` fields

Properties for `localeString` fields

Properties for `int` & `float` fields

Properties for `datetime` fields

Properties for `struct` fields

Properties for `relation` fields