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
One 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.
Booleans
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
The 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
The 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.
During 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.
- 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).
- 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.
- 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.
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.
The API details of how to make the necessary registrations to accomplish these kinds of modifications are beyond the scope of this blog.