Representing field types

In the previous post we examined how Mitopia’s GUI auto-generation capability handles the representation of structures and sub-structures and the fields within.  In an earlier post we looked at how the keyword ‘union’ is represented in the GUI.  In this post we will explore examples of how other more specialized field types are typically represented (remember each GUI renderer is a plugin and may adopt a different strategy).

Numeric Fields and Units


The display of numeric fields is a relatively straightforward matter as illustrated by the screen shots to the right.  Numbers can be displayed in single-line text controls and formatted according to standard conventions for integer and real numbers.

The main complicating issue with numbers is the question of units.  Numbers, especially floating point numbers, tend to have associated units with them and only by knowing the units associated with any numeric value is it possible to reliably interpret the number or to compare it with other numbers.  What we require is that every numeric field potentially have an associated unit value and that there exist a Mitopia® unit manager which understands units and unit conversions at a level necessary to allow the selection of compatible alternate display units (e.g., miles/h vs. km/h).  Mitopia® has a fledgling UnitMgr package but the support for unit conversion and the associated GUI connection through the DataModels abstraction to allow renderer interaction with units is incomplete at this time.  For this reason, you may see fields in the current base ontology that hold the units associated with other numeric fields.  This is a stop gap measure designed to preserve unit data until such a time as units and their UI ramifications can be fully supported in an integrated manner with the TypeMgr APIs and specified using the Carmot ODL.

When this is the case, the numeric displays where units are appropriate will have a unit popup menu after the number value and this popup will allow selection of any compatible unit in which to display the value during display or editing.  This means that all numeric fields with associated units are always actually held in the ‘prime’ unit value and the value displayed on the screen is obtained by the renderer through DataModels API calls which convert into the currently selected ‘display’ unit for the field concerned.  Unit compatibility and conversion is a complex matter and is rarely handled in any formalized manner in today’s systems.  Units might include currency values which require near-real-time lookups, and they might include units such as distances on the earth’s surface which require complex calculations involving other fields of the record in order to make the necessary conversions.  The full support of units within the Mitopia® type manager infrastructure will be a subject of future R&D.  The problem is similar in many ways to tracking union ‘state’ since we cannot place the display unit into the actual record structure, but must instead track it in the associated collection structures.
Numeric fields should generally use the maximum precision available (i.e., int64 or double) unless there is good reason to be certain that a smaller representation (e.g., int32) will never overflow.  Beware of falling into the trap of including units in a field name (e.g., ‘heightInInches’) since this will violate the unit manager abstraction when available.  Field names should be meaningful without including units (i.e., ‘height’).

Dates and Time

DateFieldOne special case of numeric formatting and units is the whole area of dates, time and calendars.  In Mitopia® and in the DataModels abstraction layer there is extensive support for date handling and display by renderers.  Mitopia® stores dates and times as double precision floating point numbers where the whole number part represents the ‘Serial Day Number’ (SDN) and the fractional part represents the time of day.  See the earlier section on “Numeric Queries” for details of date encodings.


There are of course a significant number of different calendar systems in effect throughout the world and it is necessary to convert to/from these ‘units’ during date display and entry.  Currently Mitopia® provides support for GUI renderers to convert between the Gregorian, Julian, Islamic (x2), and Hebrew calendar systems.  Additionally, Mitopia® contains code internally to handle and convert between virtually all known common calendar systems such as the Alexandrian Calendar, the Armenian Era Calendar, the Badi & Baha’i Calendars, the Chinese Calendar, the Egyptian Coptic Calendar, the Ethiopian Calendar, and roughly 20 others including the Ancient Mayan calendar.

The screen shots on this page illustrate the rendering of date values in the default renderer and illustrate the various controls available for choosing the date display format.  In this sense, date conversion can be seen as a special case of unit conversion involving complex astronomical calculations in order to make the conversion.  Once the unit conversion mechanism is fully developed, the behavior of date controls will simply be a subset of that of any numeric value with associated units.


Note that times and dates must not only be aware of the calendar system in effect, but also of the time zone.  All times are stored in GMT which means that displaying local time at any particular location also involves a conversion based on the time zone and any daylight savings time that might be in effect.  Once again even this time zone calculation can be quite complex but is essential if dates and times are to be easy to use by the users while remaining useful for analytical, comparison and search purposes to the rest of the underlying code base.  This whole area tends to be glossed over in most systems, but the existence of the flat memory model and the ability to reliably track the current display ‘state’ in the underlying abstraction without having to modify the actual structure fields, mean that dates and times, like all other unit issues can be fully handled by the substrate without renderer knowledge.  This includes the ability to lay out calendar days into months (see screen shot to the right).  As a side benefit the date/time abstraction can function as an astronomical almanac yielding times for moon rise/set, sun rise/set, twilight, phases of the moon etc.  In many cultures these calculations can in turn be used to compute other important information (e.g., Islamic prayer times, Hebrew Havdalah etc.).  The Mitopia® date conversion utilities provide all of these features/calculations although few are exposed in any direct way through current renderers.

