Skip to main content

Data Projections

DataProjections define a set of fields from their parent DataElement. When data is passed through the application, it is always represented in the form of a projection.

Standard Projections​

There are 3 projections that are always present for each DataElement.

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.

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 _:

Option
functionalKey DataElement

Define a set of Fields that together define a Key. As value, provide the names of the fields separated with _.

This option generates a DataRef class which contains said Fields in addition to the name and id, so they can be used to look up instances.

caution

Though it is currently possible to use multiple link fields in the key, this is not advised. It can lead to unexpected behavior as some DataRef constructors are a composite of fields from all included linked elements, which can cause name collisions.

This new dataRef class will then be used when fetching data from the dataBase. Adding this option forces all functional fields to be contained in each projection.

It is also possible to create a new DataRef with only the functional fields with the method withFunctionalKey(...). This DataRef can then be used in the getProjection, create, modify etc. without the need of an id. Although it is not yet supported by the find method.

The dataRef can be converted from and to a String with the {DataElement}DataRefConverter, using :: as separator.

<options>
  <functionalKey>name_version</functionalKey>
</options>

Custom Projections​

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

Starship.xml
<dataElement name="Starship">
  <dataProjections>
    <dataProjection name="Projection1">
      <referenceFields>
        <referenceField>
          <field name="field1"/>
        </referenceField>
        <referenceField>
          <field name="field2"/>
        </referenceField>
      </referenceFields>
    </dataProjection>
  </dataProjections>
</dataElement>
tip

There are multiple uses for a data projection:

A first use is to have a certain set of data available, both in the front-end and the back-end. For example, user input only needs the name and the password, instead of all of the variables.

Secondly, the calculated fields allow a logical module from the reference fields. An example would be if a file needed to be downloaded, the reference fields would be a root folder, a filename and an extension. A calculated 'full path' field could give the composed link to the file.

note

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.

Hence, it is advised to define calculated fields as regular Fields.