Caisis Input Controls

From CaisisWiki

(Difference between revisions)
Jump to: navigation, search
m (CascadeFormatString (string))
(Lookup Code Properties)
 
(7 intermediate revisions not shown)
Line 1: Line 1:
 +
Translations: [[Caisis_Input_Controls&action_it|italiano]]
 +
 +
===About===
 +
Caisis Input Controls provide the base for most of the UI controls in the application, which build upon many of the standard .NET controls, such as TextBoxes, TextAreas, CheckBoxes, RadioButton, DropDownList, etc... These controls provide useful Properties which allow for easily modifying and applying various UI elements (calendars, numberpads,icons,descriptions...) with little to no coding.
 +
 +
The Caisis Input Controls also provide additional properties to help associate them with [[Business Objects]]. Properties such as Table and Field help associate values of controls to their associated database field names and tables.
 +
===Interfaces===
===Interfaces===
 +
 +
----
 +
====ICaisisInputControl====
====ICaisisInputControl====
 +
The interface ICaisisInputControl provides commonly used UI elements into helpful properties as well as providing support to handle matching controls to associated [Business Object] Fields.
'''Controls Implementing ICaisisInputControl'''  
'''Controls Implementing ICaisisInputControl'''  
*CaisisTextBox
*CaisisTextBox
Line 14: Line 25:
====ICaisisLookupControl====
====ICaisisLookupControl====
 +
The ICaisisLookupControl provide easy access to bind controls to LookupCodes, as defined by the Administrator. There are also additional properties used to generate dynamic lookup codes based on user selected values.
'''Controls Implementing ICaisisLookupControl'''
'''Controls Implementing ICaisisLookupControl'''
*CaisisSelect
*CaisisSelect
*CaisisComboBox
*CaisisComboBox
 +
=== Base Properties ===
=== Base Properties ===
 +
----
By default, all controls that implement the ICaisisInputControl interface, have these properties exposed to be set and retrieved by user code. These properties provide easy access to many of the control's UI elements, as well as database related properties such as Table and Field, which allow for syncing with [[Business Objects]].
By default, all controls that implement the ICaisisInputControl interface, have these properties exposed to be set and retrieved by user code. These properties provide easy access to many of the control's UI elements, as well as database related properties such as Table and Field, which allow for syncing with [[Business Objects]].
Line 55: Line 69:
The CSS class name to apply to the control.
The CSS class name to apply to the control.
-
===Extended Properties===
+
 
-
The following properties are exposed by controls implementing the ICaisisLookupControl interface. This provides easy access to binding to [[Lookup Codes]] as well, as offering dynamic cascading values through related controls.
+
===Lookup Code (Drop down options) Properties===
 +
----
 +
These input field properties allow you to control the values available in select boxes and combo boxes.
 +
 
 +
The following properties are exposed by controls implementing the ICaisisLookupControl interface. This provides easy access to binding to [[Lookup Codes]] as well, as offering dynamic cascading values through related controls. LookupCode and LookupDistinct are AjaxCallbacks.  The code that handles these callbacks can be found in Caisis.UI\Core\Utilities\LookupCodesCallBack.aspx.cs
====LookupCode (string)====
====LookupCode (string)====
-
A code used to retrieve results from the database.
+
A code used to retrieve a series of drop down values from the database.
====LookupDistinct (string)====
====LookupDistinct (string)====
-
Controls filtering of lookup values.
+
Syntax used to populate drop down options based on unique values in a table column.
 +
 
 +
The format is "tablename;valuefield;textfield;restriction;order". ''order'' and ''restriction'' are optional. Behind the scenes, the Distinct query that looks like this: "SELECT DISTINCT ''valuefield'' AS DropDownValue, ''textfield'' AS DropDownText FROM ''tablename'' WHERE ''restriction'' ORDER BY ''order''".
====CascadeValuesBasedOn (string)====
====CascadeValuesBasedOn (string)====
-
(Advanced) When combined with the CascadeFormatString, lookup codes for a control are generated on the fly (client-side through javascript,CaisisComboBox), or via AutoPostBack events (via server,CaisisSelect). This property takes a list of comma-seperated list of related Fields. When lookup codes are needed (during a combo box click event), then values are extracted from these related fields and used to build a dynamic lookup code that is retrieved from the server.
+
Used in combination with CascadeFormatString to filter one set of drop down options based on the selection of a previous term.
 +
 
 +
