Modeling Pages and Blocks

By Optimizely Education
Published: Mar 9, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Architectural Core: Leverage abstract base classes to provide a single point of truth for global metadata in multi-regional environments.
Composition Strategy: Master the technical trade-offs between ContentArea flexibility and IList<ContentReference> performance.
Performance Optimization: Use explicit attributes like [CultureSpecific] and dynamic selection factories to optimize SQL and Cloud Graph footprints.
Semantic Modeling: Ensure cross-channel durability by modeling data intent rather than visual formatting.

Content modeling is the architectural nucleus of any Optimizely CMS 13 enterprise solution. It is the process of defining the schema, relationships, and editorial behavior of your data. In a high-scale PaaS (DXP) environment, where performance, stability, and globalization are paramount, a well-structured content model ensures that the application remains maintainable even as the content tree scales into the thousands or millions of nodes. Developers must transition from simply “creating fields” to “architecting a data ecosystem” that serves both traditional markup and high-performance API delivery.

This guide provides an exhaustive technical deep-dive on designing pages and blocks that are reusable, performant, and structurally resilient.

1. The Core Abstractions: PageData, BlockData, and IContent

In the Optimizely ecosystem, every content object is essentially a C# class that the CMS engine “discovers” at startup and maps to the database schema. While technically everything resolves down to the IContent interface, developers primarily work with two base classes that define the “physicality” of content objects.

1.1 PageData: The Orchestrator of Delivery

Classes inheriting from PageData represent unique pages in your site’s hierarchy. Every PageData instance is associated with a specific URL, a position in the site tree, and metadata properties like Name, ContentLink, and Created. Because PageData is the primary entry point for routing, it should contain route-level metadata suitable for indexing and crawling.

Enterprise Strategy: The Abstract Base Class Hierarchy

For solutions meant to scale across regions or brands, never define properties directly on a leaf-level page type without a shared foundation. A hierarchical approach using C# inheritance allows you to enforce global standards. For instance, a BasePageData class acts as a single point of truth for properties required by every route, such as Open Graph (OG) tags, SEO metadata, and tracking identifiers.

public abstract class BasePageData : PageData
{
    [Display(Name = "Search Engine Title", GroupName = "SEO", Order = 10)]
    public virtual string MetaTitle { get; set; }

    [CultureSpecific] // Crucial for global DXP multi-lingual sites
    [Display(Name = "Search Engine Description", GroupName = "SEO", Order = 20)]
    [UIHint(UIHint.Textarea)]
    public virtual string MetaDescription { get; set; }

    [Display(Name = "Hide From Global Navigation", GroupName = "Settings", Order = 100)]
    public virtual bool HideFromNavigation { get; set; }
}

1.2 BlockData: The Modular Building Blocks

Inheriting from BlockData defines modular components. Blocks are the “cells” of your application; they do not possess their own URL and must be hosted within a container. This decoupling allows developers to build complex components like Hero Banners, Carousel Items, and Pricing Tables once and reuse them indefinitely. From a database perspective, blocks are significantly more efficient than pages for small data fragments because they do not require the overhead of URL segment indexing.

2. Managing Relationships: ContentArea vs. IList<ContentReference>

A common bottleneck in scaling CMS applications is the mismanagement of content relationships. For enterprise-grade PaaS solutions, you must technically distinguish between Visual Composition and Structured Data Reference.

2.1 Visual Composition via ContentArea

The ContentArea property is the engine of editor flexibility. It supports drag-and-drop, inline content creation, and Visitor Group Personalization. Because ContentArea entries carry significant metadata overhead to support personalization and view configurations, they should be reserved for areas where the marketing team needs active layout control.

AllowedTypes Constraint: Crucial for scale. Without this, an editor could accidentally drop a “Search Page” inside a “Hero Banner Area,” causing rendering exceptions.
Rendering Overhead: Every item in a ContentArea goes through the full .NET rendering lifecycle. On low-tier DXP plans, areas with 50+ items can impact Time to First Byte (TTFB) due to template resolution latency.

