Each Content Type field contains a number of properties which define what information can be stored in the field and how it is displayed.
- Property Types
- Specific Cases
- Field Variables
- Variable Names
The following properties exist in every Content Type field.
|Display Type||Drop Down List||Choose the field type|
(Standard, WYSIWYG, Tag and Category, etc.).
|Label||Text||A label or title for the Field.|
This label will be shown to content contributors editing the content in the dotCMS backend.
|Variable/ID||Text (Read-Only)||Displays the variable name used to access this field (in both Velocity code, Elasticsearch queries, etc.).|
Note: This value will only display after the Field has been saved the first time.
The following five properties are standard flags (properties with true or false values), each of which is available in many different field types. Each of these flags affect how the field is stored or displayed in dotCMS:
|Required||Check if the Field is required (e.g. this Field must not be left empty when adding or editing this type of Content).|
|User Searchable||Check to allow users to search the data in the field.|
Fields with this value checked will be individually searchable when searching for content.
If this is checked, the content will automatically be indexed.
|System Indexed||Check to cause the Field to be indexed.|
This improves search performance, but increases the size of the search indexes.
|Show in List||Check to allow the Field to display in the search results list when searching for content.|
|Unique||Check to prevent duplicates in the Field.|
This ensures that no two content items have the same value in this Field.
Different flags are available for different Content Type fields; the following table summarizes the standard flags available for each field type:
|Field Display Type||Required||User|
|Date and Time||Yes||Yes||Yes||Yes||No|
|Site or Folder||Yes||Yes||Indirectly||No||No|
The following field-sepcific properties are available only to certain field types. Which parameters a field has (and which parameters are required) varies depending on the field type.
|Data Type||Radio Button||Format of the data to be stored in the Field|
e.g. Text, Decimal, Whole Number, etc..
|Validation Regex||Text||A regular expression (pre-defined or custom) that limits how data can be entered into the Field.|
For more information please see the Validation Expressions documentation.
|Code/Value||Multiline Text||You must fill out this parameter for some Field types (Radio, Multi-Select, etc.).|
Sample code/instructions are displayed highlighted in yellow to the right of the code field when this is required.
|Default Value||Text||The default value used to automatically populate the Field when a new Content item is added.|
Note: For fields with listed values (such as Select field), the value of the selection (rather than its label) must be used.
|Hint||Text||Instructions to contributors on how to fill out the Field.|
The Hint will be displayed to the content contributor on the Content editing screen.
When adding a new field to a Content Type, some of the above properties are necessary; a field can not be saved unless all necessary fields are filled in. When editing the field properties, necessary properties are marked with an asterisk to the left of their labels, as shown in the Example below.
Some field properties require specific values to handle specific cases.
Creating a Multi-Select Field with No Default Value
By default, the first value in a Multi-Select field is the default value (so when new content items are created, the value of the Multi-Select field will be set to the first value listed unless the user manually changes it).
To force a user to manually select a value from the list (instead of using a default value), do both of the following:
- Add only a pipe (“|“) character as the first choice in the select list (do not include a label or value on either side of the pipe character).
- This configures the Field to have no default value (the user must manually select a value, or no value will be saved).
- Check the Required parameter for the Field, so that the default first “null” choice is not valid.
- This forces the content contributor to click and choose an item from the select list before the content item can be saved.
Multi-select fields do NOT need any special handling. Multi-select fields always force the contributor to choose a value, otherwise the field is left blank.
In addition to the properties available to each field, for many field types you may also add Field Variables, which extend fields of specific Display Types to provide additional functionality. For example, a field of the Binary Display type may be limited to only allow certain types of files to be uploaded, and to limit the size of files uploaded.
To view the Field Variables available for any field type, please view the documentation for that specific field type. The following documentation sections cover some of the most commonly used field variables:
How Field Variable Names are Generated
You can not choose what variable name to give a Field when you first create the Field; the variable name will always be assigned automatically. All variable names are assigned to fields as follows:
- The field variable name will be generated from the name of the field when it is created.
- All spaces and punctuation in the Field name will be removed.
- All letters will be converted to lower-case to create the variable name.
- Double-byte characters are not supported in variable names, and will be replaced with an underscore (
_) in the variable name.
- Unfortunately, this limitation is due to limitations in several of code languages used to access dotCMS content, not due to dotCMS code itself, and can not be changed at this time.
- If a new field results in the same variable name as a the variable name of an existing field, the new variable name will have a number added to the end to distinguish it from the existing variable name.
Field Variable Names Can Not Be Changed
In order to ensure that code which references Field variables does not break when you rename Fields, it is not possible to change the variable name of a Field after the field has been created.
However you can create a Field with one name, and then change the name of the Field after the variable name has been automatically assigned. This allows you to initially create the Field with an appropriate name so that the appropriate variable name is generated, and then change the name of the Field afterward.
Two common cases where this may be useful are:
- If you have a Field with a name other than “Title” which you wish to be treated as the
titlefield (which is automatically indexed for all content, regardless of the Content Type).
- If you wish to create Field names using double-byte characters, but want the variable names to be more descriptive than the automatically generated variable names (consisting of mostly underscores and numbers).
The images below show examples of some of the different field types.
Example 1: Text Field
Example 2: Multi-select Field