OrgUnitPicker Reference

[This is preliminary documentation and is subject to change.]

An OrgUnitPicker element is used to select a single OrgUnit. The key values of the selected OrgUnit are saved in fields that are automatically generated in the form.

Note
Most field types generate 1 database field (named after the DataName property. OrgUnitPicker is special - it generates 2 fields in the database table (one field with field name suffix _TYPE and one field with field name suffix _CODE).

Each OrgUnitPicker element may be configured as dropdown or floating/popup window. These modes have very different set of configurations possibilites, and they generate very different user interface for the end user. Chosing between these modes is the first (and most important) decision to make when configuring an OrgUnitPicker.

This page only describes the properties specific for OrgUnitPicker. These propeties are grouped on the "OrgUnitPicker" tab in the form editor. Several propeties are inherited from base classes. The inherited properties are described elsewhere (TODO!).

See OrgUnitPicker for comments extracted from the source code.

OrgUnitPicker properties (for all modes)

Field

Type

Description

Mode

PickerMode enumeration

XML

Editor

Description

DropDown

The OrgUnitPicker is rendered as a dropdown list.

This is the default value.

It is the configurators's responsibility to make sure, that the OrgUnitPicker does not contain too many OrgUnits. If the database contains thousands of OrgUnits, and the OrgUnitPicker is configured to contain all OrgUnits in the database, performance may get very poor, and it is not user friendly to force an end user to select a value from a dropdown having thousands of values. The configurator should set properties from the table "OrgUnitPicker properties (for dropdown mode only)" below to limit the list of OrgUnits selecteable in the dropdown to a manageable number.

PopUpWindow

The OrgUnitPicker is rendered as a (read-only) field displaying the selected value, and a pair of buttons:

Search: clicking this button will open a popup window, that allows end user to search for OrgUnits by type, code and/or name. When an OrgUnit is selcted, this OrgUnit is set as the currently selected value in the OrgUnitPicker.
Clear: clicking this button will clear the currently selected value in the OrgUnitPicker.

Note that it is possible to configure 2 different kinds of popup windows - see property PopUpMode below.

Note
Properties from the table "OrgUnitPicker properties (for dropdown mode only)" have NO effect.

InputField

Boolean

Default value is false, which results in that the input field is not shown, and the user cannot key in anything.

When set to true, an input field is displayed, allowing the user to key-in (part of) key for an organizational unit.

Note
This input field is an ADDITIONAL input method - enabling this input field does not disable the "normal" input methods (dropdown or popup window).

When user types in a key of an existing OrgUnit, the corresponding dropdown or read-only text field is automatically updated accordingly. The other way around - when user selects an ORgUnit using dropdon ro popup window, the input field is automatically updated.

Note

In versions of TOPICA BEFORE 4.30, this only works when the .config-parameter EnableJavaScriptCallingWebservices is set to true (note that the default value is false!).

In TOPICA 4.30 and later, EnableJavaScriptCallingWebservices is deprecated.

The end user needs to specify the key of the requested OrgUnit. How this is done depends on property TypeFilter:

If TypeFilter is defined, user only needs to key in the code of the organizational unit.
If TypeFilter is NOT defined, user needs to key in the full key of the requested organizational unit in the format "type:code".

TypeFilter

String

Specifies the organizational unit type used to filter the list of selectable OrgUnits.

OrgUnitPicker properties (for popup mode only - Mode=1:PopUpWindow)

Field

Type

Description

PopUpMode

PopUpMode enumeration

XML

Editor

Description

Default

The popup mode is defined on the applicaton level. The effective mode is defiend in the .config-file parameter Template.OrgUnitPicker.PopUpMode, that may may have these values:

NewBrowserWindow
FloatingWindow

This is the default value.

If all OrgUnitPicker elements are set up with this value, it is easy to switch between NewBrowserWindow and FloatingWindow on the application level.

NewBrowserWindow

Clicking the "Search" button opens a new browser window. This window is "detached" from the window containing the form with the OrgUnitPicker, and is not modal. This means that it is possible to activate the original form window without closing the popup window. It is even possible to close the original form window, leaving the popup window "dangling" (not recommended...).

FloatingWindow

Clicking the "Search" button opens a "floating window" within the boundaries of the original form window. This floating window is modal - i.e. it must be closed before the original form window is activated again.

Boolean

Default value is false. Note however, that if Tree is false, the default behavior is like when Search is true!

When set to true, a search form is displayed in the popup window. In this search form the end user may enter search criterias for OrgUnits: type, code and/or name. When clicking the "Search" button, the found OrgUnits are diosplayed in a grid with paging.

Tree

Boolean

Default value is false.

When set to true, a tree view (hierarchical organization structure) is displayed. In this tree the end user may expand/collapse branches and ultimately select one OrgUnit.

Search and Tree are not mutually exclusive:

If both Search and Tree are false, the search form is displayed.
If both Search and Tree are true, both the search form and the tree view are displayed - in separate tabs.

OrgUnitPicker properties (for dropdown mode only - Mode=0:DropDown)

As described above, when using dropdown mode it is the configurators's responsibility to make sure, that the OrgUnitPicker does not contain too many OrgUnits.

The properties in this table are used to limit the list of Selectable OrgUnits in the dropdown.

These propeties may also be used to define some "business logic". For example to configure that the end user should only be able to select department on a the "current" hospital, and/or only departments having some specific functions or clinical specialties.

One useful pattern for using these properties are:

Establish a "starting point" (an OrgUnit in the hierarchy) from the context. Use property OrgUnitSelection to define this.
Optionally move from the "starting point" to the "root" (an OrgUnit specifying the subset of the organization hierarchy to search in). Per default the "root" is the same as the "starting point". Use property TypeAncestor to specifiy the "root" as an OrgUnit "above" the "starting point".
Set property Descendants=true to populate the dropdown with OrgUnits "below" the "root".
Optionally set property TypeFilter to limit the selectable OrgUnits to a specific type.
Optionally set property FunctionFilter to limit the selectable OrgUnits to those having a specific function (e.g. medical specialty).

Field

Type

Description

OrgUnitSelection

OrgUnitSelection enumeration

This property specifies how to determine the "starting point" in the organizational hierarchy. The "starting point" may be determine from various information in the context.

XML	Editor	Description
0	All	All OrgUnits in the database are selectable in the OrgUnitPicker. May be combined with TypeFilter and/or FunctionFilter. Values in Ancestors, Descendants, TypeAncestor, IncludeRoot have no effect.
1	Configured	Only OrgUnits configured as "data owners" are selectable in the OrgUnitPicker. May be combined with TypeFilter and/or FunctionFilter. Values in Ancestors, Descendants, TypeAncestor, IncludeRoot have no effect.
2	DataOwner	The current "data owner" is used as the "starting point". Obviously these only works when a data owner is established. This means, that an OrgUnitPicker with this value set MUST be placed on a form BELOW encounter level (because an "encounter" per definition is the place in the data model, where data ownership is established). May be combined with TypeFilter, FunctionFilter, Ancestors, Descendants, IncludeRoot
3	DataOwnerAncestor	The current "data owner" combined with an ancestor defined by TypeAncestor is used as the "starting point". Obviously these only works when a data owner is established. This means, that an OrgUnitPicker with this value set MUST be placed on a form BELOW encounter level (because an "encounter" per definition is the place in the data model, where data ownership is established). TypeAncestor must be specified, and MUST refer to a an organizationl unit type ABOVE the data owner. May be combined with TypeFilter, FunctionFilter, Ancestors, Descendants, IncludeRoot
4	EmployeeAssociated	TODO
5	PatientOrgUnit	TODO
6	PatientOrgUnitAncestor	TODO

Ancestors

Boolean

Default value is false.

When set to true, all ancestor organizational units from the so called "starting point" and upwards in the hierachy are selectable in the OrgUnitPicker. This is very rarely used.

Descendants

Boolean

Default value is false.

When set to true, all descendants organizational units from the so called "starting point" and downwards in the hierarchy (optionally filtered by TypeFilter and/or FunctionFilter) are selectable in the OrgUnitPicker.

When both Ancestors and Descendants are false, the effect is, that the end user may select only ONE OrgUnit in the dropdown (the "root"). This is not very useful. So in most situations, Descendants should be true on OrgUnitPicker elements dropdown mode. The "root" is called the "root" for a reason - it normally defines the common rot of all the OrgUnits selectable in the OrgUnitPicker, and this obviously requires, that Descendants should be set to true.

IncludeRoot

Boolean

Default value is false.

When set to true, the so called "starting point" is selectable in the OrgUnitPicker.

Example:

OrgUnitSelection is DataOwnerAncestor.
Data owner is established, and type of data owner is "hospdep" ("hospital department").
TypeAncestor is "hosp" ("hospital").
If IncludeRoot is false, the OrgUnitPicker will contain all departments in the hospital "owning" the "data owner" (the department specified by the encounter) - but NOT the hospital.
If IncludeRoot is true, the OrgUnitPicker will contain all departments in the hospital "owning" the "data owner" (the department specified by the encounter) AND the hospital.

TypeAncestor

String

Used only when OrgUnitSelection is DataOwnerAncestor or PatientOrgUnitAncestor

Specifies the organizational unit type used to find the "root" ancestor (relative to the "starting point"). I.e.:

Start at the "starting point".
Walk up the organization hierarchy until an OrgUnit having type equal to the value specified in TypeAncestor is found.
The found ancestor is called the "root".
If TypeAncestor is true, the dropdown is populated with all the descendants from the "root" (after optional filtering by TypeFilter and/or FunctionFilter).

FunctionFilter

String

Specifies the organizational function code used to filter the list of selectable OrgUnits.

ShowCurrent

Boolean

Default value is false, which results in no extra display of the current value.

When set to true, the currently selected OrgUnit is displayed in the form (beside the dropdown).