Controlref

Purpose

Includes the definition of one type of component in the definition of another component. A Controlref appears only as the child of a component in which it is included; it is not submitted as a stand-alone component.

Types of components in which you can include Controlrefs:

CheckBoxControl
GroupControl
Item
RadioControl
Path

Types of components you can include by using Controlrefs:

CalculatedControl
CheckBoxControl
DateTimeControl
GroupControl
PullDownControl
RadioControl
SimpleControl
TextControl

Syntax

Attributes

REFNAME="name"

RefName of the component that the Controlref is including in the definition of a compound control. Required.

ORDER="n"

Sequence in which each Controlref appears in the compound control definition. Optional. If you do not specify an order, the MedML Installer utility orders the components referred to by the Controlrefs in the order in which you enter them.

SELECTIONVALUE="text"

Value of the compound control included by the Controlref. Optional. If you do not specify a value, when a user selects one of the controls in the compound control, the value stored in the database is a string consisting of the characters !pf! and the DBUID path of the selected control. For example, this attribute is useful for providing a value to store for a checkbox or radio control component labeled Other that is associated with a text box control.

Note: When defining compound controls with Controlref or Unitref definitions, ensure that all subordinate controls return the same data type, by defining them with the same TYPE attribute.

When defining compound controls, note that the InForm application supports a maximum of five levels of nesting. Although five levels are supported, as a design practice, you should attempt to minimize the number of nested levels to help performance.

When including a Controlref definition in a Path element, only the REFNAME attribute is valid.

Examples

This example illustrates how to create a list of radio buttons in which the first button is a drop-down list and the second is a text box. The definition of the radio button list includes the definition of each list item as a Controlref. This list will be used to capture a medication regimen.

Define the drop-down list as a set of PFElements, and include them in a PullDownControl definition by using Elementrefs.
<PFELEMENT REFNAME="QD" LABEL="QD" TYPE="STRING" VALUE="QD"/>
<PFELEMENT REFNAME="BID" LABEL="BID" TYPE="STRING" VALUE="BID"/>
<PFELEMENT REFNAME="TID" LABEL="TID" TYPE="STRING" VALUE="TID"/>
<PFELEMENT REFNAME="QID" LABEL="QID" TYPE="STRING" VALUE="QID"/> <PULLDOWNCONTROL REFNAME="MEDREGIMEN"
    NAME="MEDREGIMEN">
    <ELEMENTREF REFNAME="QD" ORDER="1"/>
    <ELEMENTREF REFNAME="BID" ORDER="2"/>
    <ELEMENTREF REFNAME="TID" ORDER="3"/>
    <ELEMENTREF REFNAME="QID" ORDER="4"/>
</PULLDOWNCONTROL>
Define the text box and its caption as a TextControl.
<TEXTCONTROL REFNAME="MEDREGTEXT"
    NAME="MEDREGTEXT"
    HEIGHT="1"
    LENGTH="20"
    MAXLENGTH="20"
    DATATYPE="STRING"
    CAPTION="Other (specify): "
    CAPTIONALIGN="TOP"/>
Include the pull-down control and text control in a RadioControl by using Controlrefs. Note the use of the SELECTIONVALUE attribute to assign the value "OTHER" to the Other (Specify): radio button.
<RADIOCONTROL REFNAME="MEDREGGROUP"
    NAME="MEDREGRADIO" LAYOUT="VERTICAL">
    <CONTROLREF REFNAME="MEDREGIMEN" ORDER="1"/>
    <CONTROLREF REFNAME="MEDREGTEXT" ORDER="2"
        SELECTIONVALUE="OTHER"/>
</RADIOCONTROL>

This example illustrates the use of Controlref definitions in the Path element to identify the source control used in creating a mapping of components between the InForm database and a CDD.

</EXTERNALMAP>