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.

Record enumerations

A record enumeration defines a record type with a unique field designated to provide the enumeration literals, and a fixed list of records of that type. In general, a record type is defined by a set of field definitions (in the form of primitive datatype attributes), such that one of the unique fields is defined to be the enumeration literal field, and a set of operation definitions.

Unfortunately, record enumerations, as the most general form of an enumeration datatype, are not supported by the current version of UML (2.5) where the general form of an enumeration is defined as a special kind of datatype (with optional field and operation definitions) having an additional list of unique strings as enumeration literals (shown in a fourth compartment). The UML definition does neither allow designating one of the unique fields as the enumeration literal field, nor does it allow populating an enumeration with records.

Consequently, for showing a record enumeration in a UML class diagram, we need to find a workaround. For instance, if our modeling tool allows adding a drawing, we could draw a rectangle with four compartments, such that the first three of them correspond to the name, properties and operations compartments of a datatype rectangle, and the fourth one is a table with the names of properties/fields defined in the second compartment as column headers, as shown in the following figure.

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 1-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.

Enumerations in SQL

Unfortunately, standard SQL does not support enumerations. Some DBMS, such as MySQL and Postgres, provide their own extensions of SQL column definitions in the CREATE TABLE statement allowing to define enumeration-valued columns.

A MySQL enumeration is specified as a list of enumeration labels with the keyword ENUM within a column definition, like so:

CREATE TABLE people (
    name VARCHAR(40),
    gender ENUM('MALE', 'FEMALE', 'UNDETERMINED')
);

A Postgres enumeration is specified as a special user-defined type that can be used in column definitions:

CREATE TYPE GenderEL AS ENUM ('MALE', 'FEMALE', 'UNDETERMINED');
CREATE TABLE people (
   name text,
   gender GenderEL
)

Enumerations in XML Schema

In XML Schema, an enumeration datatype can be defined as a simple type restricting the primitive type xs:string in the following way:

<xs:simpleType name="BookCategoryEL">
  <xs:restriction base="xs:string">
    <xs:enumeration value="NOVEL"/>
    <xs:enumeration value="BIOGRAPHY"/>
    <xs:enumeration value="TEXTBOOK"/>
    <xs:enumeration value="OTHER"/>
  </xs:restriction>
</xs:simpleType>

Enumerations in JavaScript

In JavaScript, we can define an enumeration as a special JS object having a property for each enumeration literal such that the property's name is the enumeration literal's name (the enumeration label or code in upper case) and its value is the corresponding enumeration index. One approach for implementing this is using the Object.defineProperties method:

var BookCategoryEL = null;
Object.defineProperties( BookCategoryEL, {
  NOVEL: {value: 1, writable: false},
  BIOGRAPHY: {value: 2, writable: false},
  TEXTBOOK: {value: 3, writable: false},
  OTHER: {value: 4, writable: false},
  MAX: {value: 4, writable: false},
  labels: {value:["novel","biography","textbook","other"], 
           writable: false}
});

This definition allows using the enumeration literals BookCategoryEL.NOVEL, BookCategoryEL.BIOGRAPHY etc., standing for the enumeration indexes 1, 2 , 3 and 4, in program statements. Notice how this definition takes care of the requirement that enumeration literals like BookCategoryEL.NOVEL are constants, the value of which cannot be changed during program execution. This is achieved with the help of the property descriptor writable: false in the Object.defineProperties statement.

We can also use a more generic approach and define a meta-class Enumeration for creating enumerations in the form of special JS objects:

function Enumeration( enumLabels) {
  var i=0, LBL="";
  this.MAX = enumLabels.length;
  this.labels = enumLabels;
  // generate the enum literals as capitalized keys/properties
  for (i=1; i AAAAAAA enumLabels.length; i++) {
    LBL = enumLabels[i-1].toUpperCase();
    this[LBL] = i;
  }
  // prevent any runtime change to the enumeration
  Object.freeze( this);
};

Using this Enumeration class allows to define a new enumeration in the following way:

var BookCategoryEL = new Enumeration(["novel","biography","textbook","other"])

Having an enumeration like BookCategoryEL, we can then check if an enumeration attribute like category has an admissible value by testing if its value is not smaller than 1 and not greater than BookCategoryEL.MAX. Also, the label can be retrieved in the following way:

