Orchard Core CMS Shortcodes and Shortcode Delegates

Orchard Core CMS Tutorials

In the previous Orchard Core CMS Tutorial I talked about shortcodes and shortcode templates in Orchard Core CMS. If you're unfamiliar with shortcodes and the new shortcode templates, I recommend you read that tutorial first, because it will give you the necessary background before diving into shortcode delegates.

As mentioned previously, shortcode templates allow you to create shortcodes in the administrative backend using the liquid template language in Orchard Core. Shortcode templates are perfect for shortcodes that can easily be expressed using liquid.

In addition to shortcode templates, however, there are a couple of other ways to create shortcodes in Orchard Core CMS via code: shortcode delegates and shortcode providers. I'll describe shortcode delegates now and save shortcode providers for another time.

Shortcode Delegates in Orchard Core CMS

If you take a peek at OrchardCore.Shortcodes.Abstractions you'll find a few IServiceCollection extension methods that allow you to add shortcodes to Orchard Core CMS via code. The one I will be using here is:

AddShortcode(
    this IServiceCollection services,
    string name,
    ShortcodeDelegate shortcode,
    Action<shortcodeoption> describe
)

Let's use this extension method to add a shortcode that highlights text on the web page. The name of the shortcode will be highlight and it will simply surround text with the mark HTML tag to highlight text.

Shortcode in Orchard Core CMS

Shown below is the code to add this shortcode to Orchard Core CMS. First thing to notice is that we only want to add this shortcode when the Shortcodes Feature is enabled for the Orchard Core CMS Website. Therefore, I've added a RequireFeatures attribute on the custom startup class to insure this shortcode delegate is only added if and when shortcodes are enabled. If you're including these shortcodes as part of your custom Orchard Core CMS theme that enables the shortcodes feature as part of the setup recipe, you're probably fine. However, I prefer to add the attribute and custom startup class to make things more clear and for peace of mind.

[RequireFeatures("OrchardCore.Shortcodes")]
public class ShortcodesStartup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddShortcode("highlight", (args, content, ctx) =>
        {
            var text = args.NamedOrDefault("text");
            if (!String.IsNullOrEmpty(text))
            {
                content = text;
            }

            return new ValueTask<string>($"<mark>{content}</mark>");
        }, describe =>
        {
            describe.DefaultValue = "[highlight text-here]";
            describe.Hint = "Add highlighting with a shortcode.";
            describe.Usage = "[highlight 'your content here']";
            describe.Categories = new string[] { "HTML Content" };
        });
    }
}

The Shortcode Delegate is passed:

  • args - arguments included in the shortcode, named or positional
  • content - content between the opening and closing shortcode tags (if any)
  • ctx - a shared context across all shortcodes

In this case we only have a string of text to highlight so things are pretty simple. We can use this shortcode in a few ways:

[highlight]Orchard Core CMS Shortcodes[/highlight]
[highlight 'Orchard Core CMS Shortcodes']
[highlight text='Orchard Core CMS Shortcodes']

The shortcode delegate will first look for a name argument, called text. If it can't find one, it will grab the default argument at position 0. If there are no arguments, named or default, it will assume there is content between opening and closing shortcode tags.

Using the examples above, the underlying HTML would be rendered as:

<mark>Orchard Core CMS Shortcodes</mark>

This markup will by default highlight the text with a yellow background: Orchard Core CMS Shortcodes.

As part of the AddShortcode extension method you have the opportunity to describe the new shortcode. The shortcode's DefaultValue is the default text that gets added when you insert the shortcode into the HTML editor. The shortcode's Categories setting helps filter the list of shortcodes so it's easy to find this shortcode. Hint and Usage, shown in the image above, inform the user why and how to use the new shortcode. You can see the effect of these values a little better in the previous Orchard Core CMS Tutorial on Shortcode Templates: shortcodes and shortcode templates in Orchard Core CMS.

Conclusion

Congratulations! You've created your first Shortcode Delegate in Orchard Core CMS!

Although shortcodes are still in development at the time of this tutorial, I'm enjoying the new Shortcodes Feature in Orchard Core CMS and it will be interesting to see how other Orchard Core Developers make use of it. I've included theme-specific shortcodes in my custom Orchard Core CMS Themes as well as wrapped a number of liquid templates to make them available to the HTML editor.

So far we've looked at Shortcode Templates and Shortcode Delegates in Orchard Core CMS. Let's dive into Shortcode Providers (i.e. IShortcodeProvider) next time.

You can view my other Orchard Core CMS Tutorials.

Best Wishes!