Full CRUD with Views

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.

Generator inputs

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.

note

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.

Generator outputs

This generator updates 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 or GenerateForSubobjects parameters are set to true on the mod:Operations/mod:CRUD config, 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 GenerateRestMethods parameter is set, then the generator will also configure the operations with annotations for the REST method, as illustrated below.

<objects>
  <object name="sales order">
    <operations>
      <operation name="create" type="create">[...]
      <operation name="read" type="read">[...]
      <operation name="update" type="update">
        <input>
          <param name="sales order id"/>
          <struct name="data">...</struct>
        </input>
        <config>
          <rest:method verb="PUT" uri-template="sales-order/{sales order id}"
                       xmlns:rest="http://www.xomega.net/rest"/>
        </config>
      </operation>
      <operation name="delete" type="delete">[...]
    </operations>
  </object>
</objects>

After you add the 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 or GenerateForSubobjects parameters of the generator to true on the mod:Operations/mod:ReadList config, the generator will add read list operations to the selected objects and/or their subobjects.

The output of the operation will have a list="true" attribute and will contain all the object's fields. The input parameters for a read list operation on a subobject will contain just the parent object's key fields.

For primary objects that don't have a parent though, the input parameters will contain all the object's fields as criteria, if the GenerateCriteria parameter is set, as illustrated below.

<object name="sales order">
  <operations>
    <operation name="read list" type="readlist">
      <input>
        <struct name="criteria">
          <param name="sales order number"/>
          <param name="status" list="true"/>
          <param name="order date" type="date"/>
        </struct>
      </input>
      <output list="true">...</output>
    </operation>
  </operations>
</object>

tip

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 GenerateRestMethods parameter will also add a REST method configuration to the read list operations.

Data Objects

When you set the Generate parameter of the generator to true on the mod:DataObjects config, 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.

<operation name="read list" type="readlist">
  <input>...</input>
  <output list="true">
    <param name="sales order id"/>
    <param name="sales order number"/>
    <config>
      <xfk:add-to-object class="SalesOrderList"/>
    </config>
  </output>
</operation>

In addition, the generator can configure the data objects to make a serial key field hidden when you specify the MakeSerialKeysHidden parameter. If the UI views are also being added, and the GenerateLinks parameter is set, then it will also add link configurations to list objects, which would open the corresponding details view, as illustrated below.

<xfk:data-objects xmlns:xfk="http://www.xomega.net/framework">
  <xfk:data-object class="SalesOrderList" list="true" customize="true">
    <ui:display>
      <ui:fields>
        <ui:field param="sales order id" hidden="true"/>
      </ui:fields>
    </ui:display>
    <ui:link name="details" view="SalesOrderView" child="true">
      <ui:params>
        <ui:param name="sales order id" field="sales order id"/>
      </ui:params>
      <ui:display on-field="sales order number"/>
    </ui:link>
  </xfk:data-object>
</xfk:data-objects>

The data objects serve as view models for search or details views and are the main part of the views.

Search/Details Views

When you set the Generate parameter of the generator to true on the mod:Views/mod:SearchView or mod:Views/mod:DetailsView configs, 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 the word "List" added for search views, and a postfix specified by the ViewNamePostfix parameter, which is typically set to "View".

The following snippet illustrates such a view setup.

<ui:views xmlns:ui="http://www.xomega.net/ui">
  <ui:view name="SalesOrderView" title="Sales Order">
    <ui:view-model data-object="SalesOrderObject"/>
    <ui:main-link name="new sales order">
      <ui:params>
        <ui:param name="_action" value="create"/>
      </ui:params>
    </ui:main-link>
  </ui:view>
  <ui:view name="SalesOrderListView" title="Sales Order List">
    <ui:view-model data-object="SalesOrderList"/>
    <ui:main-link name="sales order list"/>
  </ui:view>
</ui:views>

For the primary object (aka aggregate root), the generator will also add a ui:main-link main menu for the search view to browse objects, and a main menu for the details view to create new objects if you set the ViewMenu parameter. The AutoRun parameter on the mod:Views/mod:SearchView config can be set to true to auto-run the search view from the main menu.

Dynamic 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 enum operation to allow the client to read and cache that static data.

This is done by specifying the Generate and/or GenerateForSubobjects parameters on the mod:Operations/mod:ReadEnum config, which will add a read enum operation decorated 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.

warning

If the generator cannot find a proper object field to use as the Id or a description, then it will just add those as output parameters, and you'll need to manually provide custom code in the services for those parameters, to return proper values.

You can also set the MakeKeyTypeEnumerated 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.

<types>
  <type name="sales territory" base="integer enumeration">
    <enum ref="sales territory"/>
  </type>
