XperienceCommunity.ChannelSettings
1.0.2
See the version list below for details.
dotnet add package XperienceCommunity.ChannelSettings --version 1.0.2
NuGet\Install-Package XperienceCommunity.ChannelSettings -Version 1.0.2
<PackageReference Include="XperienceCommunity.ChannelSettings" Version="1.0.2" />
paket add XperienceCommunity.ChannelSettings --version 1.0.2
#r "nuget: XperienceCommunity.ChannelSettings, 1.0.2"
// Install XperienceCommunity.ChannelSettings as a Cake Addin #addin nuget:?package=XperienceCommunity.ChannelSettings&version=1.0.2 // Install XperienceCommunity.ChannelSettings as a Cake Tool #tool nuget:?package=XperienceCommunity.ChannelSettings&version=1.0.2
XperienceCommunity.ChannelSettings
This package allows you to easily create strongly-typed Settings models that can be edited per-channel in the Xperience Admin, and retrieved easily, including default fallback values.
Huge shout out to Dragoljub and his repository which laid the groundwork for this module.
Requirements
- Kentico.Xperience.Admin 29.6.0 or newer version to use latest Xperience by Kentico
- net8.0 as a long-term support (LTS) release
Installation
- Install the Nuget Packages into your project:
- There are 3 packages, each with different dependencies for Kentico Libraries, so you can install them seprately on different projects to keep concerns separated
- XperienceCommunity.ChannelSettings.Core = Kentico Agnostic, contains
IChannelCustomSettingsRepository
(settings retrieval) andXperienceSettingsData
(Model decoration) - XperienceCommunity.ChannelSettings = Kentico.Xperience.Core dependent, contains actual logic. Install this on your MVC Site itself.
- XperienceCommunity.ChannelSettings.Admin = Kentico.Xperience.Admin dependent, contains
ChannelCustomSettingsPage
Class which you inherit from and use when creating yourUIPage
for editing your settings.
- In your startup code, add
builder.Services.AddChannelCustomSettings();
Create your Custom Settings Model(s)
Next step is to create your Channel Settings Model class, and decorate the properties with the [XperienceSettingsData("The.Key", defaultValue)]
. The system will read the properties and attributes and use this when saving to the database and retrieving/building your model from settings.
public class SEOChannelSettings
{
[XperienceSettingsData("SEO.ShowRobots", true)]
public virtual bool ShowRobots { get; set; } = false;
[XperienceSettingsData("SEO.Favicon", "~/images/favicon.png")]
public virtual string Favicon { get; set; } = string.Empty;
}
Create (or append) Xperience's Form Annotation Attributes
Xperience will need information on how to display the fields and the form editing of them. This is done through the Xperience FormAnnotation Attributes. You can append them to your Model directly (requires Kentico.Xperience.Admin package), or simply make an inherited class off of your Kentico Agnostic Class.
// This is a special class only for the Admin, overriding the fields and adding the Form Annotations to them.
public class SEOChannelSettingsFormAnnotated : SEOChannelSettings
{
[CheckBoxComponent(Label = "Show Robots", Order = 101)]
public override bool ShowRobots { get; set; } = false;
[UrlSelectorComponent(Label = "Favicon", Order = 102)]
public override string Favicon { get; set; } = "";
}
Add a UI Page to edit the settings
Lastly, you need to define your UI Page to edit this. Copy and paste the code snippet below, Editing the slug
, uiPageType
, name
, and putting your FormAnnotated model as the type for the ChannelCustomSettingsPage<YourModel>
[assembly: UIPage(parentType: typeof(Kentico.Xperience.Admin.Base.UIPages.ChannelEditSection),
slug: "seo-channel-custom-settings",
uiPageType: typeof(SEOChannelSettingsExtender),
name: "SEO Channel settings",
templateName: TemplateNames.EDIT,
order: UIPageOrder.NoOrder)]
namespace XperienceCommunity.ChannelSettings.Admin
{
public class SEOChannelSettingsExtender(Kentico.Xperience.Admin.Base.Forms.Internal.IFormItemCollectionProvider formItemCollectionProvider,
IFormDataBinder formDataBinder,
IChannelCustomSettingsRepository customChannelSettingsRepository,
IChannelSettingsInternalHelper channelCustomSettingsInfoHandler,
IInfoProvider<ChannelInfo> channelInfoProvider)
// Change type below to your settings
: ChannelCustomSettingsPage<SEOChannelSettingsFormAnnotated>(formItemCollectionProvider, formDataBinder, customChannelSettingsRepository, channelCustomSettingsInfoHandler, channelInfoProvider)
{
}
Edit Properties in the Admin
With the above, you can now go to /admin/channels/list
(Admin → Configuration → Channels), select your channel, and you should now see your UI Page on the section when you edit.
Getting your Settings
Retrieiving your settings is quite simple. Inject the IChannelCustomSettingsRepository
into your class, then call the await _channelCustomSettingsRepository.GetSettingsModel<YourModel>()
. This will:
- Analyze the model for
XperienceSettingsData
attributes - Attempt to retrieve and parse values found in the Settings table for the given keys
- Add in Defaults (if defined) where there is no value in the database.
- Return the model.
[ViewComponent]
public class HomeViewComponent(IChannelCustomSettingsRepository channelCustomSettingsRepository) : ViewComponent
{
private readonly IChannelCustomSettingsRepository _channelCustomSettingsRepository = channelCustomSettingsRepository;
public async Task<IViewComponentResult> InvokeAsync()
{
var settings = await _channelCustomSettingsRepository.GetSettingsModel<SEOChannelSettings>();
// Any retrieval here
var model = new HomeViewModel(settings.ShowRobots)
{
// Properties here
};
return View("/Features/Home/Home.cshtml", model);
}
}
Dependency Keys
The IChannelCustomSettingsRepository
already has data caching applied to make sure retrieval is quick and doesn't require multiple database queries, and it has it's own Cache Dependency Key settings to make sure data is cleared upon updates.
However, if you are using <cache>
tags, you can use the IChannelCustomSettingsRepository.GetSettingModelDependencyKeys<YourModel>();
to get a list of all the cache dependency keys that went into making the settings model.
Migration from KX13
You should be able to migrate your CMS_SettingsKeys into the new database table and use the Attributes to make similar Settings Models. I would simply write SQL once this is installed to move things over.
KeyName ⇒ ChannelCustomSettingKeyName KeyValue ⇒ ChannelCustomSettingKeyValue KeySiteID ⇒ ChannelCustomSettingKeyChannelID KeyGUID ⇒ ChannelCustomSettingGuid
The following should be coded as part of the Form Data Annotation / Model:
KeyDisplayName ⇒ Use FormAnnotation Order
KeyType (Just the property type)
KeyCategoryID ⇒ You can either split it into different Models, or use the FormCategory
attribute on your FormAnnotated class
KeyOrder ⇒ Use FormAnnotation Order
Global Settings
For settings that are global, you should probably consider using AppSettings.json and transformations for almost all of those needs, or a simple Custom Module Class.
Contributions and Support
Feel free to fork and submit pull requests or report issues to contribute. Either this way or another one, we will look into them as soon as possible.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Kentico.Xperience.Core (>= 29.6.0)
- XperienceCommunity.ChannelSettings.Core (>= 1.0.2)
NuGet packages (3)
Showing the top 3 NuGet packages that depend on XperienceCommunity.ChannelSettings:
Package | Downloads |
---|---|
XperienceCommunity.Baseline.Core.Library.Xperience
The Baseline a set of Core Systems, Tools, and Structure to ensure a superior Kentico Website that's easy to migrate, for Kentico Xperience 13 and eventually Xperience by Kentico |
|
XperienceCommunity.ChannelSettings.Admin
Allows easy creation and modification of Channel Settings in Xperience by Kentico |
|
XperienceCommunity.Baseline.Account.Library.Xperience
The Baseline a set of Core Systems, Tools, and Structure to ensure a superior Kentico Website that's easy to migrate, for Kentico Xperience 13 and eventually Xperience by Kentico |
GitHub repositories
This package is not used by any popular GitHub repositories.
Set KeyValue to be nullable