Skip to main content

Option Types

Options are annotations on various parts of the model that are used to active certain features and expanders.

Options have an option-type, and in some cases a value. As you can see below, the DataElement has 2 options:

  • an option with type cruds.table.csvExportButton and no value
  • an option with type cruds.table.pageSize and a value 50, 100
<dataElement name="City">
  <packageName>net.demo</packageName>
  <options>
    <cruds.table.csvExportButton/>
    <cruds.table.pageSize>50, 100</cruds.table.pageSize>
  </options>
</dataElement>

Option Type resource​

The option type name can be any alphanumeric string separated by dots, but it is also possible to define the option type in an expansion-resource. To do this, define a DataResource XML file containing the descriptions of the option types:

<dataResource type="elements::OptionType">
  <optionType name="cruds.table.csvExportButton">
    <description>Add a CSV export button to the table</description>
    <elementTypes>
      <elementType component="elements" name="DataElement"/>
    </elementTypes>
  </optionType>  
  <optionType name="cruds.table.pageSize">
    <description>Set the pageSize of the table</description>
    <elementTypes>
      <elementType component="elements" name="DataElement"/>
    </elementTypes>
  </optionType>
</dataResource>

Target Element Types​

You can define one or more element types for which this option is valid. If an element-type is defined, that option type is only applicable to elements of that type.

E.g. if cruds.table.pageSize would be applicable to both DataElement and Component, we could define it as follows:

<optionType name="cruds.table.pageSize">
  <description>Set the pageSize of the table</description>
  <elementTypes>
    <elementType component="elements" name="DataElement"/>
    <elementType component="elements" name="Component"/>
  </elementTypes>
</optionType>

Value Constraints​

You can also define constraints for the values of that option type:

<optionType name="cruds.table.pageSize">
  <elementTypes>
    <elementType component="elements" name="DataElement"/>
    <elementType component="elements" name="Component"/>
  </elementTypes>
  <valueConstraint>
    <isRequired>true</isRequired>
    <matchRegularExpression>unlimited|\d+(\s*,\s*\d+)*</matchRegularExpression>
  </valueConstraint>
</optionType>
<optionType name="cruds.table.csvExportButton">
  <elementTypes>
    <elementType component="elements" name="DataElement"/>
  </elementTypes>
  <valueConstraint>
    <noValue>true</noValue>
  </valueConstraint>
</optionType>

Default Value​

It is possible to define a defaultValue for an optionType. In case the option would be defined without a value, this value will be used instead.

It can be combined with the alwaysEnabled flag. That means the option will always be present, and if it was not explicitly defined, the defaultValue will be used.

<optionType name="struts.version">
  <elementTypes>
    <elementType component="elements" name="Application"/>
    <elementType component="elements" name="ApplicationInstance"/>
  </elementTypes>
  <defaultValue>6.0</defaultValue>
  <alwaysEnabled>true</alwaysEnabled>
</optionType>

Cascading Options​

Sometimes, it is useful to set an option on a higher level and have it cascade down to the relevant elements. In this case, you can add the cascading flag.

<optionType name="includeCsvImport">
  <elementTypes>
    <elementType component="elements" name="Application"/>
    <elementType component="elements" name="Component"/>
    <elementType component="elements" name="DataElement"/>
  </elementTypes>
  <cascading>true</cascading>
</optionType>

If enabled, the option on a Component or Application will be added to each DataElement in that Component/Application. This will not override any existing options. If the DataElement defines the option itself, the value of the option on the DataElement will be used.

Aliases​

In case you need to rename an option type, it is possible to define an alias. Options using the alias will be treated as having the same option type. There will also be a warning to notify developers that they are using an alias.

<optionType name="legacy.editorconfig.disabled">
  <alias>editorconfig.disabled</alias>
</optionType>

Deprecating Option Types​

There are option types that are either outdated, or explicitly introduced to support backwards compatibility for a given period. For these option types it is possible to add a deprecationWarning. This warning will be shown when expanding with the option enabled.

Furthermore, you can add a validUntil date to add a deadline for migrating the option. This will cause an exception to be thrown when trying to expand with this option.

<optionType name="legacy.editorconfig.disabled">
  <validUntil>2023-04-07</validUntil>
  <deprecationWarning>All projects should now be expanded with editorconfig to enforce consistency in formatting as much as possible.</deprecationWarning>
</optionType>