Skip to main content
Version: 17+

Enable block previews

By default the Block Grid shows each block in the backoffice as a simple label. Block previews replace that with the block's real rendered markup — the same Razor view and the same CSS the front end uses — so editors see what they're building without leaving the content editor.

Igloo ships with Umbraco.Community.BlockPreview as a dependency and wires it up for you. Previews are off until you turn them on.

Enable it​

Add the BlockPreview section to your site's appsettings.json (top level, alongside Umbraco):

{
  "BlockPreview": {
    "BlockGrid": {
      "Enabled": true
    }
  }
}

Restart the site, open a page and expand a block in the grid — it now renders its real markup.

Models must exist on disk

BlockPreview renders blocks through Igloo's strongly typed models, so generated models must be on disk. Keep ModelsMode set to SourceCodeAuto (or SourceCodeManual, generating models manually) and commit the generated files before deploying:

{
  "Umbraco": {
    "CMS": {
      "ModelsBuilder": {
        "ModelsMode": "SourceCodeAuto"
      }
    }
  }
}

What Igloo sets up for you​

Igloo's composer calls AddBlockPreview() and pre-configures three things you'd otherwise have to do by hand:

  • Every Igloo block is registered. All of Igloo's generated block models are added to ContentTypes, so each of the built-in blocks previews without being listed.
  • Igloo's stylesheet is loaded into the preview, so blocks are styled rather than raw HTML.
  • The page's Design is applied. A preview renders one block in isolation, with none of the front end's <body> ancestry. Igloo wraps the markup in <div class="igloo-block-preview design-{key}">, resolving the Design from the host page, so the palette and spacing variables cascade exactly as they do on the live site.

Options​

Each block editor type — BlockGrid, BlockList, RichText, SingleBlock — takes the same settings:

SettingDescription
EnabledWhether previews are rendered for this editor type. Igloo ships with all of them off.
ContentTypesElement type aliases to preview. Igloo appends every Igloo block alias to this list, so you only add your own.
IgnoredContentTypesAliases to exclude. Only applies when ContentTypes is empty — see the caveat below.
ViewLocationsExtra folders to look for block views in, if yours don't live in Views/Partials/blockgrid/Components/.
StylesheetsStylesheets to load into the preview. Igloo already sets this to its own CSS bundle; overriding it in appsettings.json replaces that.
IgnoredContentTypes has no effect on Igloo blocks

IgnoredContentTypes is only consulted when ContentTypes is empty, and Igloo always populates ContentTypes with every block alias. To stop a single block previewing, remove it from the list in code rather than relying on IgnoredContentTypes.

Previewing a custom widget​

Igloo only auto-registers its own block models. A widget you added yourself (see Create a new widget) lives in your site's models, so add its content element type alias to ContentTypes:

{
  "BlockPreview": {
    "BlockGrid": {
      "Enabled": true,
      "ContentTypes": ["helloWorld"]
    }
  }
}

Igloo's own aliases are still added on top of whatever you list here.

Writing views that preview well​

Render nested blocks with the preview helpers​

If your view renders child blocks — an area, or a list of block items — use BlockPreview's helpers instead of Umbraco's standard ones. They render the same markup on the front end, but also resolve the children correctly inside a preview, where there's no surrounding grid request to hang them off:

@* Igloo's sectionBlock.cshtml and groupBlock.cshtml *@
@await Html.GetPreviewBlockGridItemAreaHtmlAsync(Model, "area")
HelperUse instead of
GetPreviewBlockGridItemAreaHtmlAsync(Model, "area")GetBlockGridItemAreaHtmlAsync — one named area on a block.
GetPreviewBlockGridItemAreasHtmlAsync(Model, template)GetBlockGridItemAreasHtmlAsync — all areas on a block.
GetPreviewBlockGridItemsHtmlAsync(items, template)GetBlockGridItemsHtmlAsync — a set of block items.

They come from Umbraco.Community.BlockPreview.Extensions, which Igloo's _ViewImports.cshtml already imports — no @using needed in your view. Blocks that nest content (Section, Group) use them out of the box; without them a previewed Section would render its band but not the blocks inside it.

Account for JavaScript that hasn't run​

A preview runs your view through a real request, but not a real page load — so anything that depends on front-end JavaScript won't have run. Igloo's built-in views handle this by checking for a preview request and skipping the lazy-load state:

@{
    var loadingState = "";
    if (Igloo.Extensions.HttpRequestExtensions.IsBlockPreviewRequest(Context.Request))
    {
        loadingState = "loaded";
    }
}

Without it, images that fade in on scroll would sit invisible in the backoffice. Use the same check in your own views for any markup that starts hidden and is revealed by script — see imageBlock.cshtml, galleryBlock.cshtml, logosBlock.cshtml and podBlock.cshtml for working examples.