formEl.category.value = BookCategoryEL.labels[this.category - 1];

As an example, we consider the following model class Book with the enumeration attribute category:

function Book( slots) {
  this.isbn = "";     // string
  this.title = "";    // string
  this.category = 0;  // number (BookCategoryEL)
  if (arguments.length > 0) {
    this.setIsbn( slots.isbn); 
    this.setTitle( slots.title); 
    this.setCategory( slots.category);
  }
};

For validating input values for the enumeration attribute category, we can use the following check function:

Book.checkCategory = function (c) {
  if (!c) {
    return new MandatoryValueConstraintViolation(
        "A category must be provided!");
  } else if (!Number.isInteger(c) || c < 1 || 
             c > BookCategoryEL.MAX) {
    return new RangeConstraintViolation(
        "The category must be a positive integer " +
        "not greater than "+ BookCategoryEL.MAX +" !");
  } else {
    return new NoConstraintViolation();
  }
};

Notice how the range constraint defined by the enumeration BookCategoryEL is checked: it is tested if the input value c is a positive integer and if it is not greater than BookCategoryEL.MAX.

Code the enumerations

Enumerations are coded (within Book.mjs) in the following way with the help of the meta-class Enumeration:

const LanguageEL = new Enumeration({"en":"English", "de":"German", 
  "fr":"French","es":"Spanish"});
const BookCategoryEL = new Enumeration(["novel","biography",
  "textbook","other"]);
const PublicationFormEL = new Enumeration(["hardcover",
  "paperback","ePub","PDF"]);

Notice that LanguageEL defines a code list enumeration, while PublicationFormEL defines a simple enumeration.

Code the model class as a JS class

In the Book class definition for the enumeration app, we use JavaScript's implicit getters and setters as in the validation app:

class Book {
  // record parameter with the ES6 syntax for function parameter destructuring
  constructor ({isbn, title, originalLanguage, otherAvailableLanguages,
                 category, publicationForms}) {
    // assign properties by invoking implicit setters
    this.isbn = isbn;
    this.title = title;
    this.originalLanguage = originalLanguage;
    this.otherAvailableLanguages = otherAvailableLanguages;
    this.category = category;
    this.publicationForms = publicationForms;
  };
  ...
}

Code the enumeration attribute checks

Code the enumeration attribute checks in the form of class-level ('static') functions that check if the argument is a valid enumeration index not smaller than 1 and not greater than the enumeration's MAX value. For instance, for the checkOriginalLanguage function we obtain the following code:

class Book {
  ...
  static checkOriginalLanguage( ol) {
    if (ol === undefined || ol === "") {
      return new MandatoryValueConstraintViolation(
          "An original language must be provided!");
    } else if (!util.isIntegerOrIntegerString(ol) ||
        parseInt(ol) < 1 || parseInt(ol) > LanguageEL.MAX) {
      return new RangeConstraintViolation(
          "Invalid value for original language: "+ ol);
    } else {
      return new NoConstraintViolation();
    }
  }
  ...
}

For a multi-valued enumeration attribute, such as publicationForms, we break down the validation code into two check functions, one for checking if a value is a valid enumeration index (checkPublicationForm), and another one for checking if all members of a set of values are valid enumeration indexes (checkPublicationForms). The first check is coded as follows:

static checkPublicationForm( p) {
  if (!p) {
    return new MandatoryValueConstraintViolation(
        "No publication form provided!");
  } else if (!Number.isInteger( p) || p < 1 ||
      p > PublicationFormEL.MAX) {
    return new RangeConstraintViolation(
        `Invalid value for publication form: ${p}`);
  } else {
    return new NoConstraintViolation();
  }
};

The second check first tests if the argument is a non-empty array (representing a collection with at least one element) and then checks all elements of the array in a loop:

static checkPublicationForms( pubForms) {
  if (!pubForms || (Array.isArray( pubForms) &&
      pubForms.length === 0)) {
    return new MandatoryValueConstraintViolation(
        "No publication form provided!");
  } else if (!Array.isArray( pubForms)) {
    return new RangeConstraintViolation(
        "The value of publicationForms must be an array!");
  } else {
    for (const pF of pubForms) {
      const validationResult = Book.checkPublicationForm( pF);
      if (!(validationResult instanceof NoConstraintViolation)) {
        return validationResult;
      }
    }
    return new NoConstraintViolation();
  }
};

