BlockPreview

BlockPreview enables easy to use rich HTML backoffice previews for the Umbraco Block List and Block Grid editors.

Installation

Important

v3.x supports Umbraco v15

v2.x supports Umbraco v14.2+

v1.x supports Umbraco v10.x - v13.x

To understand more about which Umbraco CMS versions are actively supported by Umbraco HQ, please see Umbraco's Long-term Support (LTS) and End-of-Life (EOL) policy.

The Umbraco v15 version of this package is available via NuGet.

To install the package, you can use either .NET CLI:

dotnet add package Umbraco.Community.BlockPreview --version 3.0.0

or the NuGet Package Manager:

Install-Package Umbraco.Community.BlockPreview -Version 3.0.0

Setup

The package can be configured in the Program.cs file, before the call to the .Build() method:

+using Umbraco.Community.BlockPreview.Extensions;
builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
+   .AddBlockPreview(options =>
+   {
+       options.BlockGrid = new()
+       {
+           Enabled = true,
+           ContentTypes = [RichTextBlock.ModelTypeAlias]
+       };
+       options.BlockList = new()
+       {
+           Enabled = false
+       };
+   })
    .Build();

Alternatively, it can be configured in appsettings.json:

{
  "BlockPreview": {
    "BlockGrid": {
      "Enabled": true,
      "ContentTypes": ["richTextBlock"]
    },
    "BlockList": {
      "Enabled": false
    }
  }
}

Options

The following options can be configured, either in .AddBlockPreview() or appsettings.json:

builder.AddBlockPreview(options =>
{
  options.BlockGrid = new()
  {
      Enabled = true,
      ContentTypes = [],
      ViewLocations = []
      Stylesheet = ""
  };

  options.BlockList = new()
  {
      Enabled = true,
      ContentTypes = [],
      ViewLocations = []
  };
})

{
  "BlockPreview": {
    "BlockGrid": {
      "Enabled": true,
      "ContentTypes": [],
      "ViewLocations": []
      "Stylesheet": ""
    },
    "BlockList": {
      "Enabled": false,
      "ContentTypes": [],
      "ViewLocations": []
    }
  }
}

Settings

BlockPreview

Property	Type	Description
BlockGrid	BlockTypeSettings	Configure settings for the Block Grid previews
BlockList	BlockTypeSettings	Configure settings for the Block List previews

BlockTypeSettings

Property	Type	Description
Enabled	boolean	Toggle previews on or off for a given data type.
ContentTypes	string[] | List	A list of content type aliases to enable the previews for. If left blank, all blocks will be enabled.
ViewLocations	string[] | List	A list of custom locations to be searched for your partial views. The default paths are included automatically.
Stylesheet	string	BlockGrid only - path to a stylesheet that exists in /wwwroot, to be loaded for every block preview

Usage

This package installs a custom Web Component preview for both the Block List and Block Grid editors in the backoffice. Block Grid and Block List can be configured independently (v14.2+).

Before and after of how components look within the Block Grid:

Grid-specific setup

When using the new Block Grid, replace the references below in your default Grid template partial views, and and custom views that render areas:

/Views/Partials/blockgrid/default.cshtml

<div class="umb-block-grid"
     data-grid-columns="@(Model.GridColumns?.ToString() ?? "12");"
     style="--umb-block-grid--grid-columns: @(Model.GridColumns?.ToString() ?? "12");">
-   @await Html.GetBlockGridItemsHtmlAsync(Model)
+   @await Html.GetPreviewBlockGridItemsHtmlAsync(Model)
</div>

/Views/Partials/blockgrid/areas.cshtml

<div class="umb-block-grid__area-container"
     style="--umb-block-grid--area-grid-columns: @(Model.AreaGridColumns?.ToString() ?? Model.GridColumns?.ToString() ?? "12");">
    @foreach (var area in Model.Areas)
    {
-       @await Html.GetBlockGridItemAreaHtmlAsync(area)
+       @await Html.GetPreviewBlockGridItemAreaHtmlAsync(area)
    }
</div>

/Views/Partials/blockgrid/area.cshtml

<div class="umb-block-grid__area"
     data-area-col-span="@Model.ColumnSpan"
     data-area-row-span="@Model.RowSpan"
     data-area-alias="@Model.Alias"
     style="--umb-block-grid--grid-columns: @Model.ColumnSpan;--umb-block-grid--area-column-span: @Model.ColumnSpan; --umb-block-grid--area-row-span: @Model.RowSpan;">
-   @await Html.GetBlockGridItemsHtmlAsync(Model)
+   @await Html.GetPreviewBlockGridItemsHtmlAsync(Model)
</div>

You will also need to use @await Html.GetPreviewBlockGridItemAreasHtmlAsync(Model) in any custom Razor views that contain areas, for example...

<section
    style="background-color: #@backgroundColor"
    @(noBackgroundColor ? "nobackgroundcolor" : null)
    @(hasBrightContrast ? "bright-contrast" : null)>
+   await Html.GetPreviewBlockGridItemAreasHtmlAsync(Model)
</section>

All of these extensions can be found in the namespace Umbraco.Community.BlockPreview.Extensions. This ensures that the grid editors correctly load in the back office.

Preview mode

This package adds an IsBlockPreviewRequest() extension to HttpContext.Request, similar to IsBackOfficeRequest() and IsFrontEndRequest() so you can add custom code to your views that only appears in the back office.

For example:

@using Umbraco.Community.BlockPreview.Extensions
@inherits UmbracoViewPage<BlockGridItem<TContent, TSettings>>

@if (Context.Request.IsBlockPreviewRequest())
{
    <p>This content will only be shown to content editors in the back office!</p>
}

Custom View locations

If your block partials are not in the usual /Views/Partials/block[grid|list]/Components/ paths, you can add custom locations in your appsettings.json:

"BlockPreview": {
  "BlockGrid": {
    "ViewLocations": ["/path/to/block/grid/views/{0}.cshtml"]
  }
}

Contribution guidelines

To raise a new bug, create an issue on the GitHub repository. To fix a bug or add new features, fork the repository and send a pull request with your changes. Feel free to add ideas to the repository's issues list if you would to discuss anything related to the library.

Using the test sites

The repo comes with a test site for Umbraco 14.2+. The site is configured with uSync out of the box to get you up and running with a test site quickly. Use the following credentials to log into the back office:

Username: [email protected]
Password: 1234567890

Who do I talk to?

This project is maintained by Rick Butterfield and contributors. If you have any questions about the project please get in touch on Twitter, or by raising an issue on GitHub.

Credits

This package is entirely based on the amazing work done by Dave Woestenborghs for 24days in Umbraco 2021. His code has been extended to support the new Block Grid editor in v10.4+ and turned into this package.

Matthew Wise also wrote a great article for 24days in Umbraco 2022 which added the ability to surface ViewComponents and has allowed his code to be contributed.

License

Copyright © 2022-2024 Rick Butterfield, and other contributors.

Licensed under the MIT License.