Configure properties

Properties are key elements in Optimizely Content Management System (CMS). Content type properties store and present data, such as page types and block types, and they are fields where editors enter information into a page type. A property can be the page name, an image placeholder, or the editor area, where you can add text. For example, the XHTML editor is a property of the type XHTML String (>255), which results in an editorial area in the page type when used. For property content to be visible to visitors, link it to a content type with the corresponding rendering. See also Develop properties.

🚧

Important

Dynamic Properties were removed in CMS 13. If your implementation references DynamicProperty, DynamicPropertyCollection, or any related APIs, remove those references before upgrading. No replacement feature is available. Use standard content type properties or custom data stores instead.

Property types

Property types determine the data each field stores and how editors interact with it. Choose the right type to match the editorial experience and the rendered output.

Define properties in code or from Settings > Content Types > {select content type} > Properties. You can create "non-breaking" changes in the Settings view for certain properties defined in code to override these settings. Information displays if a property is defined in code and cannot be changed in the Settings view. If you change a property defined in code, you can reset the changes to the values defined in code.

The following types of properties are used:

• Built-in properties – Set by the system and are automatically available for pages and blocks regardless of type. For example, PageName (name of the web page) and PageStartPublish (start publish date for the page).
• User-defined properties – These are added to the page or block type definition in code or from the admin view. Typical examples are Heading and MainBody.

Locate property settings at Settings > Content Types > {select content type} > Properties when you work with content types. 

Create page properties

Create page properties to define the editable fields on a page type. Page properties give editors the inputs required to author content for a specific template.

1. Select Create New > Page Type (or Block Type) from the Content Type tab in the Settings view.

   

2. Enter the page information.

   

3. Select Add Property to define the properties for the page type. See the following section for more details about adding a property.

   

Add a property

Add a property to extend a content type with the fields editors need to capture data. Adding properties shapes the authoring experience and the structured data published through the CMS.

1. Select a content type from the list and click Add Property on the Content Type tab in the Settings view. 

2. Select the property type you want. 

   

   The legacy content types are not available in CMS 13. Use the primary content types; legacy content types are removed in a future release.

   

   Change the type in the Configure Property panel.

   

3. Fill in the fields in the Configure Property view.

   

   Each type may have different validations display. The following fields belong to the Content type.

   • Name – Name the property. This is used when programming and making language settings.

     📘

     Note

     CMS 13 enforces strict naming conventions for property identifiers. Names must match the pattern ^[A-Za-z][0-9A-Za-z]+. That is, they must start with a letter, contain only letters and digits, and be between 2 and 255 characters in length. Spaces, hyphens, underscores, and other special characters are not permitted. Use the Display name field to provide a human-readable label for editors.

   • Type – Select a property type. You can choose from several property types: integer, string, page, date, and so on. You can also create a property type.

     When you select a basic data Type, you also select its subtype. For example, if you select Content, you also select the Content Type (Content Area, Content Area Item, or Content Reference); if you select Text, you also select the Text Type (Long string (>255), String (<=255), or XHTML string (>255)), and so on.

     When you select Content Type, also specify Allowed Content Types or Restricted Content Types that an editor can see for this property.

     

   • Value must be entered – Select the checkbox to make it mandatory to enter a value for the property before saving. The setting is configured per property and content type.

   • Unique value per language – Select whether the property is unique for a certain language. This is needed only if the website supports globalization.

   • Searchable property – Controls whether the property's value is included in the search index.

     📘

     Note

     In CMS 13, the Searchable attribute on property definitions is replaced by the IndexingType attribute. Use [IndexingType(IndexingType.Included)] to include a property in the index, or [IndexingType(IndexingType.Excluded)] to exclude it. The legacy [Searchable(false)] attribute is no longer supported. Clear this check box in the admin view (or set IndexingType.Excluded in code) to exclude a property from the search index. For example, this prevents undesired property values from appearing in search results.

     
     

   • List – Select to make the property a list property. This displays only for some properties.

   • Default value – Select a value for the property: No default value, Inherits value, or Custom properties.

     📘

     Note

     Default values can be defined in code using the [DefaultValue(...)] attribute on a property, in addition to the admin view. The [DefaultValue] attribute sets the value used when a new content instance is created. Admin view default value settings take priority over code-defined defaults where both are present.

   • Display in edit view – Select whether the property is visible. By default, all properties are visible in the editorial interface. The setting is configured per property and page type.

   • Display name – Specify a heading for the property. This text displays for the editor when editing the page in the All Properties view unless a translation was added to language resources.

   • Help text – Specify a help text to help the editor understand how to use this property, and it displays in the All Properties view when hovering over the property name.

   • Sort index – Select a relative number to sort this property among other properties.

   • Tab – Select the tab on which the property will be displayed in the Tab drop-down list.

