Built-in property types

Describes how to use built-in property types in your models and also create your own property types.

Optimizely Content Management System (CMS) content is built up by models with properties that store and present data. You can use many built-in property types in your models and create your own.

You can use most property types as instance or list properties. Some types are list types themselves; those cannot be modeled as lists.

Common property types

What you want to create	Solution	Editing experience
Plain short text – Control the allowed length with the `StringLength` attribute. Use a custom tag to control the containing tag, such as using an H1 for the main header for the page.	`String` property	One row input
Plain long text – Control the allowed length with the `StringLength` attribute.	`String` property with UIHint.Textarea	Text area
HTML	`XHtmlString` property	A TinyMCE HTML editor
Integer value – Controls other rendering, such as the number of items in a list. Control the min and max values with the `Range` attribute.	`Int` property	A number slider
Date and time – Control the min and max values with the `Range` attribute.	`DateTime` property	A date and time picker
Double – Control the min and max values with the `Range` attribute.	`Double` property	Check editor
Boolean	`Boolean` property	Checkbox
Page type – Filter items in a list, and so on.	`PageType` property
BLOB – Hold binary data (such as an image). Route to a BLOB with pattern `<Url to content>/BlobPropertyName`.	`Blob` property

📘
Note
See also Properties in the CMS 12 user guide.

Difference between ContentType and ContentReference

Use ContentType when working with the definition of a content structure. For example, when you need metadata about a page type or block type (name, description, available properties). Developers often use ContentType in scenarios where you need to query or manage content model definitions.

Use ContentReference when you need to work with a specific instance of a content item, such as a particular page, block, or media asset. ContentReference uniquely identifies that content instance in the database.

This distinction ensures that developers use the right property for defining content schemas (ContentType) versus referencing content instances (ContentReference).

Work with other content

To refer to existing content, use the Link or LinkCollection to create internal or external links.

Use Link or LinkCollection to create internal or external links.
Use ContentArea to display content from other content.
Use ContentReference, ContentReferenceList, or Url to link to a single content item of a specified type.
Use the AllowedTypes attribute to restrict the kinds of links that can be added to a property (with some limitations).
A content reference combined with UIHint lets editors select different entities, such as a block, media item, block folder, or media folder.

The editing experience for a ContentArea is user-friendly and designed to empower content editors to create dynamic and engaging digital experiences without requiring extensive technical knowledge. Editors can drag and drop blocks, media, or pages into the content area and reorder or personalize them with ease.

Use a content reference with many UI hints to select different entities in CMS, such as a block, a media item, a block folder, or a media folder.

What you want to create	Solution	Editing experience
Link to a page	`PageReference` property	Content picker with drag and drop support
Link to a media file of any type – Link to any file in the media repository. Use `ContentReference` instead to use standard content rendering. (Mostly for backward compatibility.)	`ContentReference` property with `UIHint.MediaFile`	Content picker with drag and drop support
Link to an image – Lets an editor select content in the media repository by implementing IContentImage.	`ContentReference` property with `UIHint.Image`	Content picker with drag and drop support
Link to a video* – Lets an editor select content in the media repository by implementing `IContentVideo`.	`ContentReference` property with `UIHint.Video`	Content picker with drag and drop support
Link to a media file* with the possibility to append information in the URL – Each link can be an item inside Optimizely CMS, such as pages, media, and external URLs. Use URL instead of `ContentReference` to add information, such as query string parameters to control size.	`Url` property with `UIHint.MediaFile` or `UIHint.Image` or `UIHint.Video`	Content picker with drag and drop support
Content area	`ContentArea` property
URL	`Url` property	Link dialog with drag-and-drop support
Link to multiple external and/or internal resources – Does not support `AllowedTypesAttribute`.	`LinkItemCollection` property	Link collection editor with drag-and-drop support
Link to external or internal resource* – Does not support `AllowedTypesAttribute`.	`LinkItem` property Note:* Available in CMS 12.11.0 and later.	Link editor with drag-and-drop support
Link to multiple internal pages, media files, or other content types* – Supports `AllowedTypesAttribute`.	`ContentReferenceList` property	Content picker with drag and drop support

Select predefined values

You can use the following solutions to create drop-down lists and check box lists:

What you want to create	Solution	Editing experience
Select a single item from a relatively short list of options	String/Int property with SelectOne attribute	Link to implementation page
Select several items from a relatively short list of options	String/Int property with SelectMany attribute	Link to implementation page
Select a single item from a relatively long list of options. – Use with caution because the auto-suggestion editor creates requests to the server.	String/Int property with AutoSuggestion attribute	Link to implementation page

Validation attributes

CMS supports the following validation attributes that are part of the .NET:

Range
StringLength
RegularExpression
EmailAttribute

You can create custom attributes that implement either ValidationAttribute. See Write custom attributes.

Updated 4 days ago