orchardcore-display-management

Orchard Core Display Management - Prompt Templates

Mental Model

model ──display drivers──▶ shapes ──placement──▶ zones ──templates (alternates)──▶ HTML

• Shape: a dynamic view model with a shape type and Metadata (alternates, wrappers, differentiator, placement). The shape type selects both the template and the placement rule.
• Driver: Display, Edit, and UpdateAsync return IDisplayResults, each with a default .Location(...) per display type.
• Placement: placement.json at the root of a module or theme (or the admin Placements UI) overrides where a shape goes, whether it renders, and which template it uses.
• Zone: a named region of the root shape (Content, Meta, Actions, Parts, ...) or of the layout (Header, Footer, ...), or an editor group (tab, card, column).

Driver or Placement?

Want to...	Use
Reposition or hide a shape someone else built	placement.json
Move a shape to a layout zone	placement.json (place starting with /)
Swap the template, add alternates or wrappers	placement.json (shape, alternates, wrappers) or a shape table provider
Lay out an admin editor in tabs, cards, columns	placement.json groupings or the driver's .Location(...)
Produce a new shape from your part, field, or model	A display driver
Read and validate posted editor values	A display driver (UpdateAsync)

Prefer placement for layout; a theme can override it without recompiling the module. See orchardcore-placement.

Create Display Drivers and Shapes

You are an Orchard Core expert. Generate display drivers, shapes, and display management code for Orchard Core.

Guidelines

• Every content part that needs custom rendering requires a DisplayDriver.

• Pick the base class by model:

  Base class	Contexts (Display / Edit / Update)	For
  ContentPartDisplayDriver<TPart>	BuildPartDisplayContext / BuildPartEditorContext / UpdatePartEditorContext	A content part
  ContentFieldDisplayDriver<TField>	BuildFieldDisplayContext / BuildFieldEditorContext / UpdateFieldEditorContext	A content field
  SiteDisplayDriver<TSettings>	BuildDisplayContext / BuildEditorContext / UpdateEditorContext	A site settings group (SettingsGroupId)
  SectionDisplayDriver<TModel, TSection>	Same as DisplayDriver	A section (named property) of any IEntity, such as user settings
  DisplayDriver<TModel>	BuildDisplayContext / BuildEditorContext / UpdateEditorContext	Any other model

• Drivers handle three operations: Display, Edit, and Update (sync or ...Async variants).

• Each operation returns IDisplayResult (shapes to render). ShapeResult resolves placement first and only creates the shape when it is actually displayed.

• View models are used to pass data between drivers and views.

• Shape names follow the convention {PartName} for display and {PartName}_Edit for editor.

• Use Initialize<TModel> to create shapes with a view model. Use Factory() when you build the IShape yourself. Never use the obsolete Shape() method (see Upgrading from 3.x).

• Prefer static lambdas with the typed-state overloads on hot paths (drivers that run for every content item in a list) to avoid closure allocations.

• Register drivers in Startup.cs using services.AddContentPart<TPart>().UseDisplayDriver<TDriver>().

• For non-content-item models rendered through DisplayDriver<TModel>, the root shape still needs its own wrapper template for each display type you build (for example, CampaignAction.Edit.cshtml for CampaignAction_Edit and CampaignAction.SummaryAdmin.cshtml for CampaignAction_SummaryAdmin).

• When driver results are placed into zones with .Location("Content:1"), .Location("Actions:5"), or similar, the wrapper template must render those zones (Model.Content, Model.Actions, Model.Meta, etc.) or the child shapes will never appear.

• For ALL admin editor views (*.Edit.cshtml including *Settings.Edit.cshtml), use the ocat-* (Orchard Core Admin Theme) CSS classes instead of raw mb-3, form-label, or hard-coded grid classes. Use ocat-wrapper for the outer row, ocat-label for labels, ocat-end for the input column, ocat-end-offset for checkbox-only rows/headings/buttons with no left label, ocat-limited-wrapper + ocat-limited for narrow-width fields. Do NOT apply these classes to frontend views (Login, Register, etc.) or Admin Menu node editing (needs full width).

• The former @Orchard.GetWrapperClasses(), @Orchard.GetLabelClasses(), @Orchard.GetEndClasses() helper methods and TheAdminThemeOptions class have been removed. Use the static ocat-* CSS classes directly.

• Always seal classes.