This page will contain the list of directives (or GUI hints) which we intend to define at template level (using annotations) that will be used by the GastrOS application to generate GUIs dynamically based on the underlying operational templates.

Note that this list will be heavily edited as we experiment!


 red/black: implemented/not implemented in Stage 1
 g - generic
 d - domain/application specific (i.e. to MST)
 c - conditional (depends on user input or system state)

  • isOrganiser (g): when this is set then it will be shown as a group which will contain all its children (i.e. as a frame, form etc.) The Heading in MST is an organiser. A container object will simply be ignored when isOrganiser is not set and all its children will be shown together with its immediate parent in the GUI. Might be useful to simply high level of nesting in clinical models.
  • isCoreConcept (g): This is an abstract concept; but we can say that Core Concepts are real-world entities which we can talk about their abscence (i.e. a clinical finding, a disease but not tumour grade or physical examination). The directive depicts whether a node with all its children (if any) shall be <ins>handled and repeated as a whole</ins> in an archetype (i.e. makes sense together such as a clinical finding with other attributes defining its nature). When the node and/or its children are selected, its <ins>presence information</ins> is stored in the corresponding ELEMENT node which records this (i.e. in MST Findings archetypes [Present?] node).
    In this case this node by becomes the "default axis" (i.e. if a clinical finding is selected as a core concept which has a number of descriptions and anatomical sites within then it can be said that this is a "finding oriented" view or in other words the default axis is "finding"). There can be an "alternate axis" in a Core Concept, in some cases more than one, which means that all the attributes and the default axis can be regrouped and rendered to an alternative view (i.e. this becomes a "site oriented" view). The alternate axis will be depicted by another directive.
    Splitting out of GUI container is not allowed unless allowChildrenSplit directive has also been set.
  • showAs (form|splash, modal|modeless|smart) (g): Determines the behaviour when node's values or children are displayed.The node's label is shown as a reference (i.e. link, button or similar) and the contents will be shown on another modal form - (form) or on a pop-up form (splash). (smart) is a special type of modeless form which closes when loses focus).
    • If this is a leaf node (i.e. ELEMENT) then its values will be listed to be selected (depending on the cardinality and occurrences allowed in the archetype single or multiple selection will be possible.
    • If this is not a leaf node then the node and all its children will be displayed using regular display options.
  • showWithParent (simple|merged)(g):This directive applies to nodes of type ELEMENT and causes display of its widget (label and values) at the same level as its immediate parent (simple); or display without label (merged) does not need further specification because the semantics is implied with the term alone (i.e. term tumour with attributes malignant/benign). Sites is an example for simple where it will simply be shown next to term. This directive is intended to make GUI simpler and require less space.
  • break (next|parent|tab) (g): causes the node and rest of the model to appear in the next column but within the same organiser (next); in the next column within a separate organiser which is semantically the continuation of current one (parent); in a new tab within the same form (tab).
  • formAspects (width=pixels, height=pixels, position, resize:none|hor|ver|both, startup mode etc.) (g): determine form's all aspects (the keywords TBD)
  • showText (multi|smart) (g): this applies to free text nodes (ELEMENT DV_TEXT). Only free text or coded list can be specified at archetype level. Normally a single line text box will be displayed; when this directive is used it will be possible to depict whether:
    • multiple lines are allowed but within a fixed height - with scroll bars (multi)
    • multiple lines are allowed in a text box which may expand (vertically and horizontally) to accommodate the content when entering data. When it loses focus it will return back to its initial size but will let use know that there is more content inside than can fit visible area. When user wants to see its contents (i.e. when control gets focus or mouse hover) it will expand again to show full contents (smart).
  • showValueContext (append|organise) (g): this applies to ELEMENT and cause the display of Description and Term together. Need for representing anatomical sites from multiple organs in single widget. It will simply append two or when used with organise parameter it will show distinct descriptions as organisers (i.e. as Separators in pick lists or separate columns with headings in Splash forms).
  • showInstances (number) (g): this applies to nodes where multiplicity is allowed and sets the number (n=positive integer) of repetitions displayed initially on GUI. Used for MST Diagnoses on form.
  • showDescription (g): when set text in "Description" of term_id will be shown together with label (later can be further specialised as appended or tooltip)
  • codedTextWidgetType (combobox|list) (g): TBD
  • allowChildrenSplit (g):can be applied only to container nodes (i.e. Cluster, Item, Event etc.). Normally the children of any container node will not be allowed to split into another column, frame/panel or form; however when this directive is in place then all immediate children (but NOT their children) will be allowed to split on the GUI. This will prevent splitting of MST Attributes but let splitting of individual MST Terms to a different column or tab when defined at the MST Heading level.
  • hideonGUI (g): determines whether the node and all its children will be hidden on GUI.
    Note that this is <ins>already present</ins> in the Ocean Template Designer (_hide_on_form=(True|False)); but not implemented yet to go into operational template.
  • hideChildren (simple|linked) (g): all the children under a node shall be hidden when the form is first initialised. Their further visibility will be controlled by the application (simple); however if this node is selected (i.e. either bu user selection or it has been selected during initialisation; such as it's presence is true from persistence or its default value) they will be displayed and then hidden each time the node is unselected (linked).
    NOTE: for sake of simplicity the hideChildren(linked) has been implemented in isCoreConcept directive. Otherwise they will be handled independently and both can exist separately.
  • alternateAxis (name) (g): as per above it designates a node within a Core Concept group as an alternative axis for GUI rendering.
    Note that when with the parent node of a Core Concept is container node and is an organiser (i.e. a frame/panel etc. for grouping purposes) depicted by the isOrganiserdirective, the alternate axis can also be relocated on top of that node in the hierarchy (i.e. Site can either go under MST Headings or above - refer to my thesis for details).

These are still under consideration

  • overrideDefaultWidget (widget type) (g): self explanatory - to assign a special widget other than predefined ones for each RM Class. It is obvious that the values of ELEMENTs of type DV_BOOLEAN will be displayed as radio button; but there may be cases where a combo box or a similar widget might be preferred (i.e. due to space constraints - the radio button takes more space). Another example is when displaying the values of ELEMENTS of other types such as DV_CODED_TEXT. We may want to show as radio buttons (mutually exclusive) or a combobox.
  • visibleWidgets(X)(g): a predefined number of individual widgets for multiple occurrences of ELEMENTs can be showed at once without manually adding extra widgets as necessary. This is the case where 4 diagnoses are selected in old app. We believe there is utility in this approach and can be useful to speed up data entry and more intuitive. This is also related with the showWithParent(merged) directive (i.e. the label will not be displayed for extra widgets).
  • mergeValues (g): useful for combining values of different ELEMENTs (under same parent) of type DV_CODED_TEXT to be shown together in a single widget. Of course these need to be defined as choice (i.e. mutually exclusive) so that it will be inferred where the value will be stored; for example Main and Other Diagnoses can be combined to be shown in a single pick list (as in old app.) and when a main Dx is selected it will be stored accordingly. We are not implementing in Stage 1 for sake of simplicity - we will have separate widgets for each category.
  • Some directive to depict whether a node can exist alone without further specifying children nodes (i.e. whether to allow selection of ulcer without specifying its site and/or other attribues; which does not make sense. However selecting hemorrhoids is possible because the site is implied and there are no other attributes.)
    BUT I don't like this because <ins>this is part of domain knowledge</ins> which should be represented at Archetype level - not in Templates.
  • TBD: what happens when a tree control kind of GUI is used? Probably need new directives or modify these.

These are deprecated:

  • presenceOnly (True|False) (g): some terms do not have any attributes as defined in MST; however the MST archetypes do have an ELEMENT of type DV_BOOLEAN which depicts its presence (or not). For the sake of simplicity and speed during data entry we do not want to click the Term and then select a value for presence. Instead we will hide the presence attribute and bind the check box of Term to the persistence object instead of using for showing/hiding its children 
  • getPresence (True|False) (g): For sake of simplicity and speed during data entry, it can be employed to let user to click a check box (or a combobox with a value list) to depict its presence at once (otherwise user has to click the node and then click the node depicting its presence). When applied to the ELEMENT which depicts the presence of a MST Term in our case, it will hide the presence attribute and display the the check box of [Present?] node next to the MST Term. Note that value of the [Present?] node will now bind to the existing widget used to select the parent (MST Term).
  • new (tab|form): this causes the node and rest of the model to be displayed in a new form or tab.


  • Although not needed in Phase 1 implementation (same with old application), we will need to specify which terms are allowed to be selected without further specifying attributes and/or sites. In other words we must be able to depict which terms can not be clinically valid when selected alone (i.e. presence). Ideally this is related with domain knowledge; hence must go into Archetypes. However currently the only way to ensure this is to define a invariant/rule. But this is problematic...So we may chose to (as an interim solution) define another directive for this purpose; i.e. allowSingleSelection (True/False). This issue is handled in openSDE with a fature called "Selection requires further evidence". Core concepts can probably exist by itself but need to test this. We should investigate whether these two are separate aspects.
    Related with this, hideChildren directive will allow to display of these nodes like core concepts initially; but their presence will not be recorded and will act like a dynamic organiser.
  • We chose not to implement allowChildrenSplit this in Stage 1 so we won't allow any Heading split; instead form will resize (for sake of simplicity!). <ins>One drawback</ins> will be in Additional Diagnostic and Therapeutic Procedures archetype where all >10 terms with many attributes are given under two headings only. In this case we decided to use a single break(next) to split them into two columns instead of multicolumns in two tabs; in other words we will not implement two tabs as in old app.
  • Some issues to discuss:
    • Requirement to display Urease (+) and Urease (-) on Findings for Stomach. This has been modelled as:
      CLUSTER: Rapid Urease Test
          ELEMENT>DV_CODED_TEXT: Result; values: positive|negative
      This can have only two outcomes: Yes or No. If we decide to use DV_BOOLEAN then we can not set custom labels such as Yes/No, True/False, Positive/Negative etc. because in ADL they don't have at codes in ontology.
      So two options: 1) Modify ADL to include such; 2) Provide labels with a GUI Directive (but translations will be problematic).
      I think the practical solution is to model all existing Yes/No type of data items with DV_BOOLEAN and GUI generator will assign Yes/No labels by default. Then for Urease and potentially similar binary items we continue to use DV_CODED_TEXT where we set labels in ontology. But in order to represent  with radio button we use a GUI Directive to inform GUI generator (Refer to overrideDefaultWidget directive above).
    • Kind of pre-coordination issue: for Urease data item is represented in GST with two radio buttons: Urease(+) and Urease(-). No organiser, no label but just two values. In order to display current MST model similarly we need to combine the label of the CLUSTER with the values (omitting ELEMENT label). When we change the label of CLUSTER: Urease and Values: (+) and (-) we can concatenate two labels and display. Some GUI directive to 'merge values with parent' is needed.
      However for simplicity and until we discuss with openEHR folks we will change the model and assign Urease(+) and Urease(-) values to ELEMENT>DV_CODED_TEXT: Result. Refer to showWithParent Directive; merged parameter describes just that.


  • Ocean Template Designer: when a tree is set to 0 occurrence (i.e. not allowed) the opt does not contain that part of the tree; however the at codes defined therein still exist. Suggest checking first if it is also used by any other node and then remove from opt. (

Last edited Feb 5, 2011 at 3:29 AM by atalagk, version 2


No comments yet.