1.1. Defining and Using Enumerations in OEMjs Apps

In OEMjs, enumerations can be defined in the following way:

1
2
3
4
5
6
7

const BookCategoryEL = new eNUMERATION("BookCategoryEL", 
    ["novel","biography","textbook","other"]);
const LanguageEL = new eNUMERATION("LanguageEL", 
    {"en":"English","de":"German","fr":"French","es":"Spanish",
     "it":"Italian","pt":"Portugese","gr":"Greek","pl":"Polish"});
const PublicationFormEL = new eNUMERATION("PublicationFormEL", 
    ["hardcover","paperback","ePub","PDF"]);

Notice that a simple enumeration (like "BookCategoryEL") is defined with a name and a list of labels for enumeration literals, while a code list enumeration (like "LanguageEL") is defined with a name and a code list map consisting of a number of code-label pairs such as "en":"English".

Enumerations can be used for defining the range of attributes in the following way:

1
2
3
4
5
6
7
8
9

Book.properties = {
  ...
  "category": {range: BookCategoryEL, label:"Category"},
  "publicationForms": {range: PublicationFormEL, label:"Publication forms", 
                       minCard: 1, maxCard: Infinity},
  "originalLanguage": {range: LanguageEL, label:"Original language"},
  "otherLanguages":   {range: LanguageEL, label:"Other languages", 
                       maxCard: Infinity}
}

1.2. Model-Based User Interface Generation

Based on the property definitions of the Book.mjs module file, a default user interface (UI) is generated for each of the data management operations Create, Retrieve, Update and Delete (CRUD).

For the data management operation Retrieve, the following UI is created, showing all book records retrieved from the app's database with columns showing their enumeration attribute values:

Notice that the enumeration attributes Category and Original language are single-valued, while the enumeration attributes Publication forms and Other languages are multi-valued.

For the data management operation Update, the following UI is created:

2.1. Enumerations

In all application domains, there are string-valued attributes with a fixed list of possible string values. These attributes are called enumeration attributes, and the fixed value lists defining their possible string values are called enumerations. For instance, when we have to manage data about people, we often need to include information about their gender. The possible values of a gender attribute may be restricted to one of the enumeration labels "male","female" and "undetermined", or to one of the enumeration codes "M", "F" and "U". Whenever we deal with codes, we also need to have their corresponding labels, at least in a legend explaining the meaning of each code.

Instead of using the enumeration string values as the internal values of an enumeration attribute, it is preferable to use a simplified internal representation for them, such as the positive integers 1, 2, 3, etc., which enumerate the possible values. However, since these integers do not reveal their meaning (which is indicated by the enumeration label) in program code, for readability we rather use special constants, called enumeration literals, such as MALE or M, prefixed by the name of the enumeration like in this.gender = GenderEL.MALE. Notice that we follow the convention that the names of enumeration literals are written all upper case, and that we also use the convention to suffix the name of an enumeration datatype with "EL" standing for "enumeration literal" (such that we can recognize from the name GenderEL that each instance of this datatype is a "gender enumeration literal").

There are also enumerations having records as their instances, such that one of the record fields provides the name of the enumeration literals. An example of such an enumeration is the following list of units of measurement:

Notice that since both the "Unit Symbol" and the "Unit Name" fields are unique, either of them could be used for the name of the enumeration literals.

In summary, we can distinguish between the following three forms of enumerations:

1. simple enumerations define a list of self-explanatory enumeration labels;

2. code lists define a list of code/label pairs.

3. record enumerations consist of a list of records, so they are defined like classes with simple attributes defining the record fields.

These three forms of enumerations are discussed in more detail below.

Notice that, since enumerations are used as the range of enumeration attributes, they are considered to be datatypes.

Enumerations may have further features. For instance, we may want to be able to define a new enumeration by extending an existing enumeration. In programming languages and in other computational languages, enumerations are implemented with different features in different ways. See also the Wikipedia article on enumerations.

Simple enumerations

A simple enumeration defines a fixed list of self-explanatory enumeration labels, like in the example of a GenderEL enumeration shown in the following UML class diagram:

