Content types in the UI

Content in Optimizely can be page types and block types, folders, or media files such as images and documents. Content can also be products in a product catalog in Optimizely Commerce Connect. Additionally, developers can create content types through code.

Content types and properties

Content types contain the properties where editors enter information, such as a link to an image on a web page.

The Type column identifies the foundational type each content type inherits from, such as Page, Block, Media, Experience, or Section. Content types whose base type cannot be determined — for example, those registered from a package that has since been removed — display an Undefined label in the Base type column.

For a content type, you define properties that can hold information, such as a link to an image, a web page, or editorial text. A typical website has a set of content types that match the identified functions needed on that website.

The content type is the foundation for creating one or many page or block instances. The page type or block type and its properties must be mapped to the corresponding rendering to display content to visitors.

The content concept in Optimizely Content Management System (CMS) is based on inheritance from a "generic" content type, which is then used to create specific content types, such as a page type or a media folder. Using this feature, developers can create custom content types when they set up new websites.

• You can define page types in code or from the admin view. However, you can define block types only in code.
• For page types defined in code and for all block types, you can define "non-breaking changes" of properties in the admin view.
• You are notified if you cannot change the settings defined in code in the admin view.
• If you change a page type defined in code, you can reset the changes to the original values defined in code.

Page types

❗️

Warning

Changing page type settings may cause the website to stop working. Although you can create page types in the admin view, you should create them from code.

Edit a page type

To edit settings for an existing page type:

1. Go to Settings > Content Types.

2. Select the page type from the list, such as Article. The Properties view displays for the page type.

3. Click Settings and modify the form.

   
   • Name – Enter an internal, programmatic identifier for the content type, often used in development and system configurations. In the image, the name is ArticlePage.
   • Display name – Enter a user-friendly name of the content type that is shown in the user interface. In the image, the display name is Article.
   • Description – This field provides a brief explanation of the content type's purpose or its intended use. The description in the image is Used to publish news articles on the website.
   • Sort index – Enter a numerical value for the order in which the content type appears in lists or menus within the system. A value of 0 is shown in the image.
   • Available in edit view – Select to controls whether content based on this content type can be created and edited by users in the content editing interface.
   • Reset Content Type – Click to discard any changes made to the content type that have not been defined in the underlying code, reverting it to its default, code-based configuration.

4. Click Save.

Because you can identify page types and their properties in code or from the Settings view, you can change some settings from the Settings view. If a page type is created from code, this is shown on the page type information page under General.

📘

Note

You cannot delete certain page types defined in code. These are typically page types upon which other page types are based, such as the standard or default page and the start page.

Using the Access level area, you can define which users or user groups have access to the page type.

Create a page type from the Settings view

1. Go to Settings > Content Types , select  Create New >  Page Type, and modify the form.

   
   • Name – Enter an internal, programmatic identifier for the content type, often used in development and system configurations. In the image, the name is AlloyTech.
   • Display name – Enter a user-friendly name of the content type that is shown in the user interface. In the image, the display name is Alloy Tech.
   • Description – This field provides a brief explanation of the content type's purpose or its intended use. The description in the image is This page will display Alloy technical specifications.

2. Click Create.

3. Set values in the new page Settings tab.

   
   • Name – Automatically filled from the name you entered when you created the page type.
   • Display name – Automatically filled from the name you entered when you created the page type.
   • Description – Automatically filled from the name you entered when you created the page type.
   • Sort index – A number determining the (ascending) sort order in the list of available page types. The default is 0.
   • Available in edit view – Select to make the page type available for selection when creating pages in the editorial interface. You should hide rarely used page types, such as the start page type. You can make these available when needed and then hide them again.

4. Set the values on the Permissions tab.

   You can use the Search box to filter and find users and groups to which you want to give access. Enter partial text to find the users or groups you want.

   

5. Set values on the Default Values tab.

   You can set default values for some of the built-in properties in Optimizely CMS from the admin view. You can also specify default values for the properties from code which are not visible in the admin view.

   
   • Use adjusted default settings for pages using this page type – Select to enable or disable adjusted default settings for pages created with this page type.
   • Visibility – A section for configuring how pages of this type are displayed.
     • Show this page type in navigation (page tree) – Select to control whether pages of this type appear in the navigation tree.
     • Sort index – A field to specify the sorting order.
     • Target Frame – Select the target frame for pages of this type.
   • Children – A section for configuring child pages.
     • Sort subpages – Select to determine how subpages are sorted; default is According to creation date (latest first).
   • Automatically publish – A section for setting automatic publishing rules.
     • Publish after – Select set a rule for when to automatically publish; default is Never.
     • Unpublish after – Select to set a rule for when to automatically unpublish; default is Never.

6. Set values on the Child Content Types tab.

   When creating pages, limit the available page types in the page type list to make it easier for editors to choose the correct page type. For example, for an Alloy Tech parent page, select Selected and then specify that the only available page type is Alloy Tech or Article.

   

7. Click Save.

Copy a page type

When you copy a page type, its properties are also copied. You can then edit the information for the page type and its properties. Copy a page type as follows:

