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.

what are extension

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 two steps:

  • Merge field’s UI and functions with Contentstack
  • Enable field data syncing with Contentstack

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.

Contentstack also lets you include its design stylesheet within the custom field, so that your custom field’s design blends smoothly with Contentstack’s default UI.

You need to include the JS SDK and Contentstack’s CSS styleguide in the index.html file.

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

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://www.contentstack.com/sdks/contentstack-ui-extensions/dist/latest/ui-extension-sdk.js"></script>
    <link href="https://www.contentstack.com/sdks/contentstack-ui-extensions/dist/latest/ui-extension-sdk.css" rel="stylesheet" type="text/css" media="all">
</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 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;
          // Get current color field value from Contentstack and update the color picker input element
          colorPickerElement.value = extensionField.field.getData();
      })

The above snippet initialises Contentstack SDK, fetches the current color value from Contentstack using the getData() function and assign the value to the color picker element. Once the custom field is initialised, 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 you custom field is ready. It’s now time to deploy it on Contentstack.

Step 3 - 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 two options, select Custom Field.
    Select 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 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 ‘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
  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 two 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 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
  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 an custom field source doc cannot exceed 500 KB. Check the Limitations section for more limitations.

Once you 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. Set the properties of your Custom field. Learn more about these properties.
    Set properties for the Extension field - Color Picker.png
  4. Select the custom field that you created. Add other fields as required.
    Select the Extension - 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 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 option 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.
  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. Set the properties of your Custom field. Learn more about these properties.
    Set properties of the Extension field.png
  4. Select the custom field that you created. Add other fields as required.
    Select the Extension - Ace Editor.png

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 an custom field file cannot exceed 500 KB
  • The title you provide to an custom field cannot exceed 256 characters
  • You can install maximum 50 extensions (including custom fields and custom widgets) in a stack
  • The 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
  • Internally hosted custom fields are not supported on Internet Explorer and Microsoft Edge as these browsers lack support for the <iframe> srcdoc attribute. Read more.

Helpful links

Was this article helpful?
top-arrow