</types>
<objects>
  <object name="sales territory">
    <operations>
      <operation name="read enum">
        <output list="true">
          <param name="territory id"/>
          <param name="name"/>
          <param name="country region code"/>
          <param name="group"/>
        </output>
        <config>
          <xfk:enum-cache enum-name="sales territory" id-param="territory id" desc-param="name"
                          xmlns:xfk="http://www.xomega.net/framework"/>
        </config>
      </operation>
    </operations>
  </object>
</objects>

Configuration

By default, the generator configuration is defined under the .Generators\Model Enhancement folder in the model project as follows.

Full CRUD with Views.xgen

<XomGeneratorConfig xmlns="http://schemas.xomega.net/v10/xgen"
                    xmlns:mod="http://schemas.xomega.net/v10/xgen/model-ops">
  
  <Generator Xsl="Model/crud_ops_views.xsl"
             GeneratorGroup="model"
             IndividualFiles="true"/>

  <mod:Operations GenerateRestMethods="true">
    <mod:CRUD Generate="true"
              GenerateForSubobjects="true"
              UseYesNoSubstitution="true"/>
  
    <mod:ReadList Generate="true"
                  GenerateCriteria="true"
                  GenerateForSubobjects="true"/>

    <mod:ReadEnum Generate="false"
                  MakeKeyTypeEnumerated="true"/>
  </mod:Operations>

  <mod:DataObjects Generate="true"
                   GenerateLinks="true"
                   MakeSerialKeysHidden="true"/>

  <mod:Views ViewNamePostfix="View">
    <mod:SearchView Generate="true"
                    ViewMenu="true"
                    AutoRun="false"/>

    <mod:DetailsView Generate="true"
                     ViewMenu="true"/>
  </mod:Views>

</XomGeneratorConfig>

Generator parameters

The following table describes configuration parameters for the generator.

Parameter	Value Example	Description
Xsl	Model/crud_ops_views.xsl	Relative path to the XSLT file used by the generator to add CRUD operations and views to the model objects in the selected file(s).
GeneratorGroup	model	The group to which this generator belongs based on the type of the generated files.
IndividualFiles	true	Specifies whether this generator can be run on individual files.
mod:Operations
GenerateRestMethods	true	Whether to generate REST API methods on operations.
mod:Operations/mod:CRUD
Generate	true	Whether to generate Create, Read, Update and Delete operations.
GenerateForSubobjects	true	Whether to generate Create, Read, Update and Delete operations on sub-objects.
UseYesNoSubstitution	true	Whether to substitute boolean type with yesno type for non-required parameters of CRUD operations.
mod:Operations/mod:ReadList
Generate	true	Whether to generate Read List operation.
GenerateCriteria	true	Whether to generate criteria for Read List operation.
GenerateForSubobjects	true	Whether to generate Read List operation on sub-objects.
mod:Operations/mod:ReadEnum
Generate	false	Whether to generate Read Enum operation.
GenerateForSubobjects	false	Whether to generate Read Enum operation on sub-objects.
MakeKeyTypeEnumerated	false	Whether to update the key type to reference generated enumeration.
mod:DataObjects
Generate	true	Whether to generate Xomega.Framework Data Object definitions for operations.
GenerateLinks	true	Whether to generate links to corresponding details views on list objects.
MakeSerialKeysHidden	true	Whether to configure serial key fields as hidden on views.
mod:Views
ViewNamePostfix	View	Postfix to use for view names.
mod:Views/mod:SearchView
Generate	true	Whether to generate a search view for list objects.
ViewMenu	true	Specifies whether to add the search view to the application menu.
AutoRun	false	Whether to auto-run the search view from the main menu.
mod:Views/mod:DetailsView
Generate	true	Whether to generate a details view for CRUD objects.
ViewMenu	true	Whether to add a main menu for details view to create new objects.

Model configuration

The generator doesn't use any other configuration parameters from the model.

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

Read Enum Operation

For objects that contain static data that can be cached, you may not even need a search view, but rather a read enum operation to provide data for the cached enumeration. To configure this, you can select the option to add a read enum operation with an enumeration specification to the aggregate object and/or to its subobjects. 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.

How to use the generator

The sections below provide some details on how to work with the generator.

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 enhancements 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, then CRUD operations, and then data object definitions, views, etc.

warning

The generator is not supposed to be included in the model build process.

Customizing the output

After you have added your operations, data objects, or other enhancements with this generator, you can update the model to tailor 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 directly on the object's fields.

If you re-run the generator after updating the model, your manual changes should be largely preserved.

warning

However, it is still recommended to check in your model to your source control before re-running the generator, so that you could easily review the changes from it.

Cleaning the 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 clean up the model if you run the generator on the wrong file.

danger

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.