4. Click Save.

The Custom Settings tab displays custom information for the selected property type.

Typed content references

ContentReference<T> is a strongly typed variant of the standard Content Reference property. Specifying the type parameter T restricts the property to accept only content of a specific type, improving type safety and enriching the Optimizely Graph response.

When you define a Content Reference property and set the Reference Type to a specific content type (other than Any):

• The content picker in the editor is limited to content matching the declared type T.
• Optimizely Graph returns the full typed object. For example, a ContentReference<ContactBlock> property returns all fields of ContactBlock (such as name and email), rather than only contentLink.
• When Reference Type is set to Any with allowed content types, Graph returns only contentLink.

Define a typed reference in code

// Restricts the picker to ContactBlock instances only
[Display(Name = "Contact", Order = 100)]
public virtual ContentReference<ContactBlock> Contact { get; set; }

// Restricts the picker to any type implementing IProductContract
[Display(Name = "Featured Product", Order = 110)]
public virtual ContentReference<IProductContract> FeaturedProduct { get; set; }

Configure a typed reference from the admin view

Configure typed references in the admin view to constrain a Content Reference property to a specific type without redeploying code. This keeps the editor picker focused and ensures Optimizely Graph returns the full typed object.

1. Go to Settings > Content Types and select the content type.
2. Select the property, then open its Configure Property panel.
3. Set Reference Type to Specific Content Type and select the target type or contract from the list.
4. Click Save.

📘

Note

Content type contracts are filtered out of the type picker by default. To type a reference against a contract, explicitly select the contract as the Reference Type.

Graph behavior by reference type configuration

Property type mapping for external content

When integrating external content sources (such as Shopify, Bynder, or other GraphQL-connected sources), the CMS applies less strict type-compatibility rules during property mapping than it does for internal CMS-to-CMS property mapping. This allows a source field of one type to map to a broader set of target CMS property types.

📘

Note

These relaxed mappings apply only to properties sourced from connected external content types. Standard CMS-to-CMS property mappings enforce stricter type compatibility. When mapping ShortString to XHTMLString, the CMS does not HTML-encode the source value. Validate that the external source does not supply HTML-unsafe strings before using this mapping in production.

Mapped properties behave in the following ways:

• Read-only – Properties included in a mapping become read-only in the CMS Edit UI and reflect the external source value directly.
• Editable – Properties excluded from the mapping remain fully editable in the CMS.
• Late additions – If a mapping is updated to include additional properties, those properties automatically become read-only.
• Depth – Mappings support scalar properties inside a block at one level of depth.

Define language-specific properties

When working with globalization, you define which fields in every template vary depending on the language. To do this, set the property for that field to "locked" or "open" for globalization using the Unique value per language setting in the admin view.

Properties with unique values per language are editable in activated languages on the website, which is normally the case. You can edit only properties that do not have language-specific values in the language in which the page was created (the original page language). These properties are deactivated in edit view with an icon indicating the original language.

Imagine the property defining the sort order field is not set as a unique value per language (that is, the Unique value per language check box is cleared). You can set the sort order in the original page language when creating a page. But if you create a version of the page in another language, the sort order field is not editable. As a result, the sort order is the same for activated languages. If you want to change the sort order for each language, select the Unique value per language check box.

❗️

Warning

Existing values are deleted if a property is changed to not having a unique value. So if the property for the editor area is changed not to have a unique language, text entered in the editor area for all languages on the website is permanently deleted.

