Creating Custom Settings in Orchard Core CMS A tutorial on OrchardCore.CustomSettings for Orchard Core Developers.

Custom Settings in Orchard Core

Imagine you’re developing an Orchard Core website and there are pieces of information about the site or organization that you constantly display throughout the website. Let’s pretend it’s contact information, like an email address and phone number, that are used in various public relations articles, contact and about pages, site header and footer, etc. Hard coding this information on every page may not be the best course of action, because if it ever changes, you will have to manually change it in multiple places across the website. Instead, you and your client prefer that it be a setting in the Orchard Core backend that can easily be changed and updated across the website.

Although there are several ways to tackle this challenge, Orchard Core has a specific feature to address such needs, Custom Settings. The Custom Settings feature allows you to use a custom content type as a cohesive collection of custom settings that can be populated and updated from the backend and displayed throughout your website with no coding. The custom settings appear as a separate menu item under Configuration -> Settings in the Orchard Core dashboard with its own set of permissions. These settings can then be accessed globally throughout the website via Razor, Liquid, shortcodes, code, etc.

Creating a Custom Content Type for Orchard Core Custom Setting

The first step to creating custom settings in Orchard Core is to create a new custom content type for these settings. It’s important that you create a new content type and not use an existing content type to avoid breaking any functionality used by the existing content type. You can name the content type anything you want, but you may want to name it with a suffix of “Settings” or “CustomSettings” for clarity and to avoid clashing with a name you may want to use later. In our example we are holding contact information, so let’s name the Content Type “ContactSettings” with a display name of “Contact”.

Custom Settings Content Type Definition in Orchard Core

I’ve reduced the screenshot above to it’s most important parts. At most, you want the new custom settings content type to be “Versionable”. You can uncheck "Creatable", "Listable", "Draftable", and "Securable". And, most importantly, it needs to have a stereotype of “CustomSettings”. It is the stereotype of “CustomSettings” that tells Orchard Core that this content type holds custom settings that will be displayed in the Orchard Core dashboard and made available throughout the Orchard Core website.

Add any Orchard Core content fields and content parts you wish to the new content type. In our example, I added the Email and Phone fields that will be used throughout the Orchard Core website in various pages and widgets. Once completed, our new custom settings content type will be displayed in the list of other content types with a badge of "CustomSettings".

Custom Settings Content Type Orchard Core

Custom Settings Permissions in Orchard Core

Every content type you create with a stereotype of “CustomSettings” will have its own set of permissions. By default, the “Administrator” role in Orchard Core will have access to these settings. However, depending on your needs, you may want to adjust which roles have permissions to these custom settings. Just know that this can easily be done for each role from the administrative dashboard in Orchard Core.

Custom Settings Permissions in Orchard Core

Managing Custom Settings in Orchard Core

Once you’ve properly created the new content type that will serve as your custom settings and adjusted the permissions of these custom settings based on your needs, you will now be able to populate and manage these custom settings from the Orchard Core backend.

All custom settings will appear under the Configuration -> Settings menu in the Orchard Core dashboard. This is typically where Orchard Core Developers will put settings for their custom modules. I’ve done this will almost all my custom modules mentioned in my portfolio (e.g. Live Chat, Google Analytics, JotForm, Calendly, etc.).

The name of the admin menu item will be the display name of the content type. This is why I called the technical name of the content type, "ContactSettings", and the display name, "Contact". A display name of "Contact" makes more sense than "Contact Settings", which would be a little redundant for the admin menu item.

Custom Settings Admin Menu Item in Orchard Core

Once you navigate to the custom settings you will be able to populate all content fields and content parts associated with the content type in Orchard Core.

Accessing the Custom Settings on the Orchard Core Website

You have full access to the custom settings throughout the Orchard Core website via code in Orchard Core modules or various shapes written in Razor and Liquid. You can even create shortcodes, and especially shortcode templates, that access these custom settings by wrapping a Liquid template.

Here is an example of accessing the email address and phone number that are part of our custom settings content type from within a Liquid shape.

Phone: {{ Site.Properties.ContactSettings.ContactSettings.Phone.Text }}
Email: {{ Site.Properties.ContactSettings.ContactSettings.Email.Text }}

You can also access the contact settings from a controller or service in your Orchard Core module by injecting an instance of ISiteService.

public class ContactSettingsController : Controller
{
    private readonly ISiteService _siteService;
    public ContactSettingsController(ISiteService siteService)
    {
        _siteService = siteService;
    }

    public async Task<IActionResult> Index()
    {
        var siteSettings = await _siteService.GetSiteSettingsAsync();
        var contactSettings = siteSettings.As<ContentItem>("ContactSettings");

        ...
    }
}

Conclusion

Let's wrap up what we learned in this Orchard Core Tutorial. We created a custom content type with a stereotype of "CustomSettings" that holds the custom settings we wish to manage on the Orchard Core website. Each custom settings content type has its own set of permissions and we adjusted those permissions based on our needs.

Orchard Core detected the new custom settings and created a new admin menu item under Configuration -> Settings based on the display name of the content type. By navigating to this menu item we were able to populate and manage these custom settings.

Using a Liquid template we were able to access these custom settings and inject them into various pages and wigets on the Orchard Core Website. If necessary, we are also able to access these same settings in code via an instance of ISiteService.

If you wish to use these custom settings in a Text Field, HTML Field, or HTML BodyPart, we can create a custom shortcode or shortcode template.