1. On the page type that you want to copy, select More (...) > Copy.

   

2. Copy of... displays in the Copy of Page Type dialog box. Enter the text you want and click Create.

   

3. Edit the page type information to suit your requirements and click Save.

📘

Note

Copied page types are untyped, and you need to add the path to the display template; otherwise, pages based on the page type will not have a preview.

Block types

🚧

Important

Defining a custom block type in the CMS is only the first step. For a newly created custom block to render and appear on a webpage in a PaaS environment, a developer must implement a corresponding MVC View in the website's codebase. This view acts as the rendering component that translates the block's data into visible HTML. Without this developer-side implementation, the block will not be visible on the frontend, even if content editors can create instances of it in the CMS.

A block type is a component that makes up a portion of a web page. It is reusable content you can display with a template. It does not have a URL. It can consist of other block types, content, and media types. The following are some examples of block types:

• A carousel container, used for holding multiple slides.
• A slide used in a carousel.
• A button.
• A navigation menu.
• SEO settings for a page.
• Label dictionary for the application.
• An interactive map.

Block types are similar to page types, and you can modify some settings from the Settings page.

📘

Note

You cannot use blocks with complex types inside (like nested block types) as sections or elements. If you try, the following message displays: Cannot set Enable as Element because this content type contains property type that elements cannot have. (See property 'SiteLogoType')

Create a block type

1. Go to Settings > Content Types and click Create New > Block Type. The Create New Block Type window displays.

   
   

2. In the new block type, click Settings.

   

   • Name (required) – Enter a name for the block type.

   • Display name – Enter the name to be displayed in the list of available block types.

   • Description – Enter the text describing the block type also displays in the list of available block types.

   • Sort index – Enter a number to determine the (ascending) sort order for content types listed on the Content Types page.

   • Available in edit view – Select to make the block type available when creating content in the editorial interface. You should hide rarely used block types, such as the start block type. You can make these available when needed and then hide them again.

   • Available for composition in Visual Builder – Important! Select to let this block work in Visual Builder. If you do not select this, your block will not display in the element or section selection.

     • Section – Select to display this block as a section in Visual Builder.
     • Element – Select to display this block as an element in Visual Builder. Selecting Element affects the available options for adding properties to the block.

3. Select Properties and specify the components of your block type. For example, the CardTitle content type has a Text property, which is further defined as an XHTML string (>255) in the Configure Property panel.

   

4. Modify Permissions and other properties as needed.

   

5. Click Save to define the block type.

Block as an element

If you selected Available for composition in Visual Builder in the content type settings, when you click Add Element in a Visual Builder Outline, the block type—for example Card—is listed among the selections.

The following image shows a view of Card when it is added as an element of a section:

Block as a section

If you selected a block (such as Card Component) to display in Visual Builder as a section, when you click Add Section in a Visual Builder Outline, Card Component is among the selections.

Selecting it creates a New Card Component section in the outline.

The following image shows a partial view of Card Component as a section:

Media types

Media types are similar to page types. From the Settings view, you can add properties, modify permissions, and set some Settings.

Edit a media type

Edit the settings for an existing media type as follows:

1. Go to Settings > Content Types, and select a media type (Image, Video, or Media).

2. Click Settings.

3. Enter the following information.

   • Name – A name for the media type.

   • Display name – The name to be displayed in the list of available media types.

   • Description – The text describing the media type also displays in the list of available media types.

   • Sort index – A number determining the (ascending) sort order in the list of available media types. The default is 100.

   • Supported media extensions – Comma-separated list of file extensions the media type supports. 

     

4. Click Save.

Create a media type from the Settings view

1. Go to Settings > Content Types, and select Create New > Media Type.

   

2. Enter the following information.

   • Name – A name for the media type.

   • Display name – The name to be displayed in the list of available media types.

   • Description – The text describing the media type also displays in the list of available media types.

   • Sort index – A number determining the (ascending) sort order in the list of available media types. The default is 100.

   • Type –  Required for image and video types. Select the media type.

     

   • Supported media extensions – Comma-separated list of file extensions the media type supports.

3. Click Save.

Contract types

Contracts define a shared structure—a set of required properties—that multiple content types can implement. When you configure a Content Reference or ContentReference<T> property and select an allowed reference type, the type picker filters contracts from the list by default. Only concrete content types appear as selectable reference targets.

To reference content by contract rather than by a concrete type, configure the property's Reference Type as a specific contract. The content picker then surfaces all content types implementing that contract.

See Create contracts.

Experience types

An Experience content type is an extension of the page type, enhanced for use with the Visual Builder. To create one from the Settings view:

1. Go to Settings > Content Types.

2. Select Create New > Experience Type. The Create New Experience Type window displays.

   

3. Complete the following fields: * Name (required) – Enter a unique identifier for the content type (for example, LoremIpsum). This is the internal key used by the system.

   • Display name – Enter a human-readable label that editors see in the interface (for example, Lorem ipsum).
   • Description – Optionally, add a description to clarify the purpose of this content type for your team

