Develop a Custom Widget In Orchard Core CMS

Orchard Core CMS Development

I'm really excited about this next tutorial where I demonstrate one way to develop a custom widget for Orchard Core CMS. Again, we will be using The Blog Theme since it ships with Orchard Core. This is the 3rd part of a series on theme development in Orchard Core. In the first part, I customized the Article Content Type to allow authors to choose and display a custom background image for each article in The Blog Theme. In the second part, I created a new zone for The Blog Theme, where I will place the custom widget I develop today. In all these tutorials I am deliberately using the Templates Module in Orchard Core that allows us to create templates in the database from the administrative backend. These templates override the templates in the themes. Let's get started.

Custom Widget for Orchard Core CMS: Alert Widget

The Blog Theme is a Bootstrap theme and Bootstrap has a lot of components that I can make into a widget, so I will start simple and develop an Alert Widget. This widget will allow one to easily display a Bootstrap alert on the website. Here is the alert widget being displayed below in the new Messages Zone I created last time.

Custom Boostrap Alert Widget for Orchard Core CMS

Developing a Widget in Orchard Core CMS

Widgets in Orchard Core CMS are Content Types with a stereotype of Widget. Therefore, developing a widget is as simple as creating a Content Type, which can easily be done from the admin in Orchard Core. Content Types are composed of fields and parts. These can be custom fields and parts I develop, but, if possible, I want to use the built-in fields and parts that come with Orchard Core CMS.

When I look at the anatomy of an alert component in Bootstrap, there are two pieces of information that need to be provided by the user to display the shape. The first piece is the type of alert: danger, success, info, warning, etc. The second piece is the information displayed in the alert.

<div class="alert alert-danger" role="alert">
  A simple danger alert—check it out!
</div>

The widget editor is responsible for collecting this information and it displays the appropriate editors based on the fields and parts I choose as well as the settings I pick for them. For simplicity, I will use a Text Field to capture the type of alert and an HtmlBody Part to capture the information displayed in the alert.

From the Orchard Core admin I create a new Content Type, called Alert, and add a new Text Field to it, called Type, and an HtmlBody Part. I make sure to set the stereotype to Widget so Orchard knows this is a widget. I also uncheck Creatable and Listable, because I prefer the widget not clutter the New menu option in the admin and not be displayed in the list of content items.

Custom Content Type in Orchard Core CMS

Note that because I designate Alert as a Widget stereotype, I will see the nice widget badge when I list the content types.

Widget Stereotype in Orchard Core CMS

Field and Part Settings in Orchard Core

The new fields and part are added, but I still need to modify their settings. The Edit buttons next to the fields and parts allow one to adjust their settings.

For the Type Field, I only want the user to choose types from a predefined list of options: success, info, warning, and danger. Orchard Core CMS has an editor for this situation: Predefined List Editor (aka Options Editor). I will display the list as a Drop down List and populate the list with the options mentioned above. This is a required field. The settings for the Type Field are as follows.

Text Field Settings and Options Editor in Orchard Core CMS

I am not making any changes to the HtmlBody Part settings. The standard editor is fine for such a small amount of text and HTML. If a lot more text and HTML is being added to the alerts, I can specify the Wysiwyg editor at a later time.

Add an Alert Widget to the Messages Zone in Orchard Core CMS

I still need to create the widget template that displays the alert, but I'm excited to see the user experience of creating an alert widget. It should be really clean and easy with the Predefined List and standard HTML editors. I navigate to Layers in the Orchard Core admin and start adding a widget to the Messages zone. Notice that Alert is now an available option when adding a widget!

Add Widget to Layer in Orchard Core CMS

The experience of creating the alert is very convenient. A drop down list with the available alert types and a multiline text area where I can add basic HTML if necessary. Again, I always have the options of switching to the Wysiwyg editor and even the MarkdownBody Part to avoid HTML altogether.

Custom Widget Orchard Core CMS Developer

Create the Widget Template in Orchard Core

It's still a little early to celebrate, however. I need to create the template that displays the alert. You will love this tip. You remember that Edit templates button when editing the Alert Content Type? Click it and choose Template for a Alert content item in detail views to automatically start creating the properly named widget template using the Templates Module in Orchard Core CMS.

Create Widget Template in Orchard Core CMS from Content Type Editor

Here is the liquid template to display the alert widget. I'll save liquid filters and expressions for another time. The Orchard Core documentation is a good place to start learning about templating using liquid.

<div class="alert alert-{{ Model.ContentItem.Content.Alert.Type.Text }}" role="alert">
  {{ Model.Content.HtmlBodyPart | shape_render }}
</div>

Custom Widget Template for Boostrap Alert in Orchard Core CMS

Custom Bootstrap Alert Widget in Orchard Core CMS

When I view the homepage I see the Bootstrap Alert as expected. The custom widget was very easy to develop and required no coding in Visual Studio, Visual Studio Code, or JetBrains Rider. Everything can be done from the Orchard Core admin with only a minor bit of knowledge about the liquid template language. Best wishes!

Custom Boostrap Alert Widget for Orchard Core CMS

Next Step: Dismissible Bootstrap Alerts

Just when I thought I was done with this widget, let's add a checkbox and improve the Liquid Templates to make the Orchard Core CMS Widget display dismissible Bootstrap Alerts!