DataProjection

The DataProjection element is used to define a subset of fields of the parent DataElement.

When data is passed through the application, it is always represented in the form of a projection.

For what projections are and why they exist, see Data Elements.

Standard Projections

There are 3 projections that are always present for each data element.

Projection	Contains	Used for
Details	All fields, excluding calculated fields	Create, modify, default backend representation
Info	Fields marked as info field	Table columns in the user interface, default result of `find()`
DataRef	`id`, `name` and functional key fields	References to an instance

Details Projection

The details projection is used to create and modify. It is also the default representation for most logic in the backend.

The details projection is defined by the set of all fields in the DataElement excluding the calculated Fields.

Info Projection

The info projection is a reduced set of fields from the DataElement. It defines the columns in the table in the user interface. A field is added to the info projection with isInfoField.

note

The find() method defaults to returning the info projection if no projection is defined in the SearchDetails. However, it is better to explicitly define a projection. If you are not sure, use the details projection.

DataRef Projection

The DataRef projection is used in several places to reference an instance of a DataElement without requiring the entire DataElement projection.

By default, this projection only contains the id (and name if possible) of that instance.

It is also possible to define your own Fields to add to the DataRef. To do so, add the option functionalKey with the names of the fields separated with _. Read more in Business keys.

Custom Projections

Developers can also define their own projections. These projections define a set of reference fields, which point to fields of the DataElement.

Car.xml
<dataElement name="Car">
  <dataProjections>
    <dataProjection name="CarReservation">
      <referenceFields>
        <referenceField>
          <field name="status"/>
        </referenceField>
        <referenceField>
          <field name="reservedBy"/>
        </referenceField>
        <referenceField>
          <field name="reservedTill"/>
        </referenceField>
      </referenceFields>
    </dataProjection>
  </dataProjections>
</dataElement>

Calculated fields in projections

Projections also allow the definition of CalculatedFields specific to the projection. This representation, however, is not only redundant, but also not easy to migrate to a regular Calculated Field. Calculated fields defined as regular Fields do not have this limitation.

Projections as Input

It is possible to use projections as input for both create and modify. In this case only the fields defined in the projection will be updated.

These methods are only generated when the corresponding option is set.

CityMyProjection city = new CityMyProjection();
city.setDescription(newDescription);

CrudsResult<DataRef> result = cityLocalAgent.createWithProjection(city);

Options

Option

Adds a method to the DataElement classes to create an instance with a projection other than details.

<options>
  <cruds.createWithProjection/>
</options>

Option

Adds a method to the DataElement classes to modify an instance with a projection other than details.

<options>
  <cruds.modifyWithProjection/>
</options>

Standard Projections​

Details Projection​

Info Projection​

DataRef Projection​

Custom Projections​

Projections as Input​

Options​