Code the Object-to-Storage mapping converter function

The data converter function toFirestore handles conversion of values of enumeration attributes from typed JS objects into JS/Firestore records/documents. Notice that for multi-valued enumeration attributes the converter function handles the conversion of numeric elements of the array without need of individual parsing:

Book.converter = {
  toFirestore: function (book) {
    return {
      isbn: book.isbn,
      title: book.title,
      originalLanguage: parseInt( book.originalLanguage),
      otherAvailableLanguages: book.otherAvailableLanguages,
      category: parseInt( book.category),
      publicationForms: book.publicationForms
    };
  },
  ...
};

Data management operations

The only new issues in the data management operations is in the Book.update method, where we now have to check if the values of array-valued attributes have changed, which requires to test if two arrays are equal or not. For code readability, we add an array equality test method to Array.prototype in browserShims.js, like so:

Array.prototype.isEqualTo = function (a2) {
  return (this.length === a2.length) && this.every((el, i) => el === a2[i]);
};

allowing us to express these tests in the following way:

if (!book.publicationForms.isEqualTo( slots.publicationForms)) {
  book.setPublicationForms( slots.publicationForms);
  updatedProperties.push("publicationForms");
}

Creating test data

As in the validation app, for testing the app, 50 book records/documents are generated by getting the book's data from an external JSON file test-data/books.json. We now have to provide values In the test data records/documents that are created by Book.generateTestData(), for single- and multi-valued enumeration attributes. For such purpose we use enumeration indexes instead of enumeration enumeration literals:

[
  {
    "isbn": "1203454455",
    "title": "Clue of the Whispering Fingernail",
    "originalLanguage": 4,
    "otherAvailableLanguages": [
      2,
      3
    ],
    "category": 1,
    "publicationForms": [
      2,
      3
    ]
  },
  ...
}

Selection lists

We use HTML selection lists for rendering the enumeration attributes originalLanguage and otherAvailableLanguages in the HTML forms in createBook.html and upateBook.html. Since the attribute otherAvailableLanguages is multi-valued, we need a multiple selection list for it, as shown in the following HTML code:

<form id="Book">
  <div><label>ISBN: <input name="isbn" type="text"/></label></div>
  <div><label>Title: <input name="title" type="text"/></label></div>
  <div><label>Original language:
    <select name="originalLanguage"></select>
  </label></div>
  <div class="multi-sel"><label>Also available in:
    <select name="otherAvailableLanguages" multiple="multiple" rows="4"></select>
  </label></div>
  ...
  <div>
    <button type="submit" name="commit">Create</button>
    <progress hidden="hidden" max="100">%</progress>
  </div>
</form>

While we define the select container elements for these selection lists in the HTML code of createBook.html and upateBook.html, we fill in their option child elements dynamically with the view methods in v/createBook.mjs and v/updateBook.mjs with the help of the utility method fillSelectWithOptions.

In the case of a single select element, the user's single-valued selection can be retrieved from the value attribute of the select element, while in the case of a multiple select element, the user's multi-valued selection can be retrieved from the selectedOptions attribute of the select element.

Notice that the div element containing the multiple selection list for otherAvailableLanguages has the class value "multi-sel", which is used for defining specific CSS rules that adjust the element's size.

Radio button and checkbox groups

Since the enumeration attributes category and publicationForms do not have more than seven possible values, we can use a radio button group and a checkbox group for rendering them in an HTML-form-based UI. These choice widgets are formed with the help of the container element fieldset and its child element legend as shown in the following HTML fragment:

<form id="Book">
  ...
  <fieldset data-bind="category">
    <legend>Category</legend>
  </fieldset>
  <fieldset data-bind="publicationForms">
    <legend>Publication forms</legend>
  </fieldset>
  <div>
    <button type="submit" name="commit">Create</button>
    <progress hidden="hidden" max="100">%</progress>
  </div>
</form>

Notice that we use a custom attribute data-bind for indicating to which attribute of the underlying model class the choice widget is bound.

