orchardcore-display-management

OrchardCore Display Management

This skill guides you through OrchardCore's display system following project conventions.

OrchardCore renders content by building shapes (dynamic view models) from drivers, then placing each shape into a zone of the layout. Drivers decide what shapes exist and their default location; placement.json overrides where they go, whether they show, and which template renders them.

Mental model

ContentItem ──drivers──▶ shapes ──placement.json──▶ zones ──templates──▶ HTML

• Shape — a dynamic object with a ShapeType and Metadata. The shape type (e.g. TextField, Parts_Contents_Publish, ContentPart) selects the template and the placement rule.
• Driver — DisplayDriver / ContentPartDisplayDriver / ContentFieldDisplayDriver. Returns IDisplayResults from Display, Edit, UpdateAsync, each with a default .Location(...).
• Placement — placement.json at the root of a module or theme. Filters shapes and rewrites their location/visibility/template.
• Zone — named region of the layout (Content, Header, Footer, Actions, …) or an editor group (tab/card/column).

Decide: driver vs placement

Prefer placement.json for layout — no rebuild needed, theme can override.

Workflow A: place a shape

Step 1: Find the shape type and differentiator

The placement property name is the shape type, not the part name. A part without its own driver renders as ContentPart (differentiator = part name). A field renders as its field type (TextField) with differentiator {PartName}-{FieldName}.

See references/placement.md for the full differentiator table.

Step 2: Add a rule to placement.json

{
  "TextField": [
    {
      "differentiator": "Article-Subtitle",
      "displayType": "Detail",
      "place": "Content:2"
    }
  ]
}

Step 3: Verify

Run the site, view the content item. Use ?display debug shapes or the template's shape tracing to confirm the shape type. Wrong type → no rule matches.

Workflow B: write a display driver

Step 1: Inherit the right base

Step 2: Implement Display / Edit / Update

public sealed class TextFieldDisplayDriver : ContentFieldDisplayDriver<TextField>
{
    public override IDisplayResult Display(TextField field, BuildFieldDisplayContext context)
    {
        return Initialize<DisplayTextFieldViewModel>(GetDisplayShapeType(context), model =>
        {
            model.Field = field;
            model.Part = context.ContentPart;
            model.PartFieldDefinition = context.PartFieldDefinition;
        })
        .Location(OrchardCoreConstants.DisplayType.Detail, "Content")
        .Location(OrchardCoreConstants.DisplayType.Summary, "Content");
    }

    public override IDisplayResult Edit(TextField field, BuildFieldEditorContext context)
    {
        return Initialize<EditTextFieldViewModel>(GetEditorShapeType(context), model =>
        {
            model.Field = field;
            model.Part = context.ContentPart;
            model.PartFieldDefinition = context.PartFieldDefinition;
        });
    }

    public override async Task<IDisplayResult> UpdateAsync(TextField field, UpdateFieldEditorContext context)
    {
        await context.Updater.TryUpdateModelAsync(field, Prefix, f => f.Text);
        return Edit(field, context);
    }
}

Step 3: Register the driver

In Startup.cs:

services.AddContentPartDisplayDriver<MyPart, MyPartDisplayDriver>();
// or for a field:
services.AddContentFieldDisplayDriver<TextField, TextFieldDisplayDriver>();

See references/drivers.md for shape-type helpers, the fluent .Location API, and registration variants.

Quick Reference

Placement rule keys

Position values

before < 0/empty < 1 < 1.1 < 2 < 10 < after. Numeric, not alphabetic. Dot notation inserts between (5.1 is between 5 and 6).

Editor grouping modifiers

;N after a group name = group order. _N after a column name = Bootstrap grid width (12-col).

Common zones

Gotchas

• Hiding a whole editor row → target ContentPart_Edit with differentiator {ContentType}-{PartName}, not the inner XxxPart_Edit.
• Shape type ≠ part type. No driver → shape is ContentPart. Summary display of a dynamic part → ContentPart_Summary.
• Field display modes are stricter: shape type needs _Display, differentiator is {Part}-{Field}-{FieldType}_Display__{Mode}.
• Placement precedence: startup project → active theme → modules (by dependency). A theme can override any module's placement.
• Same position value → registration order decides; use distinct positions when order matters.

References

• references/placement.md — placement.json filters, differentiators, layout zones, editor groupings
• references/drivers.md — driver base classes, shape helpers, fluent Location API, registration
• src/docs/reference/modules/Placement/README.md (repo) — official placement reference
• src/docs/reference/modules/DisplayManagement/README.md (repo) — display management reference
• src/docs/reference/modules/Templates/README.md (repo) — shape differentiators and alternates
• AGENTS.md (repo root) — build commands