[Display(Name = "Main Content Items")]
[AllowedTypes(typeof(StandardTeaserBlock), typeof(CallToActionBlock))]
public virtual ContentArea MainContent { get; set; }

2.2 Structured References via IList<ContentReference>

When your model requires a simple list of related objects, such as a footer menu, a list of related product IDs, or a selection of featured articles, IList<ContentReference> is the superior technical choice. It provides a lightweight list of IDs without the overhead of the ContentArea rendering engine or personalization logic.

Governance Advantage: This property type does not show a “Create new inline block” button. It forces editors to select from existing globally managed assets, encouraging reusability and preventing content sprawl.

3. Advanced Property Decorators for Global Scale

To ensure your model is performant and editor-friendly, leverage Optimizely’s extensive attribute system. These attributes do not just affect the UI; they define how the data is stored and indexed in Optimizely Graph.

3.1 CultureSpecific and Performance

The [CultureSpecific] attribute tells the SQL engine to version the property by language. In a 20-language DXP site, applying this to a large XhtmlString results in 20 distinct database records. Ensure this is applied strategically to user-facing text but avoided for technical configuration flags like “Show Background Video” to keep the database footprint lean.

3.2 Selection Factories for Constraint Management

Hardcoding dropdown values in C# is a brittle hack that prevents updates without a full deployment. Instead, use an ISelectionFactory to provide editors with values managed dynamically. This ensures the content model remains pluggable.

public class ThemeSelectionFactory : ISelectionFactory
{
    public IEnumerable<ISelectItem> GetSelections(ExtendedMetadata metadata)
    {
        return new ISelectItem[] {
            new SelectItem { Text = "Light Mode", Value = "theme--light" },
            new SelectItem { Text = "Dark Mode", Value = "theme--dark" },
            new SelectItem { Text = "High Contrast", Value = "theme--accessible" }
        };
    }
}

// In the Content Model:
[SelectOne(SelectionFactoryType = typeof(ThemeSelectionFactory))]
public virtual string VisualTheme { get; set; }

4. Reusability Tiers: Inline vs. Global Blocks

A scalable content model effectively manages the shared assets pane to prevent editorial clutter.

Shared (Global) Blocks: These live in the CMS Blocks pane. They are central entities. If you update a Global Alert Block, every page referencing that block instance is updated immediately. This is the gold standard for global governance.
Local (Inline) Blocks: Created directly within a ContentArea on a specific page. These are stored mathematically as part of that page’s version history. They are perfect for one-off banners that will never be used elsewhere, keeping the global assets folder clean and performant.

5. Architectural Principle: Decoupling Data from Design

The move toward Optimizely Graph and Headless Delivery in CMS 13 (PaaS) makes this the most critical lesson for developers: Model for the meaning of the content, not the visual style.

If a property is called LargeBoldTextWithRedBackground, it is doomed to obsolescence the moment the brand changes its CSS. Furthermore, such names become nonsensical when the content is consumed by an API for a native mobile app. Instead, model properties based on their informational intent, such as PrimaryHeadline or HeroSubTitle. This ensures your data remains clean when indexed by Optimizely Graph and can be consumed by both your main C# site and a remote Next.js site simultaneously.

Conclusion

Building content models for CMS 13 PaaS requires a strategic balance between composition and structural control. For developers, this means moving beyond simple property sets to a robust architecture focused on reusability and performance. By standardizing metadata through abstract base classes, enforcing strict child hierarchy with [AvailableContentTypes], and carefully selecting between ContentArea and IList<ContentReference>, you ensure that your platform remains performant and intuitive. Mastering the maintenance of clean global asset folders through localized block usage and semantic, design-agnostic property naming is the final step in ensuring your content architecture can scale seamlessly from a local sandbox to a global enterprise footprint with millions of queryable nodes. This approach ensures that your content remains valid through custom IValidate<T> logic and is properly decoupled from design, allowing for seamless integration with Optimizely Graph and other headless consumers.