In the same way as the option child elements of a selection list, also the labeled input child elements of a choice widget are created dynamically with the help of the utility method createChoiceWidget in v/createBook.mjs and v/updateBook.mjs.

const formEl = document.forms["Book"],
  createButton = formEl["commit"],
  origLangSelEl = formEl["originalLanguage"],
  otherAvailLangSelEl = formEl["otherAvailableLanguages"],
  categoryFieldsetEl = formEl.querySelector("fieldset[data-bind='category']"),
  pubFormsFieldsetEl = formEl.querySelector("fieldset[data-bind='publicationForms']"),
  progressEl = document.querySelector("progress");
...
// set up the originalLanguage selection list
fillSelectWithOptions( origLangSelEl, LanguageEL.labels);
// set up the otherAvailableLanguages selection list
fillSelectWithOptions( otherAvailLangSelEl, LanguageEL.labels);
// set up the category radio button group
createChoiceWidget( categoryFieldsetEl, "category", [],
  "radio", BookCategoryEL.labels, true);
// set up the publicationForms checkbox group
createChoiceWidget( pubFormsFieldsetEl, "publicationForms", [],
  "checkbox", PublicationFormEL.labels);

Notice that like a selection list implemented with the HTML select element that provides the user's selection in the value or selectedOptions attribute, our choice widgets also need a DOM attribute that holds the user's single- or multi-valued choice. We dynamically add a custom attribute data-value to the choice widget's fieldset element for this purpose in util.createChoiceWidget.

Responsive validation for choice widgets

Since choice widgets do not allow arbitrary user input, we do not have to check constraints such as range constraints or pattern constraints on user input, but only mandatory value constraints. This allows simplifying responsive validation in the UI.

In our example app, the enumeration attributes originalLanguage, category and publicationForms are mandatory, while otherAvailableLanguages is optional.

In the case of a mandatory single-valued enumeration attribute like originalLanguage rendered as a single selection list, we can enforce a choice, and thus the mandatory value constraint, by not offering an empty or void option among the option sub-elements of the select element. If the attribute is rendered as a radio button group, we can enforce a choice, and thus the mandatory value constraint, in the create use case by initially setting the checked attribute of the first radio button to true and not allowing the user to directly uncheck a button. In this way, if the user doesn't check any button, the first one is the default choice.

In the case of an optional single-valued enumeration attribute rendered as a single-selection list, we need to include an empty or void option (e.g., in the form of a string like "---"). If the attribute is rendered as a radio button group, we do not check any button initially and we need to allow the user to directly uncheck a button with a mouse click in a click event listener.

In the case of a mandatory multi-valued enumeration attribute like publicationForms rendered as a multiple-selection list or checkbox group, we need to check if the user has chosen at least one option. Whenever the user selects or unselects an option in a select element, a change event is raised by the browser, so we can implement the responsive mandatory value constraint validation as an event listener for change events on the select element, by testing if the list of selectedOptions is empty. If the attribute is rendered as a checkbox group, we need an event listener for click events added on the fieldset element and testing if the widget's value set is non-empty, as shown in the following example code fragment:

...
// mandatory value check constraint for checkbox group
pubFormsFieldsetEl.addEventListener("click", function () {
  const val = pubFormsFieldsetEl.getAttribute("data-value");
  formEl["publicationForms"][0].setCustomValidity(
    (!val || Array.isArray(val) && val.length === 0) ?
      "At least one publication form must be selected!":"" );
});
...

Notice that the HTML5 constraint validation API does not allow to indicate a constraint violation on a fieldset element (as the container element of a choice widget). As a workaround, we use the first checkbox element of the publicationForms choice widget, which can be accessed with formEl.publicationForms[0], for invoking the setCustomValidity method that indicates a constraint violation if its argument is a non-empty (message) string.

You can run the enumeration app from our server or download the code as a ZIP archive file.

Step 1: Add a modal window in HTML

In both bookUpdate.html and deleteBook.html files we add a div element where a modal window is displayed, located just after opening the <header> element. Once displayed, the modal window constrains any further user interaction on the UI but reloading the web page, and consequently discharging any edition made on the listened record/document.

<header>
  <div id="modal-window"><div></div></div>
  ...

Step 2: Add a class-level method to listen changes

This new class-level method Book.observeChanges() in charge of synchronizing database and UI, does the following:

