[uml] flagplus.flags.inc

REFACTOR: this software engineering content is flagged as under consideration for refactoring.
HOT TIP: this content is flagged as highly recommended !

Webel module:

Package/Namespace: 

UML element type:

OOE stereotypes:

Relationships
Relationships (inverse)

In migrating from Drupal7 function-and-hook "flatland" to a more OOP and UML-friendly world we endeavour to: Create "bridge" include files that mediate between the classic Drupal7 hooks of the .module file and OO Class libraries that progressively encapsulate define() data and functions as Class attributes, constants, and Interface/Class methods

A guiding principle is that a form-related include bridge file should use one and one only helper/builder class, as was achieved for flagplus.entitytype.inc, with delegation from each of the form _build(), _ajax(), _validate() and _submit() functions.

But flagplus.flags.inc currently handles roughly 3 sets of closely related but differently implemented functionality:

1. A passive readonly page view of the applicability of each flag by entity type and bundle.

2. An editable view (with an entity type filter) of the applicability of each flag by entity type and bundle, with sub-forms for each table for flag applicability by bundle.

3. An editable AJAX view (with an AJAX entity type filter) of the applicability of each flag by entity type and bundle, with AJAX sub-forms for each table for flag applicability by bundle.

We can see this in the (overly complex) main diagram below through the 3 sets of dependencies on the 3 subclasses of @BybundleAbstractBuilder.

UML Diagram
Click on the UML diagram to view it in a lightbox image viewer. You may then zoom in (or just open the image in a new web browser tab using the Download Original link to view large diagrams).

UML modelling domain:

Using Dependency arrows between operations in class diagrams can be useful in dedicated mini-diagrams, but it quickly leads to clutter in large overview diagrams like this.

We can however instead represent the 3 different "scenarios" handled by this one include file in separate diagrams (as shown below).

UML Diagram
Click on the UML diagram to view it in a lightbox image viewer. You may then zoom in (or just open the image in a new web browser tab using the Download Original link to view large diagrams).

UML modelling domain:

CASE: build a readonly page showing the applicability of each Flag by entity type and bundle name in a table.

Those Dependencies between Operations are starting to look a lot more useful when a scenario is isolated !

UML Diagram
Click on the UML diagram to view it in a lightbox image viewer. You may then zoom in (or just open the image in a new web browser tab using the Download Original link to view large diagrams).

UML modelling domain:

CASE: build an editable form enabling the applicability of each Flag by entity type and bundle name to be seen and set in a table, with an entity type filter.

A bit more complex because now it includes and entity type filter sub-form and sub-forms for applicability of each Flag by entity type and bundle. But the Dependencies between operations do definitely help trace the logic.

UML Diagram
Click on the UML diagram to view it in a lightbox image viewer. You may then zoom in (or just open the image in a new web browser tab using the Download Original link to view large diagrams).

UML modelling domain:

CASE: build an editable AJAX form enabling the applicability of each Flag by entity type and bundle name to be seen and set in a table, with an AJAX entity type filter.

Also not bad except for those horrible long operations in the include file  flagplus.flags.inc, which is a a typical consequence of lack of OOP, and of Drupal7's system for passing arguments to non-OOP callbacks functions (unless you like shoving it all into an unstructured "$options" array as so often done in Drupal, which is also rather blech and yuck).

Notice how, compared with the non-AJAX form case, the entity filter sub-form is handled a bit differently; instead of it being built with a default from a system variable it is built using the form state value from the AJAX callback.

Refactoring

Some long method signatures with many parameters invite refactoring. One possibility is to encapsulate sets of closely related parameters in mini parameter transfer Classes.

For consistency, and for easier management and diagramming consider splitting this include file into 3 smaller include files corresponding with the 3 subclass helpers/builders of @BybundleAbstractBuilder.

There is an important IT moral to this story

Don't be discouraged if your UML overview diagrams are at first too complex, that is just your UML model telling you something very important, it is inviting you to refactor your system ! And the way to refactor it is to first identify such "scenarios" in separate diagrams. Later, these might become diagrams for dedicated Classes that correspond to a dedicated narrative.

Notes (policies)
Visit also