# Abp.SettingUi

(opens new window) (opens new window) (opens new window) (opens new window) (opens new window)

An ABP (opens new window) module used to manage ABP settings

demo

If you are using ABP version <2.1.1, please see Abp.SettingManagement.Mvc.UI (opens new window)

# Features

Manage ABP setting values via UI
Support localization
Group settings
Display settings with appropriate input controls
Control display of settings by permissions

# Online Demo

We have launched an online demo for this module: https://settingui.samples.easyabp.io (opens new window)

# Installation

# Add ABP packages with AbpHelper (opens new window) (Recommended)

Run following command in your ABP project root folder:

abphelper module add EasyAbp.Abp.SettingUi -acshlw

# Add ABP packages manually

Install the following NuGet packages.
- EasyAbp.Abp.SettingUi.Application
- EasyAbp.Abp.SettingUi.Application.Contracts
- EasyAbp.Abp.SettingUi.Domain.Shared
- EasyAbp.Abp.SettingUi.HttpApi
- EasyAbp.Abp.SettingUi.HttpApi.Client (Only Tiered structure (opens new window) is needed)
- EasyAbp.Abp.SettingUi.Web
Add DependsOn(typeof(AbpSettingUiXxxModule)) attribute to configure the module dependencies. (see how (opens new window))

# Configure localization resource

In order to let SettingUi module use localization resources from this application, we need to add them to SettingUiResource:

MyAbpApp.Domain.Shared project - MyAbpAppDomainSharedModule class

Configure<AbpLocalizationOptions>(options =>
{
    ...
    options.Resources
        .Get<SettingUiResource>()
        .AddVirtualJson("/Localization/MyAbpApp");
});

# Usage

Grant permission ("Setting UI" - "Show Setting Page")
Refresh the browser then you can use "Administration" - "Settings" menu to see all ABP built-in settings

# Manage custom settings

Beside ABP built-in settings, you can also use this module to manage your own settings.

Define a setting

MyAbpApp.Domain project - Settings/MyAbpAppSettingDefinitionProvider class

public class MyAbpAppSettingDefinitionProvider : SettingDefinitionProvider
{
    public override void Define(ISettingDefinitionContext context)
    {
        context.Add(
            new SettingDefinition(
                "Connection.Ip", // Setting name
                "127.0.0.1", // Default value
                L("DisplayName:Connection.Ip"), // Display name
                L("Description:Connection.Ip") // Description
            ));
    }

    private static LocalizableString L(string name)
    {
        return LocalizableString.Create<MyAbpAppResource>(name);
    }
}

The setting name is "Connection.Ip"
Provide a default value: "127.0.0.1"
Set the DisplayName and Description to a localizable string by using a helper method L. The format "DisplayName:{SettingName}" is the convention recommended by ABP

For ABP setting system, please see Settings document (opens new window)

Define localization resources for the setting, for demonstration purpose, we defined English and Chinese localization resources

MyAbpApp.Domain.Shared project

Localization/MyAbpApp/en.json

{
    "culture": "en",
    "texts": {
        ...
        "DisplayName:Connection.Ip": "IP",
        "Description:Connection.Ip": "The IP address of the server."
    }
}

Localization/MyAbpApp/zh-Hans.json

{
    "culture": "zh-Hans",
    "texts": {
        ...
        "DisplayName:Connection.Ip": "IP",
        "Description:Connection.Ip": "服务器的IP地址."
    }
}

Relaunch the application, we can see the setting displayed, and the localization also works

# Grouping

You may notice that our custom setting is displayed in "Others" tab, and "Others" card, these are the default group display names called "Group1" and "Group2" respectively:

group

So how can we custom the group of the setting? There are two ways:

Use WithProperty method

The WithProperty method is a method provided by ABP SettingDefinition class, we can directly use it in setting defining:

MyAbpApp.Domain project - Settings/MyAbpAppSettingDefinitionProvider class

context.Add(
    new SettingDefinition(
            "Connection.Ip", // Setting name
            "127.0.0.1", // Default value
            L("DisplayName:Connection.Ip"), // Display name
            L("Description:Connection.Ip") // Description
        )
        .WithProperty(SettingUiConst.Group1, "Server")
        .WithProperty(SettingUiConst.Group2, "Connection")
);

The constants Group1 and Group2 are defined in the SettingUiConst class
Set the "Server" to "Group1", and "Connection" to "Group2"

Then we should provide the localization resource for these two group names:

MyAbpApp.Domain.Shared project

Localization/MyAbpApp/en.json

{
    "culture": "en",
    "texts": {
        ...
        "Server": "Server",
        "Connection": "Connection"
    }
}

Localization/MyAbpApp/zh-Hans.json

{
    "culture": "zh-Hans",
    "texts": {
        ...
        "Server": "服务器",
        "Connection": "连接"
    }
}

Relaunch the application and see if the group names are correctly set

group-name

Use setting property file

Another way of setting group is use the setting property file, which is provided by the SettingUi module. It's useful when you can not easily modify the setting definition, or you want to put the grouping information into one single place.

For demonstration in this way, let's define a new setting:
- MyAbpApp.Domain project - Settings/MyAbpAppSettingDefinitionProvider class
```
new SettingDefinition(
    "Connection.Port",
    8080.ToString(),
    L("DisplayName:Connection.Port"),
    L("Description:Connection.Port")
)
```
The steps of adding localization for this setting are omitted.