Text Fields


The display of text fields is one of the most commonplace and pervasive behaviors of any renderer.  The screen shots in this section illustrate a number of display formats used by the default renderer for showing text.  The standard strategy is to display the text in a text control of a size that is just sufficient to display whatever text is actually in the record.  Thus we see that in the case of the ‘other’ field, the renderer (through interaction with the DataModels layer) determined how much text was available and made the control just large enough to display the it.  In the case of the ‘name’ field, the render has determined that a single line control is sufficient.  The ‘description’ field shown is empty and thus can fit into half a column in this case.  Furthermore the ‘subType’ field that follows is mentioned in the $ShortStrings annotation (see annotations discussion) for Organization and thus empty or not is a candidate for packing two to a column.  The ‘keyWords’ field shown despite being empty is followed by a collection reference field (‘divisions’) which requires a full column width to display and this means that the ‘keyWords’ field is extended to the end of the line to avoid creating odd looking gaps.


Mitopia® (and the plugin renderers) provides full support for highlighting areas of the text under program control and also for the automatic and pervasive creation of hyperlinks within displayed text.  In the ‘borderCountries’ field screen shot, we see the effect of turning on the ‘Country’ hyperlink domain.  Clicking on any of the hyperlinks displayed will result in navigating to and displaying the associated record through Mitopia’s invocation abstraction.  In the final screen shot for the ‘executive’ field we see a situation where the renderer has been unable to fit all the text into the display area due to layout constraints, in which case the text control is size limited and can be selected and scrolled as shown in order to examine the entire text string.

Styled Text


In the screen shot above (taken from the stemmer development window), we see on the far right an HTML display field extracted from a dictionary definition of the word ‘abdicate’.

If you look in the base ontology under the type DictionaryEntry, you will note that the ‘description’ field is intended to hold HTML text.  During AutoUI generation, the content of any valued ‘@char’ field is examined, and if it contains a block bounded by “<html” and “</html>”, an HTML control is used instead of a standard text control.  The effect is that persistent records can contain text styled using HTML which can thus be displayed throughout the standard auto-generated UI.  Of course this capability to embed HTML into the fields of a record should be used sparingly since the embedded HTML tags within the field make the content less useful for search purposes, and it is not clear how such HTML fields can be easily or reliably edited manually by the user.  Note that the default renderer text control is fully capable of displaying and editing simple ‘styled’ text (as indicated by the hyperlink screen shot in the previous section), the problem is that there is not currently any standardized persistent way to represent styled text in the server collections and restore the styles in user displays.



The screen shot to the right illustrates the rendering of Boolean fields by the default renderer.  As can be seen, Booleans are rendered as checkbox controls and can be packed two to a column in most layouts.  The screen shot is of a portion of the ‘SystemRelated’ type ‘InterestProfile’ for which the corresponding Carmot field definitions appear as shown in the listing below.


Bit Fields and Enumerated Types


Enumeration1The use of the C bit field capability is generally restricted to cases where existing hardware registers or encoding formats must be matched or where data storage restrictions are so severe that data must be packed as tight as possible.  None of these conditions are likely to apply to ontological types declared in Carmot, although they do apply to the platform C header files which must also be compiled by the Carmot language.  For this reason, Carmot provides full support for C’s bit field syntax.  In the listing above, driven by platform headers, we see a type definition combining both bit field definition and enumerated types within those bit fields.


The two screen shots in this section illustrate the appearance of the type defined in the listing above when rendered in the default renderer.  As can be seen, the fact that a field is a bit field rather than a normal integer type makes no difference to how it is displayed and bit fields are thus indistinguishable from other numeric fields.  The fact that the ‘segment’ field is tied to an enumerated type results in it being displayed both as a numeric value and as a popup with the enumeration options as entries.  This makes the value much easier for users to understand and enter.  If the field type has an associated $MultiSelect annotation, then the popup is a multi-select popup and the field can be used to handle bit mask values such as options flags.  The use of enumerations in this manner is not restricted to bit fields of course and can be used with any integer field.

If the number of enumerated values is small and the $MultiSelect annotation is not present, for example if the enumeration were tied to a Boolean, it might be preferable for the renderer to display the field as a radio button group.  Larger radio button groups might be generated as a result of say a $RadioButton annotation on the field.

Persistent References

Persistent1The display and handling of persistent references requires a text control to display the referenced item name, a popup selector to choose the referenced type, and an icon button (displaying the jagged arrow) to cause immediate navigation to the referenced item using the Mitopia® invocation abstraction.

The popup selector is rooted in the declared referenced type for the field but allows selection of more specific types (if any) during manual data entry.

ListPickDuring manual data entry, an additional list icon button is displayed such that clicking on the button launches a list selection dialog (as shown to the left).  This allows the user to examine the list of possible items (and their fields) that could be referenced (in this case countries).  If the domain of reference is too large, the user will be prompted to create the reference through some other means (e.g., drag & drop).


Persistent Collection References