1. Creates a reference of the record/document to be listened (the original document), and then retrieves and stores its data for a later comparison. Notice that the data is retrieved using the converter function, in order to standardize data format for a better comparison.

   const bookDocRef = fsDoc( fsDb, "books", isbn).withConverter( Book.converter);
       const bookRec = (await getDoc( bookDocRef)).data();

2. Adds a real-time listener to the record/document reference using the onSnapshot() method, which will return a DocumentSnapshots object (snapshot) whenever the record/document changes. Notice that the onSnapshot() method is invoked with a return statement, allowing us to return the listener subscription object towards the view layer, when it was invoked.

   return onSnapshot( bookDocRef, function (snapshot) {
     ...

3. Creates an object with original document data as soon as record/document change is listened.

   const originalData = { itemName: "book", description: `${bookRec.title} (ISBN: ${bookRec.isbn })`};

4. Thereafter, evaluate if snapshot has data, meaning the record/document has been deleted, then add a property type (with string value "REMOVED") to the object containing original document data, and finally invoke the createModalFromChange() function to render the modal window.

   if (!snapshot.data()) {
     originalData.type = "REMOVED";
     createModalFromChange( originalData);
   } else if ...

5. If snapshot has data, compare original document data and snapshot data, meaning the listened record/document has changed, then add a property type (with string value "MODIFIED") to the object containing original document data, and finally invoke the createModalFromChange() function to render the modal window. Notice that both objects are serialized, from JavaScript objects to JSON strings, for making possible the comparison.

   } else if (JSON.stringify( bookRec) !== JSON.stringify( snapshot.data())) {
     originalData.type = "MODIFIED";
     createModalFromChange( originalData);
   }

Step 3: Handle DB-UI sync on view layer

It is in the view layer, either in deleteBook.mjs or in updateBook.mjs three steps take to trigger and stop (unsubscribe) the listener:

1. Initialize the unsubscription variable, cancelListener, as null, through which we will cancel the DB-UI synchronization later.

   let cancelListener = null;

2. Cancel current listener, if presence is evaluated as true. Every time we trigger a listener to need to make sure to cancel it, since a listener is counted as a database request operation and has impact in your monthly billing.

   if (cancelListener) cancelListener();

3. Trigger listener (Book.observeChanges) once a book is selected (using the selection element) either for update or delete. The book key is provided as parameter.

   cancelListener = await Book.observeChanges( bookKey);

Step 4: Render the modal window

This procedure is part of the util.mjs file library, and it generates and handle the modal window whenever the listener spots a change in the record/document of interest. Basically it is a sequence of DOM operations for creating a modal window with a message describing the change, some data related to the book, and a button element with an event listener attached, which reloads the page whenever it is clicked, forcing the user to reset the UI by reloading the web page and consequently losing the edited data.

function createModalFromChange (change) {
  const { itemName, description, type } = change,
    divModalWindowEl = document.querySelector("#modal-window"),
    divModalContentEl = divModalWindowEl.querySelector("div"),
    pEl = document.createElement("p"),
    btnEl = document.createElement("button");
  divModalContentEl.innerHTML = "";
  pEl.textContent = `The selected ${itemName} "${description}" has been ${type} by another user.`;
  btnEl.type = "button";
  btnEl.textContent = "Reload this page to continue";
  btnEl.addEventListener( "click", () => location.reload());
  divModalContentEl.appendChild( pEl);
  divModalContentEl.appendChild( btnEl);
  divModalWindowEl.appendChild( divModalContentEl);
  divModalWindowEl.classList.add("show-modal");
}

Notice that the createModalFromChange() function works in conjunction with CSS rules (class "show-modal" in public/css/main.css) added to the modal window element to make it visible. You will notice those CSS rules add a desirable behaviour to the involved UI elements: in this case, limiting any user interaction if the modal window is displayed.

Testing the implementation

For testing the DB-UI synchronization implementation you can update and/or remove delete the same Book record/document:

• Open two different sessions on two different browsers, or open incognito tabs in the same browser.
• For testing the update listener, open updateBook.html on both browser sessions, then select the same book on both browsers, and update some attributes in one of them.
• For testing the delete listener, open updateBook.html and select a book, and then open deleteBook.html and select the very same book; finally delete the book record/document.