View Models
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
Generates customizable view model classes for UI search or details views based on the type of their associated data object.
The generated view models are C# classes based on Xomega Framework, which can
be reused in different types of C# clients, such as ASP.NET WebForms or WPF. The view models store their underlying data objects,
and provide logic for handling view actions and navigating between views, passing any input parameters to those views,
and handling the output parameters. The generated navigation logic is based on the view links that are defined in the model.
You can add your customizations to a subclass of the generated view model, and implement any reusable platform-independent
view logic there, such as custom actions or navigation.
Views. The generator uses view models of the view definitions in the Xomega model in order to generate
the corresponding C# classes. Each view model is associated with a specific data object that is also defined in the model.
The generator will create search or details types of view models based on whether or not the data object is a list object,
as specified by its list attribute. The logic for the standard actions on those view models, such as running the
search or saving the view, will be mostly inherited from the corresponding base classes in the Xomega Framework, but can
be overridden or extended in a customized subclass. Such subclass can be generated if you set the customize attribute
to "true" on the ui:view-model element. The following snippet shows an example of a view model definition in the
Xomega model.
Lnks. Named links between views are defined on the data object of the view model, or on any of its child
or descendant sub-objects. For each link, you can specify the target view, whether or not it should be opened as a child
view, the field on which to display the link, as well as the input and output parameters for the view. For input parameters,
you can specify the literal value to pass, or the name of the data object's field to source it from. Similarly, for link
output parameters, you can specify the data object fields to populate when the view is closed, e.g. when the view is used
for selection. The snippet below illustrates configuration of links in the model.
Note, that most of this setup of view models in the Xomega model for standard details and list objects can be easily added
automatically by a special model enhancement CRUD generator.
1.2 Generator outputs
This generator creates C# classes for view models derived from an appropriate Xomega Framework base class, with code to
handle navigation based on data object's links, as well as a static class for registering these view models for Dependency Injection (DI)
with the service container. It adds the generated classes to the specified project, which is usually a separate project
that can be reused between different types of clients.
For view models that are decorated with a customize attribute set to “true”, it also creates a subclass of the
generated view model with a postfix Customized appended to the class name, if one does not exist yet. It will use this name
for DI registration, and can also nest the customized class under the generated view model in the project, if so configured.
2. Configuration
The following sections describe configuration parameters used by the generator.
2.1 Generator parameters
The following table lists configuration parameters that are set as the generator’s properties.
| Parameter |
Value Example |
Description |
| Generator Name |
View Models
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder |
Presentation Layer\View Models
|
Folder path to the generator inside the Model project. The folders are separated by a backslash (\). |
| Include In Build |
True
|
A flag indicating whether or not running this generator should be included in building of the model project. |
| Output |
| Output Path |
../MySolution.Client.Common /ViewModels/{Module/}{File}.cs |
Relative path where to output files with generated View Models. The path may contain {Module/} and {File} placeholders
to output files by module and view model respectively.
|
| Custom Path |
|
Relative path where to output override classes for the generated View Models. If not set, then the OutputPath
will be used. The path must contain a {File} placeholder to output files by view model.
|
| Nest Custom File |
True |
Whether or not to nest custom file under the auto-generated base file in the project. Applies only if both files are output
to the same directory.
|
| Add To Project |
../MySolution.Client.Common /MySolution.Client.Common.csproj |
Relative path to the project file to add the generated files to. The project will be reloaded every time you run the generator.
Leave it blank if you don't want generated files to be added to your project automatically.
|
| Registry File |
../MySolution.Client.Common /ViewModels/ViewModels.cs |
Relative path to the file for view models registration with the DI service container. The registration extension method
will be derived from the file name.
|
2.2 Model configuration
Configuration parameters for the generator that need to be also accessible to other generators are specified in the Xomega
model in the ui:views-config element under the top level config element, which is conventionally
placed in the global_config.xom file. These parameters consist of the namespace for the generated view models. The snippet
below illustrates such a configuration.
2.3 Common configurations
There expected to be just one configuration of this generator in the model, with the parameter values as illustrated above.
3. How to use the generator
The sections below provide some details on how to work with the generator.
3.1 Running the generator
You can run this generator for the entire model only.
You can rerun the generator when you add new links to data objects or change existing links on the data objects in the model,
and also if you change the type of the data object associated with the view models. The latter may require re-running other
generators that depend on the same model elements, such as the data object generator. Therefore, this generator should
be included in the build of the model project in the configuration, in order to allow to easily regenerate all view models
along with other artifacts.
3.2 Customizing the output
You should never edit generated view models or registration classes directly. This allows re-running the generator at any
time without losing your customizations.
To add your customizations, you should edit a subclass of the generated view model class that was added when you specified
the customize attribute on the view model. You can also add your own custom subclass of the generated view models in your
project, but then you will need to make sure to register that class with the dependency injection service container after
the generated view models are registered.
3.3 Cleaning generator’s output
This generator supports cleaning all generated view models using the Clean context menu for that generator. Normally, cleaning
the generated files makes sense if you are planning to change the output path for the generator. Also, it can be used as
part of Regenerate action, which runs the Clean and then Generate actions, when you have removed some of the views
from the model, and want the generated classes deleted and removed from the target project.
Note, that the customization subclasses that were generated for view models with a customize attribute set to
“true” will not be cleaned during these operations to prevent any loss of custom code during accidental run of such actions.
Therefore, you may get compilation errors for those classes if you clean your view models, and will need to delete them
manually as needed.