Guide to Build Your First Simple App

In this section, we will learn how to build a simple “Color Picker” application using the Contentstack app framework. This will enable a custom field UI location in the stack, which provides a native color picker polyfill that Contentstack users can use as an input field within a content type.

This step-by-step guide explains how to create a Color Picker custom field app for your content types.

Prerequisites

Contentstack account with access to Developer Hub
Organization or stack admin access
Node.js version 12 or above
Understanding of App SDK
Understanding of React.js
Venus Component Library for designing UI

Setup a New React Project
1. The first step is to set up a new project that can be used as the app code in the app. You can either download the boilerplate zip or set up your project from scratch using the App SDK.
2. Switch to the project directory from CLI:
This hosts your application on http://localhost:3000. We can now use this URL to register the application.
Register the App
To register your app with Contentstack, log in to your Contentstack account and follow the steps given below:
1. On the left navigation panel, you will find an icon for Developer Hub (as shown below). Click the icon to go to the Developer Hub.
2. Click the + New App button.
3. In the New App modal that appears, enter the following details:
4. Click the Create button.
5. On the Basic Information screen, you can view the details about your app.
Configure UI Locations
In the configure UI locations section, you can add and configure UI locations for your application. Since we are creating a color picker custom field, we’ll add and configure the custom field UI location.
1. On the left navigation panel, click the UI Locations tab.
2. Enter the App URL. This is the same URL, where your app is hosted. In this case, it is http://localhost:3000.
  
  The App Location(s) section is enabled once you enter the App URL.
3. Hover over the Custom Field UI Location, and click the + Add button.
4. Configure the Custom Field meta information.
5. Click Save to save your UI location details in the manifest.
On saving, you will be directed to the UI Locations page. You will see that one location has been configured in the App Locations section.
Install the App
Now that you have configured your custom field location, you need to install the app. Installing the app will make it available in the specific stack you select.
1. Click the Install App button in the top right corner.
2. Select the stack within which you want to install the Color Picker app. Check the terms of service checkbox and click Install.
3. You will be redirected to the installed apps page in Marketplace, where you can see all the installed apps in your organization.
4. Now that your app is installed in your stack, the custom field from boilerplate is ready to use.
Use Color Picker as a Custom Field
Your Color Picker app is now installed within your stack, but to use it, you need to add it within your content type. Open the stack in which you have installed the Color Picker app and follow the steps given below:
1. Click the “Content Models” icon on the left navigation panel, and click the + New Content Type button.
2. Create a content type by adding relevant details as displayed below:
3. In the Content Type Builder page, add the Custom field to your content type by clicking the “Insert a field” link denoted by a + sign.
4. Name your custom field and configure other properties of your custom field. Under Select Extension/App, select the Color Picker custom field you created.
5. After adding the fields, click either Save or Save and Close to save your changes.
To use the Color Picker app, create an entry for this content type, and you will see the this field on your entry page as shown below:
At this point, the code does not show the color picker app and should just show an error message. Now let's add the actual color picker code to the app.

Update the Code and Test

Now that you have installed the Color Picker app, you need to add the color picker code and update the boilerplate code to suit your application.

Add the Color Picker type to the Type file in /ui/src/common/types/index.ts

export interface ColorPickerData {
    showPicker: boolean;
    pickerColor: {
        r: any;
        g: any;
        b: any;
        a: any;
    };
}

In the /ui/src/containers/CustomField/index.tsx file, replace the custom field code with the code given below:

/* Import React modules */
import React, { useEffect, useState } from "react";
import { SketchPicker } from "react-color";
import reactCSS from "reactcss";
/* Import other node modules */
import { InstructionText } from "@contentstack/venus-components";
import ContentstackAppSdk from "@contentstack/app-sdk";
/* Import our modules */
import localeTexts from "../../common/locale/en-us";
import { TypeSDKData, ColorPickerData } from "../../common/types";
/* Import node module CSS */
/* Import our CSS */
import "./styles.scss";

