Custom Fields

Create custom fields that you can use in your content types. So, apart from using the default fields such as ‘Single-line textbox’, ‘Rich text editor’, and ‘Number’, you can add your own custom fields to Contentstack such as color picker, code editor, video selector, and more.

How the Group Field Works.png

Add Custom Fields

There are two ways to add custom fields to your content types:

You can create new custom fields by writing your custom code, or you can use the prebuilt templates by modifying the given code to suit your requirements. Let’s look at both the methods in detail.

Create new custom fields

In this guide, we will learn how to develop a new custom field from the ground up.

We have step-by-step custom field setup guides for some popular third-party apps. The details can be found in the corresponding articles given in the list below. Or you can refer to our general guide on creating a custom field.

Guides for specific custom fields:

General guide on creating custom fields:

Step 1 - Create Field UI

The first step is creating the visual part of the field. It involves entering the code of your custom field in an HTML file in the format given below:

index.html

<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
</head>
<body>
     <input type="color" id="html5colorpicker">
</body>
</html>

Step 2 - Plug field into Contentstack

Once you create your field’s UI, you need to integrate that field into Contentstack. This involves three steps:

  1. Merge field’s UI and functions with Contentstack
  2. Add Contentstack's design stylesheet
  3. Enable field data syncing with Contentstack

1. Merge field’s UI and functions with Contentstack
Contentstack provides Custom Field SDK that houses all the functions and methods that you will need to build powerful custom fields. This SDK is the bridge between your custom field and Contentstack. Your custom field code communicates with Contentstack through this SDK.

You need to include the JS SDK in the index.html file as follows:

<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <script src="https://unpkg.com/@contentstack/ui-extensions-sdk@2.1.0/dist/ui-extension-sdk.js"></script>
</head>
<body>
     <input type="color" id="html5colorpicker">
</body>
</html>

2. Add Contentstack's design stylesheet
Contentstack also lets you include its design stylesheet within the custom field. Though using our style guide is optional, we recommend that you include it so that your custom field’s design blends smoothly with Contentstack’s default UI.

Similar to the JS SDK, you need to include Contentstack’s CSS styleguide in the index.html file as well.

<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <script src="https://unpkg.com/@contentstack/ui-extensions-sdk@2.1.0/dist/ui-extension-sdk.js"></script>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/@contentstack/ui-extensions-sdk@2.1.0/dist/ui-extension-sdk.css">
</head>
<body>
     <input type="color" id="html5colorpicker">
</body>
</html>

3. Enable field data syncing with Contentstack
You will need to perform a couple of steps to ensure that the field data syncs with Contentstack automatically, whenever the field is used in a content type/entry. These steps are initializing the SDK and adding the logic of your custom field.

<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <script src="https://unpkg.com/@contentstack/ui-extensions-sdk@2.1.0/dist/ui-extension-sdk.js"></script>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/@contentstack/ui-extensions-sdk@2.1.0/dist/ui-extension-sdk.css">
</head>
<body>
    <input type="color" id="html5colorpicker" onchange="colorChange()">
    <script>
      // initialise Field Extension 
      window.extensionField = {};
      // find color input element 
      var colorPickerElement = document.getElementById("html5colorpicker");
      ContentstackUIExtension.init().then(function(extension) {
          // make extension object globally available
          extensionField = extension;
          // Get current color field value from Contentstack and update the color picker input element
          colorPickerElement.value = extensionField.field.getData();
      })
        // On color change event, pass new value to Contentstack
        function colorChange(){
          extensionField.field.setData(colorPickerElement.value);      
        }        
    </script>
</body>
</html>

Let’s break down the above code into small snippets and understand what they do:

onchange="colorChange()"

Update the color input element and add the onchange event handler.

window.extensionField = {};

Define the custom field extension object globally.

var colorPickerElement = document.getElementById("html5colorpicker");

Find the input element and store it as a global variable. This will be used in the colorChange event handler.

ContentstackUIExtension.init().then(function(extension) {
    // make extension object globally available
    extensionField = extension;

    // update the field height
    extensionField.window.updateHeight();

The above snippet first initializes the Contentstack SDK. Then, it calculates the color picker palette’s height and sets the container height to this value.

    // Set default color in Contentstack
    var defaultColor = extension.fieldConfig.default_color || extension.config.default_color;

    if(!extensionField.field.getData()){
        extensionField.field.setData(defaultColor);
    }

Use the above snippet to set the default color. You need to inform the extension about which ‘config parameters’ to refer. Here, it will first consider the instance-level config parameter, if defined. Else, it will apply the default config parameter that you set while creating the custom field extension.

    // Get current color field value from Contentstack and update the color picker input element
    colorPickerElement.value = extensionField.field.getData();
})

