学习011-03-06 Change the Format Used for the FullAddress and FullName Properties

Change the Format Used for the FullAddress and FullName Properties（更改 FullAddress 和 FullName 属性使用的格式）

There are FullAddress and FullName properties in the Address and Person business classes that are supplied with the Business Class Library. These properties are calculable. The FullAddress property represents a string formed by the concatenation of the Country.Name, StateProvince, City, Street and ZipPostal property values. The FullName property is formed by the concatenation of the FirstName, MiddleName and LastName property values. The FullAddress and FullName properties are implemented so that you can change the order in which the items are concatenated. This topic details how to change this order. You can use this technique when implementing analogous business class properties.
业务类库提供的Address和Person业务类中有FullAddress和FullName属性。这些属性是可计算的。FullAddress属性表示由Country.Name、State省、城市、街道和ZipPostal属性值串联而成的字符串。FullName属性由FirstName、MiddleName和LastName属性值串联而成。实现FullAddress和FullName属性是为了更改项目串联的顺序。本主题详细介绍了如何更改此顺序。您可以在实现类似的业务类属性时使用此技术。

The following images demonstrate how the FullAddress and FullName properties are calculated.
下图演示了如何计算FullAddress和FullName属性。

To format FullAddress and FullName properties, the ObjectFormatter.Format method of the helper ObjectFormatter class is used. In this method, the format, according to which the property value is generated, is taken as a parameter. The format passed for the FullAddress property is specified by the Address class’ FullAddressFormat property. The format that is passed for the FullName property is specified by the Person class’ FullNameFormat property. Note that FullAddress and FullName properties are non-persistent calculated properties. As such, they require persistent aliases to be created for them to support sorting in Server, ServerView, InstantFeedback, and InstantFeedbackView mode (see CollectionSourceBase.DataAccessMode). For this purpose, there are additional FullNamePersistentAlias and FullAddressPersistentAlias properties. These properties are used to create persistent aliases.
要格式化FullAddress和FullName属性，需要使用辅助程序ObjectFormat类的ObjectFormat. Format方法。在此方法中，将生成属性值所依据的格式作为参数。为FullAddress属性传递的格式由Address类的FullAddressFormat属性指定。为FullName属性传递的格式由Person类的FullNameFormat属性指定。请注意，FullAddress和FullName属性是非持久计算属性。因此，它们需要为它们创建持久别名以支持Server、ServerView、InstantFeedback和InstantFeedbackView模式下的排序（参见CollectionSourceBaseDataAccessMode）。为此，有额外的FullNamePersistentAlias和FullAddressPersistentAlias属性。这些属性用于创建持久别名。

By default, the FullAddressFormat property is set to the Address class’ defaultFullAddressFormat constant, which is the following: “{Country.Name}; {StateProvince}; {City}; {Street}; {ZipPostal}”. The FullAddressFormatPersistentAlias property is set to the Address class’ defaultFullAddressPersistentAlias constant, which is the following: “concat(Country.Name, StateProvince, City, Street, ZipPostal)”. To change these property values, use the SetFullAddressFormat method (SetFullNameFormat for the Person class). These methods are static, so you can call them any place in your solution. For instance, you can specify the required format in the configuration file and read its value in a module’s constructor. In addition, override the module’s ModuleBase.CustomizeTypesInfo method and process the CalculatedPersistentAlias attribute via the static CalculatedPersistentAliasHelper.CustomizeTypesInfo method.
默认情况下，FullAddressFormat属性设置为Address类的defaultFullAddressFormat常量，如下所示：“{Country.Name}；{State省}；{城市}；{街道}；{ZipPostal}”。FullAddressFormatPersistentAlias属性设置为Address类的defaultFullAddressPersistentAlias常量，如下所示：“conat（Country.Name， State省，城市，街道，ZipPostal）”。要更改这些属性值，请使用SetFullAddressFormat方法（SetFullNameFormat for the Person类）。这些方法是静态的，因此您可以在解决方案中的任何位置调用它们。例如，您可以在配置文件中指定所需的格式，并在模块的构造函数中读取其值。此外，覆盖模块的ModuleBase.CustomizeTypesInfo方法并通过静态CalculatedPersistentAliasHelperCustomizeTypesInfo方法处理CalculatedPersistentAlias属性。

XML 
<configuration>
    <appSettings>
        <add key="FullAddressFormat" value="{Country.Name} {City} {Street}" />
        <add key="FullAddressFormatPersistentAlias" value="concat(Country.Name, City, Street)" />
        <!-- ... -->
    </appSettings>
</configuration>

C# 
using DevExpress.Persistent.BaseImpl;
using System.Configuration;
//...
public sealed partial class MainDemoModule : ModuleBase {
    static MainDemoModule() {
        Address.SetFullAddressFormat(ConfigurationManager.AppSettings["FullAddressFormat"], 
            ConfigurationManager.AppSettings["FullAddressFormatPersistentAlias"]);
    }
    public override void CustomizeTypesInfo(ITypesInfo typesInfo) {
        base.CustomizeTypesInfo(typesInfo);
        CalculatedPersistentAliasHelper.CustomizeTypesInfo(typesInfo);
    }
    //...
}

After formatting a FullAddress property using the specified format, the property names that are enclosed in curly brackets will be replaced with the current object’s property values (see the image above).
使用指定格式格式化FullAddress属性后，括在大括号中的属性名称将替换为当前对象的属性值（参见上图）。

Analogous to the Address class’ FullAddressFormat property, the Person class’ FullNameFormat property is set to the defaultFullNameFormat constant, which is the following: “{FirstName} {MiddleName} {LastName}”. The FullNamePersistentAlias property is set to the defaultFullNamePersistentAlias constant, which is the following: “concat(FirstName, MiddleName, LastName)”. As the SetFullNameFormat method is static, you are free to call it where required. For instance, you can use the value specified in the configuration file as demonstrated in the code above.
类似于Address类的FullAddressFormat属性，Person类的FullNameFormat属性设置为defaultFullNameFormat常量，如下所示：{FirstName}{MiddleName}{LastName}。FullNamePersistentAlias属性设置为defaultFullNamePersistentAlias常量，如下所示：conat（FirstName， MiddleName，LastName）。由于SetFullNameFormat方法是静态的，您可以在需要时调用它。例如，您可以使用配置文件中指定的值，如上面的代码所示。

Note
In the Main Demo, you can set a custom format for the FullName property in the common module’s constructor, as described above.
在Main Demo中，您可以为公共模块的构造函数中的FullName属性设置自定义格式，如上所述。

When implementing business class properties whose values require formatting, introduce static properties like FullAddressFormat and FullNameFormat, so that anyone using your business class can modify the formatting. The following code can be used as an example:
在实现值需要格式化的业务类属性时，引入FullAddressFormat和FullNameFormat等静态属性，以便任何使用您的业务类的人都可以修改格式。以下代码可以作为示例：

C# 
public class SampleAddress : BaseObject {
    private const string defaultFullAddressFormat = "{Country.Name}; {StateProvince};" +
       " {City}; {Street}; {ZipPostal}";
    private static string fullAddressFormat = defaultFullAddressFormat;
    public static string FullAddressFormat {
        get { return fullAddressFormat; }
        set {
            fullAddressFormat = value;
            if(string.IsNullOrEmpty(fullAddressFormat)) {
                fullAddressFormat = defaultFullAddressFormat;
            }
        }
    }
    public string FullAddress {
        get {
            return ObjectFormatter.Format(fullAddressFormat, this, 
               EmptyEntriesMode.RemoveDelimiterWhenEntryIsEmpty );
        }
    }
}