Then we need to create a new json file with arbitrary filename, however the path must be "/SettingProperties", because SettingUi module will look for the setting property files from this path.
- MyAbpApp.Domain.Shared project - /SettingProperties/MySettingProperties.json file
```
{
    "Connection.Port": {
        "Group1": "Server",
        "Group2": "Connection"
    }
}
```
  - The setting name Connection.Port as the key of the JSON object
  - Use "Group1" and "Group2" to set the grouping names
- Relaunch the application to see the new grouped setting

# Setting types

By default a setting value is string type, which will be rendered as a text input control in UI. We can custom it simply by providing a setting property "Type":

MyAbpApp.Domain.Shared project - /SettingProperties/MySettingProperties.json file

{
    "Connection.Port": {
        "Group1": "Server",
        "Group2": "Connection",
        "Type": "number"
    }
}

Set the "Connection.Port" setting type to "number"

No need to relaunch the application, just press F5 to refresh the browser, you should be able to see the effect immediately:

type-number

Now the input type changed to "number", and the frontend validations also work.

The setting types can also be configured through WithProperty method, like WithProperty("Type", "number")

For now SettingUi supports following setting types:

text (default)
number
checkbox

select

Needs an additional property "Options" to provide select options, which is a string separated by a vertical bar (|)

"Connection.Protocol": {
    "Group1": "Server",
    "Group2": "Connection",
    "Type": "select",
    "Options": "|HTTP|TCP|RDP|FTP|SFTP"
}

The render result:

selection

This is the end of the tutorial. Through this tutorial, you should be able to easily manage your settings using SettingUi. The source of the tutorial can be found in the sample folder (opens new window).

# Localization

The SettingUi module uses ABP's localization system to display the localization information of the settings.The languages currently supported are:

en
zh-Hans
tr

The localization resource files are under /Localization/SettingUi of the EasyAbp.Abp.SettingUi.Domain.Shared project.

You can add more resource files to make this module support more languages. Welcome PRs 😊 .

For ABP's localization system, please see the document (opens new window)

# Permissions

SettingUi controls whether to display SettingUi's page by checking the SettingUi.ShowSettingPage permission.

As long as the permission is granted, all settings in the system can be modified through SettingUi.

But sometimes, we don't want users to see certain settings in SettingUi, which can be achieved by defining specific permissions.

For example, if we need to hide the "system" group from users, then we need to add a child permission of SettingUi.ShowSettingPage, the name of the permission is SettingUi.System. The code is as follows:

public override void Define(IPermissionDefinitionContext context)
{
    var settingUiPage = context.GetPermissionOrNull(SettingUiPermissions.ShowSettingPage);  // Get ShowSettingPage permission
    var systemGroup = settingUiPage.AddChild("SettingUi.System", L("Permission:SettingUi.System")); // Add display permission of Group1: System
}

In this way, when SettingUi enumerates the settings, if a permission in the form of SettingUi.Group1 is found, the Group1 will only be displayed after the permission is explicitly granted.

You can also use the SettingUiPermissions.GroupName variable. The effect is the same as the above code. The code is as follows:

public override void Define(IPermissionDefinitionContext context)
{
    var settingUiPage = context.GetPermissionOrNull(SettingUiPermissions.ShowSettingPage);  // Get ShowSettingPage permission
    var systemGroup = settingUiPage.AddChild(SettingUiPermissions.GroupName + ".System", L("Permission:SettingUi.System")); // Add display permission of Group1: System
}

We can continue to add permissions to control Group2, such as "System" -> "Password" group, we need to add a permission with the Group2 name as the suffix, the code is as follows:

public override void Define(IPermissionDefinitionContext context)
{
    ...
    var passwordGroup = systemGroup.AddChild("SettingUi.System.Password", L("Permission:SettingUi.System.Password"));   // Add display permission of Group2: Password
}

In this way, when SettingUi enumerates the settings, if a permission in the form of SettingUi.Group1.Group2 is found, the Group2 in Group1 will only be displayed after the permission is explicitly granted.

Of course, we can also continue to add a permission to precisely control a specified setting, such as "System" -> "Password" -> "Required Length", we need to add a permission with the setting name as the suffix, the code is as follows:

public override void Define(IPermissionDefinitionContext context)
{
    ...
    var requiredLength = passwordGroup.AddChild("SettingUi.System.Password.Abp.Identity.Password.RequiredLength", L("Permission:SettingUi.System.Password.RequiredLength"));    // Add display permission of Abp.Identity.Password.RequiredLength
}

In this way, when SettingUi enumerates the settings, if a permission in the form of SettingUi.Group1.Group2.SettingName is found, the setting in Group2 in Group1 will only be displayed after the permission is explicitly granted.

Through the above three-level permission definition way, we can arbitrarily control the display of settings in SettingUi.

The following figure is a screenshot of Setting Ui permissions, and the displayed result:

setting_permission

For ABP's permission system, please see the document (opens new window)

Features

Online Demo

Installation

Add ABP packages with AbpHelper (Recommended)

Add ABP packages manually

Configure localization resource

Usage

Manage custom settings

Grouping

Setting types