# Dimensions

Dimensions allow you to store values for a field in several dimensions, these dimensions are fixed in the configuration.

A dimension can run in two modes. "explicit"(enabled) and "not explicit"(disabled). This always applies per record(pid), as in the following. The dimensions must always be considered independently of each other. So it can be locale "explicit" and channel "not explicit". There is no "order of dimensions".

explicit(activated): Within the dimension null cannot exist. All values must be explicitly assigned to this dimension.
not explicit(deactivated): In this dimension all entries must be null.

These modes can vary from record to record and can be changed via the API.

Danger!: The methods set_single / set_multiple delete all records from the other mode. If an explicit value is set, all entries with null are deleted. If a non-explicit value (null) is set, all explicit values are deleted.

# Dimensions at set_single/set_multiple for a bean

Saving beans with dimensions is done using the same methods as normal saving. See set_single and set_multiple.

The base class for all CE types is extended so that dimensions can also be stored.

public abstract class CEType<T> {
   protected T value;
   protected Dimension[] dimensions;
}

Structure of the class Dimension

public class Dimension {
   private String name;
   private Object value;
}

# Conditions for saving

For fields that support dimensions, all dimensions must always be set, otherwise an error occurs.

Example of error because not all dimensions are set. For field with dimensions channel and locale.

field=new CEVarchar(null, new Dimension[] { new Dimension("channel", null) })

For fields that do not support dimensions, dimension[] dimensions=zero must be entered.

Example:

field=new CEVarchar("Text");

Delete all records for a field (all dimensions) from the database
- When field=null is transferred in the map.
  
  Example:

field=null;

field=new CEVarchar(null, new Dimension[] { new Dimension("channel", null), new Dimension("locale", null) });

Delete the record with channel=web and locale=zero

Example:

field=new CEVarchar(null, new Dimension[] { new Dimension("channel", "web"), new Dimension("locale", null) });

# Dimensions at get_single/get_multiple

The methods 'get_single' and 'get_multiple' return the content of dimensions.

Dimensions are only supported if a get function with set fields is used. The old variant with ViewType is not supported. Dimensions are not available for Flex.

With the get function, all dimensions in the parameter map under Key dimensions must always be specified or none. If dimensions are specified, they apply to all fields.

request.getParameter().put("dimensions", new Dimension[] { new Dimension("locale", "de_DE") });

If no dimension is specified, it is determined from the associated FeaturePermission for the transferred fields. The name of the FeaturePermission for a dimension is dimension_<<dimension_name>>. For example, dimension_locale

# Rules for the return of values

Folgendes gilt immer im Kontext eines einzelnen Datensatzes:

If there are no records for the entire field, "field name": null is returned. This means for the GUI that all dimensions are "disabled".
If an explicit value is requested, it must be delivered with dimension output if found. If there are only NULL entries in other dimensions, this is also delivered accordingly:

"feldname": {
    "value": "Wert",
    "dimensions": {
        "locale": "de_DE", // Erkennt die GUI, dass diese Dimension "aktiviert" ist.
        "channel": null // null oder aus der Anfrage kopiert, je nach dem in welchem Modi, diese Dimension ist. Erkennt die GUI, dass diese Dimension "deaktiviert" oder "aktiviert" ist.
    }
}

If a field is in "explicit" mode, the null dimension value must never be returned. If no value is found, the value from the query must be copied to the result. Example: Request for locale=de_EN;channel=web, but the database only contains values for `fr_FR`:

"feldname": {
    "value": null, // Wird ja nichts passendes gefunden
    "dimensions": {
        "locale": "de_DE", // Aus der Anfrage kopiert => Die GUI erkennt, dass die Dimension "aktiviert" ist.
        "channel": null, // null oder aus der Anfrage kopiert, je nach dem in welchem Modi, diese Dimension ist.
    }
}

# Configuration of dimensions

Dimensions are defined under conf.customer in the folder ce_global/defaults in the file dimensions.xml.

The file is structured as follows:

<dimensions>
  <dimension type="CEVarchar">channel</dimension><!-- Default: Varchar 20 -->
  <dimension type="CEVarchar" length="20">locale</dimension>
  <!-- <dimension type="CETimestamp">valid_from</dimension> -->
  <!-- CETimestamp wird erst bei Bedarf implementiert. -->
</dimensions>

Currently only the type CEVarchar is supported. Fallback is CEVarchar(20). It follows from this:

If type not set -> CEVarchar with length 20
If type CEVarchar -> CEVarchar with length 20
If type CEVarchar and length=25) -> CEVarchar with length 25

Labels and icon keys are generated for the dimensions created here:

Label: L-D-<DIMENSION-NAME>
Icon: D-<DIMENSION-NAME>

# ValueOptions for Dimensions

ValueOptions must be defined for all configured dimensions **. The configuration must be done in the conf.customer/CUSTOMER_NAME/ce_global/value_options folder in the dimension_DIMENSION_NAME.xml file.

Sample file: dimension_channel.xml for the dimension **channel

<?xml version="1.0" encoding="UTF-8"?>
<keys>
        <key>web</key>
        <key>print</key>
</keys>

The value option dimension_channel is generated from this configuration. ValueOption Key: global.dimension_channel

The translations for key web

translation=L-V-DIMENSION_CHANNEL-WEB
info=L-V-DIMENSION_CHANNEL-WEB-INFO
icon=V-DIMENSION_LOCALE-DE_DE

# Presets

Presets are generated for the ValueOptions so that the set dimensions of the user can be saved.

Example: Dimension channel

Preset with the key global.dimension_channel

# Primary Key

The primary key no longer works in tables with dimensions. This would have to contain the dimension fields in addition. Then these should not become NULL. For Dimension not set we want to set the value to NULL. The solution is to convert the primary key into a unique constraint that also contains the dimension fields.

NULL values in unique constraints do not work in MySQL. We have to make sure in the source code that no duplicate values are inserted.

# Activate dimension for a field

Configuration see '4apfield-details

← Custom CSS Icons and Icon Creation →