Set a property to be language-specific

Mark a property as language-specific so editors maintain a distinct value for each activated language. Use this for fields such as headings or body copy that must vary per market.

1. Select the page type that contains the property to be set on the Content Types tab.
2. Click the property name you want to change.
3. Select the Localized option.
4. Click Save.

Place a property on a tab

Group properties under a tab to organize the edit view and help editors find related fields quickly. Tab placement improves the authoring layout for content types with many properties.

1. Select the page type on the Content Types tab.
2. Click the property name you want to modify.
3. Select the tab where the relevant property will be placed from the Tab drop-down list.
4. Click Save.

Configure customized property settings

Customized property settings let administrators tailor property behavior beyond the built-in defaults. Use them to apply consistent validation, defaults, and presentation across content types.

Priorities and configuration

The property settings have the following priority:

1. A specific setting for a property is defined in the admin view. This can be custom settings for this property or pointing to a specific global setting.
2. A specific setting for a property is defined for the model in code.
3. A global setting defined in admin is marked as the Default setting for the property type.
4. A global setting is defined in code.

Create a property, name it, and give it a data type and other settings.

Create custom property types

The list of available custom property types done by a developer has the following columns:

• Name – The name of the content type created by a developer, of which some are selectable in the editorial interface.
• Base type – Shows the built-in types that a developer can extend.
• Class name – Shows the full name of the class. The class is defined in the assembly.
• Assembly name – Shows the class reference. A blank column indicates a built-in property.

A developer can create property data types by inheriting from the existing available ones.

• Boolean (Selected or not selected) – True or false.
• Number (Integer) – An integer.
• FloatNumber (Floating point number) – Number with decimals, for example, 3.14.
• PageType (Page Type) – Optimizely CMS page type defined in admin view.
• PageReference (Page) – Link to an Optimizely page on the current site.
• Date (Date or Time) – Date and time.
• String (String <=255) – Short text, fewer than 256 characters in length.
• LongString (Long String >255) – Used for text exceeding 255 characters, such as the main editor area in edit view.
• Category (Category selection) – List of categories.
• LinkCollection (Link collection) – A collection of links that can be added and edited in edit view.

📘

Note

Default values for properties are not defined in code.

List property examples

When you select the List property box, you can define many list types in the All Properties view of a page. The following examples show the List property examples.

EditorialBlock List type

Click Add Editorial to add another list item; select More (…) > Delete to remove the item.

Enumerable of ContentReference List type

Click Select Content to add another drop-down list item; select More (…) > Delete to remove the item.

Enumerable of ContentReference List type (with PropertyCollection)

Click Select Content to add another list item; select More (…) > Delete to remove the item.

Enumerable of ContentReference List type (with Image UIHint)

Click Add to add another list item; select More (…) > Delete to remove the item.

Enumerable of ContentReference List type (with Video UIHint)

Click Add to add another list item; select More (…) > Delete to remove the item.

DateTime List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Enumerable of int List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Enumerable of int List type (with PropertyCollection)

Click Add to add another list item; select More (…) > Delete to remove the item.

Enumerable of LinkItem List type

Click Add Link to add another list item; select More (…) > Delete to remove the item.

Enumerable of LongString List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Enumerable of PageReference List type

Click Select Page to add another list item; select More (…) > Delete to remove the item.

Enumerable of PageReference List type (with PropertyCollection)

Click Select Page to add another list item; select More (…) > Delete to remove the item.

Enumerable of Url List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Guid List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Inline Block List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Integer List type

Click Add to add another list item; select More (…) > Delete to remove the item.

Integer (read-only) List type

LinkedItem List type

Click Add Link to add another list item; select More (…) > Delete to remove the item.

String List type

Click Add to add another list item; select More (…) > Delete to remove the item.

String List type (only letters)

Click Add to add another list item; select More (…) > Delete to remove the item.

String List type (10 character maximum)

Click Add to add another list item; select More (…) > Delete to remove the item.

XhtmlString List type

Click Add to add another list item; select More (…) > Delete to remove the item.