Custom Fields

A field in Builder is a piece of data on a model. For example, the built-in Page model comes with two fields, a Title and a Description. These two fields help define what a Page is. Any time you make or edit any kind of model in Builder, you have the option of editing fields or adding custom fields.

The following video shows some example custom fields on the three kinds of models in Builder: the Page, Section, and Data models.

Overview of custom fields

Custom fields are fields that you add to a model. You can add custom fields to models you create or to an existing model, such as the built-in Page model. All kinds of Builder model accept custom fields, so you can add the fields you need to Page models, Section models, and Data models.

Examples of custom fields include data such as title, URL, name, timestamp, or any piece of data you want to define on a model. You define and specify aspects of your custom fields such as:

• Type: There are many types available in Builder.
• Localization: Translate fields according to region settings.
• Default value: Pre-populate the custom fields you create.
• Helper text: Give your users a helpful hint about what to enter into the field.
• Required: Make a field required or optional.
• Enum: Give users a predefined list of options.
• Hidden: Make a given field hidden when editing content.

The following video shows where to find custom fields on a model, points out the available field Types, and then shows Page and Section custom fields in the Visual Editor's Option tab.

Adding custom fields to a model

You can add custom fields to any model in Builder by doing the following:

1. Open the Model.
2. Click the Edit Fields button.
3. Click + New Field.
4. Name the field.
5. Choose a Type.
6. Configure any other settings for the field and add additional fields as needed.
7. Scroll to the top and click Save.

The following video shows adding a custom field called name and type to a model.

For Pages and Sections, the custom fields you create display in the content entry on the Options tab as in the following image.

For Data, the custom fields you create on the Data model are available in the Data entry. For example, a hypothetical Blog Author Data model has three custom fields, Name, Photo, and URL. The following video shows the custom fields on the Data model and using those fields in a Data entry for a new Blog Author.

To delete a custom field, click the x to the right of the field.

Using field values in your code

When you have custom fields on your model you can add specific values to the content and use those values however you want in your code.

Querying by field values

You can also filter content by using queries with your custom field values. This technique is useful if you want to retrieve content that only has a certain custom attribute. For example, you could filter for only entries that have a certain Canonical URL. For more information on how to use queries on your API calls, refer to Content API and the HTML API or in the options object of any JS SDK.

Custom field types

The following table describes each Type in Builder along with an image of how each Type renders in the Builder UI.

1. Text
   Text is analogous to the text type in HTML. With the Text type, you can specify minimum and maximum length.
2. Select
   Creates a select in content entries. With a select, teammates can choose from options you provide.
3. Long Text
   Long Text accommodates multi-line text. With the Long Text type, you can specify minimum and maximum length.
4. URL
   The URL Type accommodates a URL, also known as a web address.
5. File
   Use the File Type to specify what kind(s) of file a user may upload to a custom field.
6. Number
   The Number file type specifies that the value that the user enters must be a number.
7. Boolean
   The Boolean Type provides a toggle for a true/false setting.
8. Rich text/HTML
   The Rick text/HTML Type provides a rich text interface with styling options and a toggle to write directly in HTML. Click the code icon, <>, at the upper right to toggle the HTML editor.
9. Date
   Use the Date Type to accept a date from the user. When the user clicks on the input, a datepicker opens
10. Timestamp
    Use the Timestamp Type to accept a date from the user. When the user clicks on the input, a date picker opens with a time picker. Though the Date and Timestamp Types appear similar, prefer Timestamp querying.
11. Color
    Use Type Color to provide users with a color picker.
12. List
    Use the List Type when for a series of items.
13. Reference
    Use the Reference type when you have Data entries that users choose from. For example, you could have a Blog Author custom field and when you click the Choose Entry button, all Blog Author Data entries display.
14. Map
    Text
    Use the Map type when you want users to provide a collection of key-value pairs.
15. JavaScript
    Use the JavaScript type so users can provide JavaScript code snippets.
16. Code
    Text
    Use the Code type for accepting JavaScript, HTML, CSS, or other type of code.
17. Tags
    Use the Tags type for adding Tags. The field is empty by default. To add tags, type the tag you'd like and press Enter. Click the x to delete a tag.

Field Validations

Field validation is useful when we need to validate the user input in the builder visual editor. It allows us to throw an error & restrict the person to publish the content unless the error has been resolved. There are two ways through which we can validate the custom fields. Custom field options & Validation hook.

Custom Field Options

Custom field options is the easiest way to add the validation to our custom field. It is limited to the basic validation however, that's an ideal choice if we don't need any complex condition for our input validation.

• First we'll select the model settings.
• We will then go to the Fields tab.
• Select the desired field.
• Scroll down & click the more options.
• Finally, we will see the input fields to add validation for our custom field.

we can add the regular expression pattern & Character limits for the custom input fields & when we're done with it, we can save it.

Validation Hook

Custom field option is a simple solution but for the more complex validation we have to add the validation hook to validate our custom field. It allows us to write the JavaScript code for validation, which opens the endless possibility for validating our input fields.

• Select the Advanced tab instead.
• Scroll down to the bottom & You'll see the Validation hook.
• Click on edit button right next to it.
• You'll be prompt with the screen similar to the given image, where you can write your custom JavaScript logic to validate the custom field.
• After you're done writing click the cross icon in the top right side.
• Finally, save the settings to see the effect.