For example, selecting a Medical Therapy Type of "Chemo" could filter the Agent values to display only "Taxol, Accutane, Cisplatin, etc.. instead of the entire list of Medical Therapy agents. Association between the Parent and Child codes can be made using the Lookup Code administration interface (relating Type to Agent in this example).
 +
 +
This property takes a list of comma-separated field names. For most input fields you will supply a list of Field names, i.e., "MedTxType,MedTxAgent", which will locate the fields based on its "Field" attribute.
 +
 
 +
For other instances where multiple input controls which have the same Field name (such as Eforms), you will need to specify the ID prefaced by a "$", which will locate the fields based on its "ID" attribute. Below are examples of how you would filter anatomy sub-sites based on the selection of a previous site (i.e. select skull, then display subsites mandible,
 +
 
 +
* '''Patient Data Entry Forms: Cascades based on Field Names'''
 +
** CascadeValuesBasedOn="ProcSite,ProcSubSite"
 +
*** use the input control where Field="ProcSite"
 +
*** use the input control where Field="ProcSubSite"
 +
 
 +
* '''EForms: Cascades based on Field Ids'''
 +
** CascadeValuesBasedOn="$ProcSite1,$ProcSubSite1"
 +
*** use the input control where ID="ProcSite1"
 +
*** use the input control where ID="ProcSubSite1"
 +
 
 +
* '''EForms - where one selection cascades to any number of other drop down options'''
 +
** CascadeValuesBasedOn="ProcSide,$ProcSite1"
 +
*** use the input control where Field="ProcSubSite"
 +
*** use the input control where ID="ProcSite1"
====CascadeFormatString (string)====
====CascadeFormatString (string)====
-
(Advanced) Specifies the format of the dynamic lookup codes, based on values of the related control (CascadeValuesBasedOn). Format is similar to C# String.Format method where string "my first value: {0} and second value: {1}" will have {0} and {1} replaced with an array of values, based on an index 0-n. In this case, the array of values are determined by the controls referenced(by Field names) in CascadeValuesBasedOn. In addition to using indexes of related control, you may also use the n. prefix to extract a number from the control's value. Below is an example of how this property is combined with the CascadeValuesBasedOn.
+
Specifies the format of the cascading(filtered) lookup code. Format is similar to C# String.Format method where string "my first value: {0} and second value: {1}" will have {0} and {1} replaced with an array of values, based on an index 0-n. In this case, the array of values are determined by the controls referenced(by Field names) in CascadeValuesBasedOn. In addition to using indexes of related control, you may also use the n. prefix to extract a number from the control's value. Below is an example of how this property is combined with the CascadeValuesBasedOn.
-
'''Example:'''  
+
'''Advanced Example:'''  
-
We have the field ClinStageT represented by the CaisisComboBox control.  
+
We want the ClinStageT values to change based on the user's choice of ClinStageDisease and ClinStageSystem.
-
On this same form there are two CaisisSelect(DropDownList) represented with Field ClinStageDisease and ClinStageSystem.
+
On the Clinical Stages form ClinStageT is a CaisisComboBox control, and ClinStageDisease and ClinStageSystem are CaisisSelect(DropDownList).
We now set the related properties.
We now set the related properties.
Line 82: Line 123:
When we change the values of ClinStageDisease or ClinStageSystem, the lookup code which the ClinStageT ComboBox generates is based on the two observed values. So if we select Prostate for the ClinStageDisease, and select UICC_02 for ClinStageSystem, we will generate a lookupcode "StageClin_Prostate_02_T", since the "Value" of ClinStageDisease is "Prostate" and the "Value" of ClinStageSystem is "UICC_02". We only extract the number for the ClinStageSystem "Value", as our format string said to parse out a number, "{n.1}" from the value at index 1.
When we change the values of ClinStageDisease or ClinStageSystem, the lookup code which the ClinStageT ComboBox generates is based on the two observed values. So if we select Prostate for the ClinStageDisease, and select UICC_02 for ClinStageSystem, we will generate a lookupcode "StageClin_Prostate_02_T", since the "Value" of ClinStageDisease is "Prostate" and the "Value" of ClinStageSystem is "UICC_02". We only extract the number for the ClinStageSystem "Value", as our format string said to parse out a number, "{n.1}" from the value at index 1.
-
NOTES: If the control using these properties is a CaisiSelect, everytime an observed control changes values, it will cause a post back to the server, causing syncing issues with retaining values. The CaisisComboBoxes however do not post back, as values are generated via javascript and are retrieved using Client CallBack, there is no need to worry about retaining values. If unsure, CaisisComboBoxes always provide the best method to handle dynamic lookup codes.
+
NOTES: If the control using these properties is a CaisisSelect, everytime an observed control changes values, it will cause a post back to the server, causing syncing issues with retaining values. The CaisisComboBoxes however do not post back, as values are generated via javascript and are retrieved using Client CallBacks, there is no need to worry about retaining values. If unsure, CaisisComboBoxes always provide the best method to handle dynamic lookup codes. The controls being observed (CascadeValuesBasedOn) can still be any type of control, even a CaisisSelect.

Current revision as of 18:54, 8 December 2011

Translations: italiano

Contents

About

Caisis Input Controls provide the base for most of the UI controls in the application, which build upon many of the standard .NET controls, such as TextBoxes, TextAreas, CheckBoxes, RadioButton, DropDownList, etc... These controls provide useful Properties which allow for easily modifying and applying various UI elements (calendars, numberpads,icons,descriptions...) with little to no coding.

The Caisis Input Controls also provide additional properties to help associate them with Business Objects. Properties such as Table and Field help associate values of controls to their associated database field names and tables.

Interfaces


ICaisisInputControl

The interface ICaisisInputControl provides commonly used UI elements into helpful properties as well as providing support to handle matching controls to associated [Business Object] Fields. Controls Implementing ICaisisInputControl

  • CaisisTextBox
  • CaisisTextArea
  • CaisisSelect
  • CaisisHidden
  • CaisisCheckBox
  • CaisisComboBox
  • CaisisRadioButton
  • CaisisRadioButtonList
  • CaisisExtendedCheckBoxList
  • CaisisExtendedRadioButtonList

ICaisisLookupControl

The ICaisisLookupControl provide easy access to bind controls to LookupCodes, as defined by the Administrator. There are also additional properties used to generate dynamic lookup codes based on user selected values. Controls Implementing ICaisisLookupControl

  • CaisisSelect
  • CaisisComboBox


Base Properties


By default, all controls that implement the ICaisisInputControl interface, have these properties exposed to be set and retrieved by user code. These properties provide easy access to many of the control's UI elements, as well as database related properties such as Table and Field, which allow for syncing with Business Objects.

Table (string)

The name of the Database Table corresponding to a control.

Field (string)

The name of the Database Table's field corresponding to a control

Value (string)

This is the corresponding "text" value of a derived control. So, for TextBox the Value field refers to the TextBox's value, for TexArea's value, DropDownList, SelectedValue.

Visible (boolean)

The name of the Database Table corresponding to a control.

FieldLabel (string)

The name to display next to the control.

Required (boolean)

Shows if this field is required on data entry forms.

ShowHelpBubble (boolean)

True or False value indicating wheather to show a help description for a control.

HelpDescription (string)

The help description displayed for a control.

ShowLabel (boolean)

True or False indicating weather to show a control.

Enabled (boolean)

True or False indicating weather to is enabled for editing/modifying.

CssClass (string)

The CSS class name to apply to the control.


Lookup Code (Drop down options) Properties


These input field properties allow you to control the values available in select boxes and combo boxes.

The following properties are exposed by controls implementing the ICaisisLookupControl interface. This provides easy access to binding to Lookup Codes as well, as offering dynamic cascading values through related controls. LookupCode and LookupDistinct are AjaxCallbacks. The code that handles these callbacks can be found in Caisis.UI\Core\Utilities\LookupCodesCallBack.aspx.cs

LookupCode (string)

A code used to retrieve a series of drop down values from the database.

LookupDistinct (string)

Syntax used to populate drop down options based on unique values in a table column.

The format is "tablename;valuefield;textfield;restriction;order". order and restriction are optional. Behind the scenes, the Distinct query that looks like this: "SELECT DISTINCT valuefield AS DropDownValue, textfield AS DropDownText FROM tablename WHERE restriction ORDER BY order".

CascadeValuesBasedOn (string)

Used in combination with CascadeFormatString to filter one set of drop down options based on the selection of a previous term.

For example, selecting a Medical Therapy Type of "Chemo" could filter the Agent values to display only "Taxol, Accutane, Cisplatin, etc.. instead of the entire list of Medical Therapy agents. Association between the Parent and Child codes can be made using the Lookup Code administration interface (relating Type to Agent in this example).

This property takes a list of comma-separated field names. For most input fields you will supply a list of Field names, i.e., "MedTxType,MedTxAgent", which will locate the fields based on its "Field" attribute.

For other instances where multiple input controls which have the same Field name (such as Eforms), you will need to specify the ID prefaced by a "$", which will locate the fields based on its "ID" attribute. Below are examples of how you would filter anatomy sub-sites based on the selection of a previous site (i.e. select skull, then display subsites mandible,

  • Patient Data Entry Forms: Cascades based on Field Names
    • CascadeValuesBasedOn="ProcSite,ProcSubSite"
      • use the input control where Field="ProcSite"
      • use the input control where Field="ProcSubSite"
  • EForms: Cascades based on Field Ids
    • CascadeValuesBasedOn="$ProcSite1,$ProcSubSite1"
      • use the input control where ID="ProcSite1"
      • use the input control where ID="ProcSubSite1"
  • EForms - where one selection cascades to any number of other drop down options
    • CascadeValuesBasedOn="ProcSide,$ProcSite1"
      • use the input control where Field="ProcSubSite"
      • use the input control where ID="ProcSite1"

CascadeFormatString (string)

Specifies the format of the cascading(filtered) lookup code. Format is similar to C# String.Format method where string "my first value: {0} and second value: {1}" will have {0} and {1} replaced with an array of values, based on an index 0-n. In this case, the array of values are determined by the controls referenced(by Field names) in CascadeValuesBasedOn. In addition to using indexes of related control, you may also use the n. prefix to extract a number from the control's value. Below is an example of how this property is combined with the CascadeValuesBasedOn.

Advanced Example:

We want the ClinStageT values to change based on the user's choice of ClinStageDisease and ClinStageSystem.

On the Clinical Stages form ClinStageT is a CaisisComboBox control, and ClinStageDisease and ClinStageSystem are CaisisSelect(DropDownList).

We now set the related properties.

  • CascadeValuesBasedOn="ClinStageDisease,ClientStageSystem"
  • CascadeFormatString="StageClin_{0}_{n.1}_T"

When we change the values of ClinStageDisease or ClinStageSystem, the lookup code which the ClinStageT ComboBox generates is based on the two observed values. So if we select Prostate for the ClinStageDisease, and select UICC_02 for ClinStageSystem, we will generate a lookupcode "StageClin_Prostate_02_T", since the "Value" of ClinStageDisease is "Prostate" and the "Value" of ClinStageSystem is "UICC_02". We only extract the number for the ClinStageSystem "Value", as our format string said to parse out a number, "{n.1}" from the value at index 1.

NOTES: If the control using these properties is a CaisisSelect, everytime an observed control changes values, it will cause a post back to the server, causing syncing issues with retaining values. The CaisisComboBoxes however do not post back, as values are generated via javascript and are retrieved using Client CallBacks, there is no need to worry about retaining values. If unsure, CaisisComboBoxes always provide the best method to handle dynamic lookup codes. The controls being observed (CascadeValuesBasedOn) can still be any type of control, even a CaisisSelect.

Personal tools