Abp.SettingUi

An ABP module used to manage ABP settings

If you are using ABP version <2.1.1, please see Abp.SettingManagement.Mvc.UI

Features

• Manage ABP setting values via UI
• Support localization
• Group settings
• Display settings with appropriate input controls

Online Demo

We have launched an online demo for this module: https://settingui.samples.easyabp.io

Installation

Add ABP packages with AbpHelper (Recommended)

Run following command in your ABP project root folder:

abphelper module add EasyAbp.Abp.SettingUi -ashlw

Add ABP packages manually

1. Install the following NuGet packages.

   • EasyAbp.Abp.SettingUi.Application
   • EasyAbp.Abp.SettingUi.Domain.Shared
   • EasyAbp.Abp.SettingUi.HttpApi
   • EasyAbp.Abp.SettingUi.HttpApi.Client (Only Tiered structure is needed)
   • EasyAbp.Abp.SettingUi.Web

2. Add DependsOn(typeof(AbpSettingUiXxxModule)) attribute to configure the module dependencies. (see how)

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

1. Add permissions ("Setting UI" - "Tenant") to the roles you want.

   

2. 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.

1. 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

2. 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地址."
           }
       }

3. 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:

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

1. 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

   

2. 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:

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 support 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:

    

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

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

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