ℹ️ 2024 April 4th: Archiving the repository since we decided to instead improve the official Contentful Color picker by contributing to their repository.

Adapt Essentials: Colors

This project was bootstrapped with Create Contentful App.

Bug reports

If you've found any issues, please open an issue here: https://github.com/adaptdk/adapt-toolkit-color-picker/issues

Feature requests

If you think the application is missing any features, please open an issue here: https://github.com/adaptdk/adapt-toolkit-color-picker/issues

Table of Contents

1. Examples
   1. Configure via GUI
   2. Configure via JSON
   3. Defined colors in a content field
   4. Validated colors in a content field
2. How to use the Application
   1. After installation, how do I configure the application?
      1. Adding a color bar to a group
      2. Editing a color bar
      3. Removing a color bar
      4. Editing a color group
      5. JSON Editor
   2. How to configure the app on a field?
   3. Validating colors on a field
   4. Querying the field
3. Developing
4. Available scripts
5. Libraries to use
6. Contentful Management SDK
7. Learn more

Examples

Configure via GUI

Configure via JSON

Access all defined colors in a content field

Access only validated colors in a content field

How to use

After installation, how do I configure the application?

Once the application is successfully installed, you will be directed to the configuration screen. There you can find basic instructions on how to start building your design system. In the Editing Options, there will be a preconfigured Default group with a single color inside of it.

Adding a color bar to a group

Clicking the + Add Color button will create a new color in the group

Editing a color bar

To change the label of the color, simply type it in the LABEL field of a color.

To change a color, you have two options:

1. Edit the #HEX value directly in the input field labeled as HEX;
2. Click on the color box to open a color picker;

Removing a color bar

To remove a color bar, simply click the red trash bin icon.

⚠️ Warning: This will remove the color without confirmation!

Editing a color group

To edit settings of a group, simply click the pencil icon in the GROUP SETTINGS "box"

JSON Editor

More advanced users can instead use the JSON Editor to configure their color groups and colors.

Each item's ID is generated via uuidv4.

ℹ️ Pro tip: Instead of generating IDs yourself, create multiple default placeholder items - they will already come with an ID!

How to configure the app on a field?

After you're done configuring your color design system, using it is extremely simple!

1. Create a new Text field in your content type

2. In the newly created field's settings, scroll down to the Appearance section and select Adapt Essentials: Colors

3. After you save your content type, you're done and ready to use the field!

Validating colors on a field

1. Go to your field's settings, scroll down to Validation and select the Accept only specified values checkbox. Simply input the LABEL value of a color and hit enter. In our example, we have a color of "hexColor": "#0f6ad2" and "label": "blue-500", so we're going to input blue-500 in to the validation field.

2. After you save your content type, you're done and ready to use the validated field!

Querying the field

Querying the field is the same as querying a basic text field. So if your field is called color, that's what the API response will respond to.

The returned value is the LABEL, so in our example of "hexColor": "#0f6ad2" and "label": "blue-500", the returned value would be color: 'blue-500'

Developing

Execute create-contentful-app with npm, npx or yarn to bootstrap the example:

# npx
npx create-contentful-app --example vite-react

# npm
npm init contentful-app --example vite-react

# Yarn
yarn create contentful-app --example vite-react

Available Scripts

In the project directory, you can run:

npm start

Creates or updates your app definition in Contentful, and runs the app in development mode. Open your app to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

npm run build

Builds the app for production to the dist folder. It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes. Your app is ready to be deployed!

npm run upload

Uploads the dist folder to Contentful and creates a bundle that is automatically activated. The command guides you through the deployment process and asks for all required arguments. Read here for more information about the deployment process.

npm run upload-ci

Similar to npm run upload it will upload your app to contentful and activate it. The only difference is that with this command all required arguments are read from the environment variables, for example when you add the upload command to your CI pipeline.

For this command to work, the following environment variables must be set:

• CONTENTFUL_ORG_ID - The ID of your organization
• CONTENTFUL_APP_DEF_ID - The ID of the app to which to add the bundle
• CONTENTFUL_ACCESS_TOKEN - A personal access token

Libraries to use

To make your app look and feel like Contentful use the following libraries:

• Forma 36 – Contentful's design system
• Contentful Field Editors – Contentful's field editor React components

Using the contentful-management SDK

In the default create contentful app output, a contentful management client is passed into each location. This can be used to interact with Contentful's management API. For example

// Use the client
cma.locale.getMany({}).then((locales) => console.log(locales));

Visit the contentful-management documentation to find out more.

Learn More

Read more and check out the video on how to use the CLI.

Privacy Policy