The display and handling of collection references is performed by renderers using list controls as illustrated in the screen shots in this section.  The column headers for these list controls are driven by the $ListSpec annotation for the field or referenced type.  If no $ListSpec is specified for the field/type, inheritance will cause the $ListSpec for Datum to be used which results in a list containing just the ‘name’ field.

Lists can be sorted by column in exactly the same way described earlier for node navigation.

Double-clicking on a cell within such a list causes the referenced item to be launched and displayed via the Mitopia® invocation abstraction for “Display”.  If the ‘option’ key is held down while double-clicking on a cell, the launch is invoked for “Info”.  See other Mitopia® documentation for details.  Note that the field values displayed in the list control are the contents of the fields of the referenced item, not the referencer, and one or more of these fields may in fact be a persistent reference.  Double-clicking on such a second-level reference launches the second-level item referenced, not the primary reference.  Thus in the last screen shot above, double-clicking on a ‘name’ column cell would launch the NoteRelating record, double-clicking on a ‘relationType’ column cell would launch the RelationType record for “Picture of”, and double-clicking on a ‘related’ column cell would actually launch and display the related JPEG image.

Relative Collection References
The screen shots above illustrate the appearance of ‘@@’ fields when being edited in the auto-generated user interface.  The type definition is for the GUI Canvas type used by Mitopia’s universal GUI renderer layer.  See the type definitions in K.DEF for details on the Canvas and Control types.
The critical difference is that the layout algorithm has chosen to display the ‘controls @@’ fields in a separate tab within the containing record display, just as it would for a sub-structure.  Within that tab, the ‘@@’ collection is displayed as a full height list on the left hand side of the display while any selected node in the list is displayed in an embedded data model view to the right of the list.  Note also that the lists are both horizontally and vertically scrollable in order to account for the possibility of nested hierarchies within the ‘@@’ collection (see the lower screen shot).  Given sufficient screen real-estate, the nested lists and DMVs can be repeated for many levels, which gives the user the ability to examine in depth the inner structure of the data stored in ‘@@’ collections if necessary.  This ability is not relevant for ‘##’ collections because these are nothing more than references to the outer collection (and persistent storage), so that double-clicking on a ‘##’ list entry causes the entire display to be replaced from the outer level by the content of the referenced record.  There is thus no need to nest displays as shown for the ‘@@’ case.  In contrast, if one double-clicks on a ‘@@’ list entry in display mode, this has no effect, however, a double-click in Edit mode will cause the selected entry to be displayed in the outer DMV just as for the ‘##’ case.
The screen shot to the right illustrates the effect of double clicking on the “ListView10742” entry in the first level ‘@@’ collection.  The content of the ‘ListView10742’ record is displayed in the DMV to the right.  Relative collections fields and the types they reference can have associated “$ListSpec” annotations in a manner identical to the ‘##’ case, and in these cases, the list displayed will contain the relevant titles over and above the default “Name” column.
Since Mitopia® places few restrictions on the data that can be displayed in an ‘@@’ sub collection, they can be used for a wide variety of data processing purposes, and thus the auto-generated UI can be a very convenient way for examining these complex structures.  In particular, the sub-collection may use any of the supported organizational metaphors (tree, list, stack, ring, queue, N-array etc.).  The only restrictions placed on the data in the ‘@@’ sub collections are the following:
  1. Records cannot be derived from ‘Datum’, but can use persistent (‘#’) and persistent collection (‘##’) reference fields.  Echo specifications that are mediated through ‘@@’ collection elements must use the ‘><><‘ indirect echo specification syntax (see earlier posts).
  2. Record types should either have a ‘name’ field (either char[] or char@) or a $UniqueBy annotation specifying another field that is used to disambiguate different records within the same parent node of the ‘@@’ hierarchy.  If names are not unique within a given node, the associated records will be merged during MitoMine™ or when persisted to the servers.
  3. The ‘@@’ nodes themselves, regardless of if they have associated values (which is permitted for any node) can be named and if they are, the merge process during MitoMine™ or when persisted to servers, will take account of the node name also.
Non-’char’ Relative References

As described previously, by default, the MitoQuest™ container registers to handle all field types other than a relative reference to a type other than char. This means that all support for rendering of these MitoQuest™ fields is provided and registered internally to Mitopia®.  When one adds a new multimedia type and a corresponding relative reference to that type as part of the Carmot ontology for a system, it is necessary also to register or add code to handle the display of that type within auto-generated UI.  This allows the renderer to display the associated item to the user.


The screen shot above shows the effect of this for the Image type as referenced in the ‘Picture @preview’ field of a Video.  To the right is a screen shot of the ‘Picture @picon’ field of the type Image.  The screen shot below shows that this registration of custom display formats can even be extended to persistent references to the type as in the ‘related’ field in this NoteRelating record.

By clicking on the camera icon, one can immediately launch and display the associated multimedia.  One might imagine sound references being playable in a similar manner, or indeed launch and display of any other custom registered multimedia type.
ApacheThe API details of how to make the necessary registrations to accomplish these kinds of modifications are beyond the scope of this blog.