Full CRUD and Views
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
This is the main, extremely flexible model enhancement generator, which allows you to quickly add and configure different model
elements, such as Create, Read, Update, Delete (CRUD) and Read List operations for the services, as well as corresponding
presentation data objects and UI views, all based on the definition of your model objects.
When the generator is run on bare objects with just a list of fields, such as those that are freshly imported from a database,
or when it adds new operations that don't exist in the model yet, it will use the structure of the object's fields and
relationship with the parent object to generate appropriate operations.
It can also be run to enhance existing operations, such as to add REST methods or data objects and views to them, in which case
it will keep and use the structure of those operations.
1.2 Generator outputs
This generator updates a single or multiple .xom files that contain model objects with operations, data objects, views,
or other elements as configured by the generator parameters.
CRUD Operations. When Generate CRUD or Generate Subobject CRUD parameters are set to "True",
the generator will add Create, Read, Update and Delete operations to the selected objects and/or their subobjects. The input
parameters of the CRUD operations will be based on the object key fields. Non-key fields will be also in the input of the
Create and Update operations, as well as in the output of the Read operation. The input structures will be generated such that
it would be easy to expose them via REST services. And if Generate Rest Methods parameter is set, then the generator
will also configure the operations with annotations for REST method, as illustrated below.
After you add CRUD operations to an object, you can update their input and output parameters, as well as the REST method
configuration as appropriate.
Read List Operation. If you set the Generate Read List or Generate Subobject Read List
parameters of the generator to "True", the generator will add "read list" operations to the selected objects and/or their
subobjects. The output of the operation will have a list attribute set to "true", and will contain all object's
fields. The input parameters for a Read List operation on a subobject will contain just the parent object's key fields.
But for primary objects that don't have a parent, the input parameters will contain all object's fields as criteria, if the
Generate Read List Criteria parameter is set. Additionally, if Generate Read List Operators parameter
is set, then the criteria input structure will have a special comparison operator parameter for each field, and there will be
a second parameter added for fields that allow a BETWEEN operator, such as for dates or numbers, to allow supplying a range.
The following example illustrates such a setup.
If you generate a Read List operation without criteria first, then you can add them later by setting the corresponding
parameters, and rerunning the generator. As with the CRUD operations, specifying Generate Rest Methods parameter
will also add a REST method configuration to the Read List operations.
Data Objects. When you set the Generate Data Objects parameter of the generator to "True",
the generator will add declarations of "details" or "list" objects for the corresponding CRUD or Read List operations,
and will add such data objects to the configuration of those operations, which determines the set of data object's
properties, as follows.
In addition, the generator can configure the data objects to make a serial key field hidden when you specify the
Make Serial Keys Hidden parameter. If the UI views are also being added, and the Generate Links
parameter is set, then it will also add link configurations to list objects, which would open the corresponding
details view, as illustrated below.
The data objects serve as view models for search or details views, and are the main part of the views.
Views. When you set the Generate Search View or Generate Details View parameters of the
generator to "true", the generator will add declarations of search and/or details views based on the corresponding data
objects as view models. The view name should be unique, so it will be built from the object name, with a word "List" added
for search views, and a postfix specified by the View Name Postfix, which is typically set to "View". You can also
specify the name of a saved layout from the model to use in the Search View Layout and Details View Layout
parameters respectively. The following snippet illustrates such a view setup.
Enumeration. For objects that represent static data that is stored in the database, but can be cached
on the client, it makes sense to add a Read List operations not so much for a search view, but rather to allow the client
to read and cache that static data. This is done by specifying the Add Read List Enumeration generator parameter,
which will decorate the "read list" operation with a dynamic enumeration specification that tells the Xomega Framework
which output parameter is an internal Id, and which one should be used as a user-facing description. You can also
set the Make Key Type Enumerated parameter to update the key type for the object, and link it to the new
enumeration, which would provide a selection control for any field that is using that type, as illustrated below.
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 |
Full CRUD and Views
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
Folder Name |
Model Enhancement
|
Folder path to the generator inside the Model project. The folders are separated by a backslash (\). |
Include In Build |
False
|
A flag indicating whether or not running this generator should be included in building of the model project. |
Operations |
Generate CRUD |
True |
Whether to generate Create, Read, Update and Delete operations. |
Generate Read List |
True |
Whether to generate Read List operation. |
Generate Read List Criteria |
True |
Whether to generate criteria for Read List operation. |
Generate Read List Operators |
True |
Whether to generate operators for search criteria. |
Generate Subobject CRUD |
True |
Whether to generate Create, Read, Update and Delete operations on sub-objects. |
Generate Subobject Read List |
True |
Whether to generate Read List operation on sub-objects. |
Generate Rest Methods |
True |
Whether to generate REST API methods on operations. |
Use Yes/No Substitution |
True |
Whether to substitute boolean type with 'yesno' type for non-required parameters of CRUD operations. |
Data Objects |
Generate Data Objects |
True |
Whether to generate Xomega.Framework Data Object definitions for operations. |
Generate Links |
True |
Whether to generate links to corresponding details views on list objects. |
Make Serial Keys Hidden |
True |
Whether to configure serial key fields as hidden on views. |
Views |
Generate Search View |
True |
Whether to generate a search view for list objects. |
Generate Details View |
True |
Whether to generate a details view for CRUD objects. |
Search View Layout |
|
Named layout from the global config to use for the search view. |
Details View Layout |
|
Named layout from the global config to use for the details view. |
View Name Postfix |
View |
Postfix to use for view names. |
Enumeration |
Add Read List Enumeration |
False |
Whether to add enumeration definition to the Read List operation. |
Make Key Type Enumerated |
False |
Whether to update the key type to reference generated enumeration. |
Add Suggest Type |
False |
Whether to add a separate type linked to the generated enumeration to suggest values, which also accepts other values. |
2.2 Model configuration
The generator doesn't use any other configuration parameters from the model.
2.3 Common configurations
This is a flexible generator that can be configured in different ways and saved as separate configurations for different scenarios.
Below are some of the common configurations that can be created.
Full CRUD with Search and Details Views. This is a default 'all inclusive' configuration with the values as described
above. It can be used to quickly add all CRUD and Read List operations to the barebone objects, as well as standard Search and Details
views based on those operations.
Lookup View. If you only need a Search view to browse or look up the objects without editing their details,
you can configure this generator to add just the Read List operation, data objects without links, and a Search View, without
selecting the CRUD operations or a Details View.
Enumeration Read List. For objects that contain static data that can be cached, you may not even need a search view,
but rather a Read List operation to provide data for the cached enumeration. To configure this, you can select the option to add
a Read List operation, and to decorate it with an enumeration specification. You can also configure it to update the key type
of the object to link it to this enumeration, and thereby provide a selection control wherever it is being used on the UI.
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 either one file, or for multiple selected files if you want to enhance multiple objects. You can
run a configuration that adds all enahancements at once, or you can create multiple configurations that add different enhancements,
and then run them one by one. For example, you can add a Read List operation first, and then CRUD operations, and then data object
definitions, views etc. The generator is not supposed to be included in the model build process.
3.2 Customizing the output
After you have added your operations, data objects, or other enhancements with this generator, you can update the model to taylor
your operations for your application. The generator creates operations based on all fields of the object, so it will be just a matter
of removing parameters for the fields that you don't need in the operations, and adding parameters that are not based direclty on the
object's fields.
If you re-run the generator after updating the model, your manual changes should be largely preserved. However, it is still recommended
to check in your model into your source control before re-running the generator, so that you could easily review the changes from it.
3.3 Cleaning generator’s output
This generator supports cleaning the enhancements it adds when you run the Clean command. This could be useful during initial
prototyping when you are actively changing the object fields, so that you could re-add the operations, or to clean up the model
if you ran the generator on a wrong file.
But keep in mind that the Clean operation will also remove any customizations that you may have made, so you want to make sure that
you check in your model to your source control before running it to avoid any loss of useful model data.