Since the labels of a simple enumeration are being used, in capitalized form, as the names of the corresponding enumeration literals (GenderEL.MALE, GenderEL.FEMALE, etc.), we may also list the (all upper case) enumeration literals in the UML enumeration datatype, instead of the corresponding (lower or mixed case) enumeration labels.

Code lists

A code list is an enumeration that defines a fixed list of code/label pairs. Unfortunately, the UML concept of an enumeration datatype does not support the distinction between codes as enumeration literals and their labels. For defining both codes and labels in a UML class diagram in the form of an enumeration datatype, we may use the attribute compartment of the data type rectangle and use the codes as attribute names defining the enumeration literals, and set their initial values to the corresponding label. This approach results in a visual representation as in the following diagram:

In the case of a code list, we can use both the codes or the labels as the names of enumeration literals, but using the codes seems preferable for brevity (GenderEL.M, GenderEL.F, etc.). For displaying the value of an enumeration attribute, it's an option to show not only the label, but also the code, like "male (M)", provided that there is sufficient space. If space is an issue, only the code can be shown.

Extensible enumerations

There may be cases of enumerations that need to be extensible, that is, it must be possible to extend their list of enumeration values (labels or code/label pairs) by adding a new one. This can be expressed in a class diagram by appending an ellipsis to the list of enumeration values, as shown in Figure 2-1. An example of an extensible enumeration.

Since enumeration values are internally represented by enumeration literals, which are normally stored as plain positive integers in a database, a new enumeration value can only be added at the end of the value list such that it can be assigned a new index integer without re-assigning the indexes of other enumeration values. Otherwise, the mapping of enumeration indexes to corresponding enumeration values would not be preserved.

Alternatively, if new enumeration values have to be inserted in-between other enumeration values, and their indexes re-assigned, this implies that

1. enumeration indexes are plain sequence numbers and do no longer identify an enumeration value;

2. the value of an enumeration literal can no longer be an enumeration index, but rather has to be an identifying string: preferably the enumeration code in the case of a code list, or the enumeration label, otherwise.

2.2. Enumeration Attributes

An enumeration attribute is an attribute that has an enumeration as its range.

In the user interface, an output field for an enumeration attribute would display the enumeration label, rather than its internal value, the corresponding enumeration index.

For allowing user input to an enumeration attribute, we can use the UI concept of a (drop-down) selection list, which may be implemented with an HTML select element, such that the enumeration labels would be used as the text content of its option elements, while the enumeration indexes would be used as their values. We have to distinguish between single-valued and multi-valued enumeration attributes. In the case of a single-valued enumeration attribute, we use a standard select element. In the case of a multi-valued enumeration attribute, we use a multi-select element with the HTML attribute setting multiple="multiple".

In the case of using a single-select element for an optional enumeration attribute, we need to include in its options an element like "---" for indicating that nothing has been selected. Then, the UI page for the CRUD use case "Create" shows "---" as the initially selected option.

For both cases, an example is shown in Figure 2-2. A single and a multiple select element with no selected option. While the single select element for "Original language" shows the initially selected option "---" denoting "nothing selected", the multiple select element "Other available languages" shows a small window displaying four of the options that can be selected.

For usability, the multiple selection list can only be implemented with an HTML select element, if the number of enumeration literals does not exceed a certain threshold (like 20), which depends on the number of options the user can see on the screen without scrolling.

For user input for a single-valued enumeration attribute, a radio button group can be used instead of a single selection list, if the number of enumeration literals is sufficiently small (say, not larger than 7). A radio button group is implemented with an HTML fieldset element acting as a container of labeled input elements of type "radio", all having the same name, which is normally equal to the name of the represented enumeration attribute.

A checkbox group

For user input for a multi-valued enumeration attribute, a checkbox group can be used instead of a multiple selection list, if the number of enumeration literals is sufficiently small (say, not larger than 7). A checkbox group is implemented with an HTML fieldset element acting as a container of labeled input elements of type "checkbox", all having the same name, which is normally equal to the name of the represented enumeration attribute.