Finally, fetch the current color value from Contentstack using the getData() function and assign this value to the color picker element. Once the custom field is initialized, a callback function is returned with the custom field object.

In the above code
- extension represents the instance of the Custom Field Extension
- extensionField returns the Field object that provides the function to get and set data in your custom field

See the Custom field extension API requests for more details.

function colorChange(){
   extensionField.field.setData(colorPickerElement.value);      
}

Set new color value in Contentstack using the setData() function.

With this, the code for your custom field is ready. It’s now time to deploy it on Contentstack.

Step 3 - Set up the configuration

Pass the necessary configuration parameters for your Custom Field. These parameters will be applied globally to every instance of the Custom Field Extension within a stack.

Alternatively, you can also define different configuration parameters for specific instance of your Custom Field extension. These instance-level configuration parameters will be applied only to that instance of the Custom Field, and will not affect any other instances of that Custom Field. To know more about it, read the Config Parameters section.

Step 4 - Deploy field

There are two ways to deploy your custom field on Contentstack:

Let’s understand the two methods in detail.

Hosted externally
This method is suitable if you do not want to host the custom field extension code on Contentstack, but on an external server. In this case, you need to provide the URL of your externally-hosted extension. Let’s look at the steps involved in deploying the custom field extension in Contentstack through this method.

  1. Go to Settings > Extensions.
  2. Click + Add Extension and select Create New.
  3. From the three options, select Custom Field.
    Select Extension Type - Custom Field.png
  4. On the page that appears, enter values in the fields as given below:
    • Title: Provide a suitable title for your custom field. This title will be visible when you select the extension in the custom field in your content type.
    • Field data type: Select the data type in which the input data of the field should be saved in Contentstack. Select ‘Text’ in this case.

      Note: We only support these data types: Text, Number, Date, Boolean, and JSON.

    • Multiple: Select this if your custom field accepts multiple values, and the data type is not JSON.
    • Hosting method: Select ‘External Hosting’ as the hosting method for this content type.
    • External hosting URL: Specify the URL of your externally-hosted custom field code.
    • Config Parameter: If you want to provide any config parameters in the source code, specify the value of the parameters in the ‘Config Parameter’ field.
      Hosted Externally.png

      Note: The settings provided in this field will act as the default configuration settings for all the instances of the custom field within the stack.

      If you want to provide alternative configuration settings for specific instances of your custom field, you can provide them in the Properties section of the specific instance of the custom field, when setting up the content type.

      However, for your instance-level configurations to be applicable, you need to mention in your custom field extension code to give precedence to and apply these parameters, if provided. Read more.

  5. Click ‘Save’. This will create your custom field.

Hosted on Contentstack
Through this method, you can host your custom field code on Contentstack. Let’s look at the steps involved in deploying the custom field extension in Contentstack through this method.

  1. Go to Settings > Extensions.
  2. Click + Add Extension and select Create New.
  3. From the three options, select Custom Field.
  4. On the page that appears, enter values in the fields as given below:
    • Title: Provide a suitable title for your custom field. This title will be visible when you select the custom field in your content type.
    • Field data type: Select the data type in which the input data of the field should be saved in Contentstack. Select ‘Text’ in this case.
    • Multiple: Select this if your custom field accepts multiple values, and the data type is not JSON.
    • Hosting method: Select ‘Hosted on Contentstack’ as the hosting method for this content type.
    • Extension source code: Enter your custom field code here. For this example, paste the code that we created in the previous steps.
    • Config Parameter: If you have used any config parameters in the source code, specify the value of the parameters in the ‘Config Parameter’ field. For example, if you have used ‘config.secret’ in the source code, specify ‘secret:abcd1234’ in the ‘Config Parameter’ field.
      Color Picker Edit Page.png

      Note: The settings provided in this field will act as the default configuration settings for all the instances of the custom field within the stack.

      If you want to provide alternative configuration settings for specific instances of your custom field, you can provide them in the Properties section of the specific instance of the custom field, when setting up the content type.

      However, for your instance-level configurations to be applicable, you need to mention in your custom field extension code to give precedence to and apply these parameters, if provided. Read more.

  5. Click ‘Save’. This will create your custom field.

