Adapter for custom data types

info

In order to use this feature, you need to initialize a FireCMS repository. You can do this by following the Customization quickstart guide.

FireCMS allows you to customize the way data is displayed and edited in the CMS. By default, the views created by FireCMS are based on the data type defined in your collection properties:

{
    name: "Created on",
    dataType: "date",
}

In this example, all fields related to created on will be displayed as a date picker, including tables, forms, detail, and filter views.

However, you may want to use a different data type in the CMS than the one you use in your data model. For example, you may want to save the date value as a Unix timestamp in your database, but display it as a date in the CMS.

To achieve this, you can use callbacks to convert the data from your model to the format you want to display in the CMS.

Let's use a simple example to illustrate this. Imagine you have an exercises collection, and you want to display the creation date of each exercise in the CMS. In your database, you store the creation date as a Unix timestamp. You want to display this date as a human-readable date in the CMS.

export type Exercise = {
    name: string;
    createdOn: Date;
}

Converting data types when reading from the database

You can use the onFetch callback to convert the data type when reading from the database. For example, you can convert a Unix timestamp to a date:

import {EntityCallbacks, EntityOnFetchProps} from "@firecms/cloud";

const exerciseCallbacks: EntityCallbacks = {
    onFetch({
                collection,
                context,
                entity,
                path
            }: EntityOnFetchProps) {
        const values = entity.values;
        if (values.createdOn) {
            values.createdOn = new Date(values.createdOn);
        }
        return entity;
    }
};

Converting data types when saving to the database

You can use the onPreSave callback to convert the data type when saving to the database. In this case, you can convert a date to a Unix timestamp:

import {EntityCallbacks} from "@firecms/cloud";

const exerciseCallbacks: EntityCallbacks = {
    onPreSave: ({
                    collection,
                    path,
                    entityId,
                    values,
                    status,
                    context
                }) => {
        if (values.createdOn) {
            values.createdOn = values.createdOn.getTime();
        }
        return values;
    }
};

Putting it all together

You can use the exerciseCallbacks in your collection definition:

import {buildCollection, EntityCallbacks, EntityCollection, EntityOnFetchProps} from "@firecms/cloud";

const exerciseCallbacks: EntityCallbacks = {
    onFetch({
                collection,
                context,
                entity,
                path
            }: EntityOnFetchProps) {
        const values = entity.values;
        if (values.createdOn) {
            values.createdOn = new Date(values.createdOn);
        }
        return entity;
    },
    onPreSave: ({
                    collection,
                    path,
                    entityId,
                    values,
                    status,
                    context
                }) => {
        if (values.createdOn) {
            values.createdOn = values.createdOn.getTime();
        }
        return values;
    }
};

// in order to use this collection with callbacks, add it to the collection definitions in the main app configuration
export const exerciseCollection: EntityCollection = buildCollection({
    name: "Exercises",
    path: "exercises",
    callbacks: exerciseCallbacks,
    properties: {
        name: {
            title: "Name",
            dataType: "string",
            validation: {
                required: true
            }
        },
        createdOn: {
            title: "Created on",
            dataType: "date", // this is the data type that will define the created views
            validation: {
                required: true
            }
        }
    }
});