1.2: Routing Patterns That Don’t Break Preview or Editor Expectations

In the world of external integrations and content federation, the backend routing logic is often the most critical—yet invisible—part of the user interface. For a developer working with Optimizely CMS 13 (PaaS), routing is not just about mapping a URL string to a controller action; it is about maintaining the continuity of the authoring experience. When you create a virtual URL space via partial routing to surface external items like PIM products or CRM profiles, you are effectively asking the CMS to treat these foreign objects as its own.

However, if your routing logic is designed solely for the live site (production), you risk "breaking" the CMS editor portal. Editors expect to be able to preview content, use "View on Website" functionality, and see their changes reflected in real-time. If the router fails to recognize the CMS context, these federated items will appear as "broken links" or "unauthorized pages" within the internal preview frame. As you prepare for the PaaS CMS 13 Developer Certification, mastering routing patterns that respect the ContextMode and enable high-fidelity preview is essential. This activity explores the architectural patterns required to build "Editor-Aware" routing.

1. Understanding ContextMode: The Developer’s Compass

The single most important property during the routing lifecycle is ContextMode. Located within the RequestContext or accessible via helper methods, this enum tells your routing logic exactly where the request is originating. By branching your logic based on this mode, you can optimize the developer experience without sacrificing production performance.

The Three Primary Modes:

• Default (Live): Standard public browsing. Focus on caching and minified payloads.
• Edit: Active property manipulation. Focus on stability and providing "editable" metadata.
• Preview: Viewing the page through the CMS iframe. Focus on visual fidelity.

Pattern: Your IPartialRouter implementation should check if the request is in Edit mode. If so, you might return a "Skeleton" version of an external item if the third-party API is slow, ensuring that the CMS UI remains snappy even when external systems are under load. This prevents the editor from facing a "hanging" interface while waiting for external data to resolve.

2. Implementing Pseudo-Content with IContent

A significant limitation of standard partial routing is that the resulting object is often a "Plain Old CLR Object" (POCO) rather than an Optimizely content item. This breaks the "Editor Expectation" because POCOs do not have a ContentReference, nor do they support native CMS UI features like breadcrumbs or "On-Page Editing" attributes. To fix this, we use the Content Mapping Pattern.

Implementation Example: Mapping External Data

By implementing the IContent interface on your external data transfer objects (DTOs), you allow the CMS to inject necessary HTML metadata (like data-epi-property-name) required for real-time visual updates.

3. The "Shell Page" Pattern: Logical Entry Points

To prevent breaking the editor’s mental model of the content tree, you should never route from "nowhere." Successful federation always begins with a Shell Page—a native CMS page that acts as the physical parent for the virtual URL space. This ensures the ParentLink property of your routed data has a physical home in the Optimizely tree. Without a Shell Page, routed content feels orphaned, and breadcrumb navigation will likely fail to resolve.

4. Permalinks and "View on Website" Continuity

A major point of friction for content creators is the "View on Website" button. When using custom routing, the CMS often defaults this button to the "Shell Page" URL, losing the virtual segments (e.g., the specific product ID). This is solved by correctly implementing Reverse Routing.

The IPartialRouter interface includes a GetPartialVirtualPath method. When the CMS generates a link to an external item, it calls this method. As a developer, you must take the object and convert it back into string segments. If this is missing, the "View on Website" feature will appear broken to the editor, as it will always link to the top-level container instead of the item they are currently editing.

5. Failure Modes: The Graceful Fallback

In a federated architecture, you will eventually encounter a "Missing Member" scenario—where a URL exists in the CMS segments but the data has been deleted in the external PIM. Avoid returning null directly from the router if possible, as this can trigger a raw 404 or a site-wide crash. Instead, consider returning a "Maintenance Mode" content item. This tells the editor exactly what happened ("This product was deleted in the PIM") rather than showing a generic error page, allowing them to proactively fix internal links and maintain site health.

Conclusion

Routing patterns that respect editor expectations in Optimizely CMS 13 are the hallmark of a senior architect who values the authoring experience as much as the end-user delivery. By mastering the usage of ContextMode to differentiate between live and edit requests, implementing IContent interfaces for external data, and ensuring breadcrumb and "View on Website" continuity through robust GetPartialVirtualPath implementations, you transform "bolted-on" integrations into seamless authoring extensions. This strategic alignment ensures that federated content remains accessible, previewable, and manageable, providing the reliable editorial guardrails required for a successful PaaS CMS 13 Developer Certification and a high-performance, resilient digital ecosystem.