const CustomField: React.FC = function () {
    const [state, setState] = useState<TypeSDKData>({
        config: {},
        location: {},
        appSdkInitialized: false,
    });

    const [stateColor, setColor] = useState<ColorPickerData>({
        showPicker: false,
        pickerColor: {
            r: "108",
            g: "92",
            b: "231",
            a: "100",
        },
    });

    const styles = reactCSS({
        default: {
            color: {
                width: "70px",
                height: "30px",
                borderRadius: "4px",
                background: `rgba(${stateColor.pickerColor.r}, ${stateColor.pickerColor.g}, ${stateColor.pickerColor.b}, ${stateColor.pickerColor.a})`,
            },
        },
    });

    const togglePickerVisibility = () => {
        setColor((prev) => ({
            showPicker: !prev.showPicker,
            pickerColor: prev.pickerColor,
        }));
    };

    const closePicker = () => {
        setColor((prev) => ({
            showPicker: false,
            pickerColor: prev.pickerColor,
        }));
    };

    const pickerColorChanged = (colour: any) => {
        setColor((prev) => ({
            showPicker: prev.showPicker,
            pickerColor: colour.rgb,
        }));
        state.location?.CustomField?.field?.setData(colour);
    };

    useEffect(() => {
        ContentstackAppSdk.init().then(async (appSdk) => {
            const config = await appSdk?.getConfig();

            setState({
                config,
                location: appSdk.location,
                appSdkInitialized: true,
            });

            appSdk.location.CustomField?.frame?.updateHeight?.(300);

            const initialData = appSdk.location?.CustomField?.field?.getData();

            if (initialData?.rgb) {
                setColor({
                    showPicker: false,
                    pickerColor: initialData.rgb,
                });
            }
        });
    }, []);

    return (
        <div className="layout-container">
            {state.appSdkInitialized && (
                <div>
                    <InstructionText testId="color-picker-text">
                        {localeTexts.customField.instruction}
                    </InstructionText>
                    <div>
                        <div className="swatch" role="none" onClick={togglePickerVisibility} onKeyDown={togglePickerVisibility}>
                            <div style={styles.color} />
                        </div>
                        {stateColor.showPicker ? (
                            <div className="popover">
                                <div className="cover" role="presentation" onClick={closePicker} onKeyDown={closePicker}>
                                <SketchPicker color={stateColor.pickerColor} onChange={pickerColorChanged}/>
                            </div>
                            </div>
                        ) : null}
                    </div>
                </div>
            )}
        </div>
    );
};

export default CustomField;

In the /ui/src/containers/customField/style.scss file, replace custom field CSS with the code given below:

.config-wrapper {
    .Form__item {
        width: 500px;
    }
    .tippy-wrapper {
        margin-right: 10px;
    }

    .radio-wrapper {
        padding: 20px 10px;
    }

    .radio-button {
        margin-right: 20px;
    }

    .toggle-save-response {
        padding: 20px 10px;
    }
 }

.swatch {
    padding: 5px;
    background: #fff;
    border-radius: 1px;
 }

Add new strings to locale to customField node in locales in /ui/src/common/locale/en-us/index.ts

instruction: "Pick a Color",

In package.json, add the additional libraries used above:

$ npm install reactcss react-color
$ npm i --save-dev @types/react-color

Stop and restart your React project:

$ npm run dev

Reload the entry page, and now you will see an actual Color Picker loaded into the custom field.

Save any color and reload, and verify if the app is saving data and fetching it on reload.

Next Steps
1. Secure your application:
  Using the signed support, you can learn how to secure calls to outgoing APIs from the Contentstack UI and backend using the Contentstack App Framework.
2. Host the app:
  The Contentstack App Framework allows you to host your app on Contentstack. Check out how to deploy your code to Contentstack and use it in the app.
3. Submit for publishing:
  Once your application is production-ready and you want to share your solution with Contentstack Marketplace, you can check the App Submission and Approval Guide.

Guide to Build Your First Simple App

Prerequisites

Overview of steps:

Setup a New React Project

Register the App

Configure UI Locations

Install the App

Use Color Picker as a Custom Field

Update the Code and Test

Next Steps

More articles in "Quickstart"

On This Page