Note: Custom field extension hosted internally on Contentstack are uploaded using the <iframe> srcdoc attribute, which is not supported on Internet Explorer and Microsoft Edge. Also, the maximum size of a custom field source doc cannot exceed 500 KB. Check the Limitations section for more limitations.

Once your custom field is created by any of the methods, you will be able to use the custom field in your content types.

Step 4 - Use Custom Field in Content Types

Once you have added a custom field, you can use it in your content type like any other field. Let’s look at the steps involved in using the custom field.

  1. Create a content type.
    Create Content Type.png
  2. Add the ‘Custom’ field in your content type.
    Add 'Custom Field'.png
  3. Select the custom field that you created. Add other fields as required.
    Select 'Color Picker' from the dropdown.png
  4. You can provide specific configuration settings for your custom extension field within the Config Parameters field. This setting will be applicable to only this instance of the Custom Field. properties.
    Fill properties for 'Color Picker'.png

Now, when you create an entry for that content type, you will see your custom field in action.

Color Picker Demo.png

Use prebuilt templates

Contentstack provides several prebuilt custom field templates so that you can get started instantly instead of writing code. You just need to configure these templates a bit and get started.

Below is a list of some of the popular custom field templates:

In order to use a pre-built custom field, follow the steps given below:

  1. Go to Settings > Extensions
  2. Click + Add Extension and select Use prebuilt.
  3. Select Custom Field from the dropdown.
  4. Select any one of the options from the given Prebuilt custom fields. For example, ‘Ace Editor’.
  5. Click Add. You will then see the Extension configuration page where you need to configure the following:
    • Title: You will see a predefined title. This title can be used when adding the custom field in your content type.
    • Field Data Type: Based on the custom field you selected, you will see a field data type assigned for your input data.
    • Hosting method: The hosting method will be set to ‘Hosted By Contentstack’ since it’s a custom field hosted on Contentstack.
    • Extension Source Code: You will find the source code for your custom field. You can make changes to this code as per your requirements.
    • Config Parameter: You can provide your configuration parameters if needed.

      Note: The settings provided in this field will act as the default configuration settings for all the instances of the custom field within the stack.

      If you want to provide alternative configuration settings for specific instances of your custom field, you can provide them in the Properties section of the specific instance of the custom field, when setting up the content type.

      However, for your instance-level configurations to be applicable, you need to mention in your custom field extension code to give precedence to and apply these parameters, if provided. Read more.

  6. Click on ‘Save’. This creates your custom field.

Now, let’s understand how you can start using the custom field in your content type.

Use Custom Field in Content Types

Once you have added a custom field, you can the associated custom field in your content type, like any other field. Let’s look at the steps involved in using the custom field.

  1. Create a content type.
    Create Content Type.png
  2. Add the ‘Custom’ field in your content type.
    Add 'Custom Field'.png
  3. Select the custom field that you created. Add other fields as required.
    Select 'Ace Editor' from the dropdown.png
  4. You can provide specific configuration settings for your custom extension field within the Config Parameters field. This setting will be applicable to only this instance of the Custom Field. Refer Config parameters section.

Now, when you create an entry for that content type, you will see your custom field in action.

Ace Editor Demo.png

Limitations

The limitations to using custom fields are as follows:

  • The maximum size of a custom field file cannot exceed 500 KB
  • The title you provide to a custom field cannot exceed 256 characters
  • You can install maximum 50 extensions (including custom fields and custom widgets) in a stack
  • The maximum size of the configuration file of a custom field cannot exceed 10 KB
  • The maximum size of a custom field file that uses JSON Data Type cannot exceed 10 KB
  • JSON object key(s) cannot start with a dollar '$' sign or contain a dot '.' character.
  • Internally as well externally hosted custom fields are not supported on Internet Explorer and Microsoft Edge as these browsers lack support for the <iframe> srcdoc attribute. Read more.
  • Extensions are loaded in an iframe in sandbox mode for security reason. Hence, the cookies are not exposed. However, as popups are allowed in the current sandbox mode, you can open the popup window and access the cookies or storage in the popup window.
Was this article helpful?
top-arrow