4. Click Create to save the Experience content type.

   📘

   Note

   Experience types include a built-in Blank Experience managed by Optimizely. While you cannot adjust its settings, you can modify Permissions and Properties on any custom experience type you create. Once created, you can add properties to define the data model for your experience.

Section types

A Section content type lets you organize content within an Experience type in the Visual Builder. Like Experience types, Section types include a built-in Blank Section managed by Optimizely. To create a custom one from the Settings view:

1. Go to Settings > Content Types

2. Select Create New > Section Type. The Create New Section window displays.

   

3. Complete the following fields:

   • Name (required) – Enter a unique identifier for the content type (for example, MaurisEleifend). This is the internal key used by the system.
   • Display name – Enter a human-readable label that editors see in the interface (for example, Mauris eleifend).
   • Description – Optionally, add a description to clarify the purpose of this content type for your team (for example, describing the custom properties it exposes, such as Copyright or Photographer).

4. Click Create to save the Section content type.

   📘

   Note

   Once created, you can modify Settings, Permissions, and Properties on any custom Section type. Use properties to define additional metadata that editors can populate when working within the Visual Builder.

Connect from Graph types

Connect from Graph lets you create a connected content source by pointing the CMS at an external GraphQL endpoint. This allows external data—such as products from a PIM, assets from a DAM, or records from any GraphQL-compatible API—to appear as content types within Optimizely CMS without a full data sync.

To create a connected content source:

1. Go to Settings > Content Types and select Create New > Connect From Graph.

2. In the Connect From Graph dialog, configure the following:

   • Name – An internal identifier for the connected content source.
   • Display name – The label shown in the CMS UI.
   • GraphQL endpoint URL – The URL of the external GraphQL API to connect to.
   • Authentication – Provide any required headers or tokens needed to authenticate requests to the external endpoint.

3. After connecting, the CMS introspects the external schema and lists the available content types from the external source.

4. Select the content types you want to expose in the CMS and map their properties to CMS property types.

5. Click Save.

The following list shows the behavior of connected content types:

• Connected content types display alongside native CMS content types in the Content Types list, with a distinct Connected indicator.
• Editors can select and reference connected content in Content Reference and ContentReference<T> properties, provided the connected type is included in the allowed types for that property.
• Properties populated from the external source are read-only in the CMS Edit UI.
• If the connected content type implements a global contract, administration settings are restricted — only the External edit URL is editable.

For information on mapping connected content type properties, see Connect content sources using GraphQL.

Other content types

By default, there are generic content types for other types of content, such as folders and media files. Based on these existing types, developers can create custom content types. For example, you can create a specific folder or media file content type that lets you add properties such as Copyright or Photographer.

Orphaned content types

When a NuGet package that registered one or more content types is removed from a project without first deleting those content types from the CMS, the types become orphaned. At runtime, the CMS cannot resolve the .NET type backing the content type, which causes an EPiServerException similar to the following:

EPiServer.Core.EPiServerException: No type mapped for content type ID [id].
   at EPiServer.DataAbstraction.RuntimeModel.ContentTypeModelRepository.TransformModel(ContentTypeModel model)

Orphaned content types also display an Undefined label in the Base type column of the Content Types list.

Resolution strategies

Choose one of the following approaches to resolve orphaned content types:

Option 1 — Delete from the Admin UI (recommended for non-production)

1. Go to Settings > Content Types.
2. Filter by Base type: Undefined to locate orphaned types.
3. Select the orphaned content type and click Delete.

❗️

Warning

Deleting a content type permanently removes all content instances based on that type. Verify that no live content depends on the type before deleting.

Option 2 — Add stub classes (recommended for production)

Create a minimal stub class in your codebase that matches the original type registration. This resolves the runtime exception without data loss and gives you time to migrate or remove content safely.

using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType(GUID = "your-original-guid-here", AvailableInEditMode = false)]
public class OrphanedBlockStub : BlockData
{
    // No properties needed — stub only
}

After deploying the stub:

1. Migrate any existing content instances away from the orphaned type.
2. Remove the stub class and delete the content type from the Admin UI once no content instances remain.

Option 3 — Database cleanup (advanced)

If neither of the previous options is viable, a database administrator can remove the orphaned content type record directly from the tblContentType table. Perform this operation only in a non-production environment first, and always take a full database backup before proceeding.

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 that specific type, improving type safety and enabling richer Optimizely Graph responses.

When you configure a Content Reference property with a specific type, other than Any, the CMS:

• Limits the content picker to content matching the declared type T.
• Returns the full typed object in Optimizely Graph. For example, a property typed to ContactBlock returns all fields such as name and email, rather than only contentLink.
• Filters content type contracts out of the type picker by default. To type a reference against a contract, explicitly select the contract as the Reference Type.

The following table shows Reference Type and Optimizely Graph behavior:

Configure a typed reference from the admin view

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 a specific content type (not Any) and select the target type or contract from the list.
4. Save the content type. When you select a contract as the reference type, the content picker in the editor surfaces all content types that implement that contract.

Define a typed reference in code

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

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