Module: Custom modules: custom settings

7 of 9 Pages

Use the Options pattern to access channel-specific settings

✖
Copy to clipboard

When you build custom module UIs with Xperience by Kentico, chances are you’ll need to access and react to the data stored in the modules’ classes.

Let’s go over the process of accessing and utilizing the values of module classes that are associated with specific web channels with practical examples. We will explore how to access custom channel-specific settings with Microsoft’s options pattern, then later without.

Earlier in this series, we went over the process of creating custom channel-specific settings:

Now, we’ll dive into the process of accessing these settings in code.

Work with the Options pattern (Serve robots.txt)

As with the global configurations described in the earlier guide, you can use channel-specific custom module configurations with the options pattern.

To put this into practice, let’s create functionality to serve the robots.txt file specified in the SEO settings of the we created earlier.

Populate the data

Start by adding data for the code to retrieve.

For this guide’s example, navigate to Project settings → Channel settings → Training guides pages → SEO settings in the admin UI.

Save a value to the Robots.txt text box, for example:

Text 

ignore: *

Set up options

Moving to the code files, create an options class to hold all the data your front-end needs, and a corresponding options setup class to populate that data.

To retrieve the value of your setting, use an IWebsiteChannelContext instance to determine which channel’s module data to retrieve, and an IInfoProvider<TInfo> for each module class you need to access.

Then, register the setup class with the dependency injection container during startup, for example in an IServiceCollection extension method.

If you’re following along with the example, add a folder called SEO within the Features directory of the TrainingGuides.Web project.

Create options and options setup classes for robots.txt.
Make sure to evaluate the current channel to retrieve the correct settings.
C#
RobotsOptions.cs 

namespace TrainingGuides.Web.Features.SEO;

public class RobotsOptions
{
    public string RobotsText { get; set; } = string.Empty;
}

C#
RobotsOptionsSetup.cs 


using CMS.DataEngine;
using CMS.Websites.Routing;
using Microsoft.Extensions.Options;
using TrainingGuides.ProjectSettings;

namespace TrainingGuides.Web.Features.SEO;
public class RobotsOptionsSetup : IConfigureOptions<RobotsOptions>
{
    private readonly IInfoProvider<SeoSettingsInfo> seoSettingsInfoProvider;
    private readonly IWebsiteChannelContext websiteChannelContext;
    private readonly IInfoProvider<WebChannelSettingsInfo> webChannelSettingsInfoProvider;

    public RobotsOptionsSetup(IInfoProvider<SeoSettingsInfo> seoSettingsInfoProvider, IWebsiteChannelContext websiteChannelContext, IInfoProvider<WebChannelSettingsInfo> webChannelSettingsInfoProvider)
    {
        this.seoSettingsInfoProvider = seoSettingsInfoProvider;
        this.websiteChannelContext = websiteChannelContext;
        this.webChannelSettingsInfoProvider = webChannelSettingsInfoProvider;
    }

    public void Configure(RobotsOptions options)
    {
        int currentChannelID = websiteChannelContext.WebsiteChannelID;

        var channelSettings = webChannelSettingsInfoProvider
            .Get()
            .WhereEquals(nameof(WebChannelSettingsInfo.WebChannelSettingsChannelID), currentChannelID)
            .FirstOrDefault();

        var seoSettings = seoSettingsInfoProvider.Get()
            .WhereEquals(nameof(SeoSettingsInfo.SeoSettingsWebChannelSettingID), channelSettings?.WebChannelSettingsID ?? 0)
            .FirstOrDefault();

        options.RobotsText = seoSettings?.SeoSettingsRobots ?? string.Empty;
    }
}

Then, in the ServiceCollectionExtensions.AddTrainingGuidesOptions method from the earlier guide, use the IServiceCollection.ConfigureOptions method to register your options.

C#
ServiceCollectionExtensions.cs 

...
public static void AddTrainingGuidesOptions(this IServiceCollection services)
{
    ...
    services.ConfigureOptions<RobotsOptionsSetup>();
}
...

You can find the complete file in the finished branch of the Training guides repository for reference.

Utilize the options in your project

Once you have set up and registered, you can utilize them anywhere in your site that allows dependency injection.

Choose which Options interface to use

In cases where the values of the options do not change during the life of the application, you can use IOptions<TOptions> to retrieve the value. It is a singleton service that evaluates the options when the application stops.

In this case, you’ll most likely want to use IOptionsSnapshot<TOptions> instead, as it is a scoped service that re-evaluates the options whenever it is constructed. This ensures that if users make changes to your module objects after the application starts, the new values will be included in the options.

For our example, let’s create a controller that returns a text response with the value of the robots.txt setting from the injected options.

C#
RobotsController.cs 


using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

namespace TrainingGuides.Web.Features.SEO;
public class RobotsController : Controller
{
    private readonly IOptionsSnapshot<RobotsOptions> robotsOptions;

    public RobotsController(IOptionsSnapshot<RobotsOptions> robotsOptions)
    {
        this.robotsOptions = robotsOptions;
    }

    [HttpGet("/robots.txt")]
    public IActionResult Index() => Content(robotsOptions.Value.RobotsText, "text/plain");
}

See the result

If you’ve followed along with the example, try visiting the /robots.txt path of the live site.

You should see a response containing the value you saved in the SEO settings.

Screenshot of robots.txt page

Feel free to change the value of the setting, and see that it is reflected in this response.

7 of 9