How to: Allow an Administrator to Create Custom Persistent Fields in an XPO-Based Application

You can allow an application administrator to create custom persistent fields and display the added fields' data in the UI without recompiling the application. In this example, the SkypeID field will be added to the Contact business object in the MainDemo application.

CustomPersistentFields_Result

The following sections describe the process of implementation custom persistent fields from application settings to runtime customization.

Prerequisites

Ensure that your application does not contradict the following conditions. Otherwise, creating new persistent fields is impossible at runtime.

Setup the Application

Apply the following changes in the application code to allow application administrators to create and display custom persistent field data in the UI.

Choose the Model Editor Type

It is necessary to determine which type of the Model Editor is appropriate for your application: standalone or built-in.

  • A built-in Model Editor

    When an administrator uses a WinForms application, it is possible to invoke the built-in Model Editor tool to add a custom field to the application model. Using this Model Editor type, the administrator can edit both Model Differences stored in the application database and Model Differences from the XAFML file.

  • A standalone Model Editor

    The use of the standalone Model Editor is preferred if an administrator uses only an ASP.NET application and Model Differences are stored in the XAFML file. To use this tool, copy the DevExpress.ExpressApp.ModelEditor.v18.2.exe and DevExpress.ExpressApp.ModelEditor.v18.2.config files from the %PROGRAMFILES(x86)%\DevExpress 18.2\Components\Tools\eXpressAppFramework\Model Editor folder to the application installation folder.

Implement the Persistent Field and Display It

Follow the steps below to add a custom persistent field at an end-user workstation.

  1. Invoke the built-in Model Editor using the Tools | Edit Model command at runtime or close the application and start the standalone Model Editor by running the DevExpress.ExpressApp.ModelEditor.v18.2.exe executable file.

    If you use the standalone Model Editor, specify the path to the application configuration file (e.g., MainDemo.Win.exe.config or Web.config) and click Open in the Open Model dialog.

    CustomPersistentFields_RunME

  2. Navigate to the BO_Model | Contact node in the tree on the left. Right-click the OwnMembers child node and choose Add... | Member.

    CustomPersistentFields_AddMember

  3. Set the Name property of the newly added node to "SkypeID". Then, set the IsCalculated property to "False", Type to "System.String", Size to "32", and Caption to "Skype ID".

    CustomPersistentFields_MemberProperties

  4. If the built-in Model Editor is in use, copy the differences that you have introduced in the administrator's layer using the Merge Differences command. Otherwise, skip this step and move to the next one.

    CustomPersistentFields_Merge

  5. Save changes using the Save button or the CTRL+S shortcut and restart the Model Editor.
  6. Navigate to the Views | Contact_DetailView node in the tree on the left. Right-click the Items child node and choose Add... | PropertyEditor.

    CustomPersistentFields_AddEditor1

  7. Set PropertyName and Id to "SkypeID".

    CustomPersistentFields_AddEditor2

  8. Focus the Layout node. Right-click the empty space within the form preview displayed on the right and select Customize Layout.

    CustomPersistentFields_AddEditor3

  9. Drag the Skype ID item from the invoked Customization window to an appropriate position within the form.

    CustomPersistentFields_AddEditor4

    You can also add the Skype ID column to the Contact List View using a similar approach (see List View Columns Customization).

  10. If the built-in Model Editor is in use, merge the differences as described at the forth step.
  11. Save the changes and close the Model Editor.
  12. Update your database schema as described in the Apply Changes to the Database section.
  13. Restart the application and open the Contact Detail View to see the result demonstrated in the introduction of this topic.
Important

If the application is installed on several PCs and the Administrator's Model Differences are stored in the Model.xafml file, copy it from the application's working folder to each PC. Otherwise, the created field will be available only at the workstation where you added it.

Apply Changes to the Database

Use the DBUpdater tool to add the column mapped to the newly created custom persistent field to the database.

Open the Command Prompt, change the current directory to the applications working directory, and run the following command.

DBUpdater.v18.2.exe MainDemo.Win.exe.config -forceUpdate