XIN Rules

HOME > SETUP > DEVELOPER'S INSTRUMENT GUIDE > HOW TO CODE AN INSTRUMENT > XIN RULES

#What are XIN Rules? XIN Rules validate your input and prevent you from moving forward if you forget to fill in a required field. They can be used to enforce dependencies between fields.

i.e. If A1 is selected in question A and if A2 is selected in question B, then give examiner a break and skip question 3 and 4.

For example:

A. Do you smoke? (Options:) A1: Yes A2: No

> B: How often do you smoke? #Skip question B if A2 "No" response was given for question A

##How to use XIN Rules All elements are required if no rule is specified, unless it is part of a group.

$this->XINRegisterRule(
    "field_name1",
    array("field_name2{@}=={@}yes|maybe|sure"),
    "Required." 
);

$this->XINRegisterRule(
    "field_name", // field name on which the rule is applied
    array("field_name{@}=={@}"), // rule
    "Required.", // message
    "group_1" // group [if field is a part of a group]
);

NOTE: When adding XIN rules some elements are implicitly added to a group in NDB_BVL_Instrument.class.inc. In consequence, a group name needs to be specified when registering a rule. A group name is necessary for the following elements:

$this->addHourMinElement();  // Group name: {$fieldName}_group
$this->addTextElement();  // Group name: {$fieldName}_group
$this->addNumericElement();  // Group name:{$fieldName}_group
$this->addDateElement();  // Group name: {$fieldName}_dategroup

Field is never required

$this->XINRegisterRule(
    "field_name",
    array("field_name{@}=={@}NEVER_REQUIRED"),
    "Not required",
    "group1" 
);

Field is required based on value of another field (check for equality)

$this->XINRegisterRule(
    "field_name1",
    array("field_name2{@}=={@}yes"),
    "Required." 
);

Field is required based on value of another field (check for equality with multiple valid values)

$this->XINRegisterRule(
    "field_name1",
    array("field_name2{@}=={@}yes|maybe|sure"),
    "Required." 
);

Multiple rules applied in AND fashion

$this->XINRegisterRule(
    "field_name3",
    array("field_name1{@}=={@}yes", "field_name2{@}=={@}no"), // Use , (comma) to "AND" the rules
    "Required." 
);

Multiple rules applied in OR fashion

$this->XINRegisterRule(
    "field_name3",
    array("field_name1{@}=={@}yes|field_name2{@}=={@}yes"), // Use | (pipe) to "OR" the rules
    "Required.",
    "group1" 
);

Validating multi-selects

Currently, multi-selects do not work well within XINRules. To validate that a multi-select has been filled, an additional validation function is a best practice, to ensure that an informative error message is displayed for the user, if the multi-select fails validation and the form is not saved.

    function _page1() {
        ...
        $this->addSelect(
            "multiselect_ex",
            "Multi-Select Example",
            $options,
            ["multiple"]
        );
        ...
        $this->form->addFormRule(array(&$this,'validateMultiSelects'));
    }

    function validateMultiSelects($values)
    {
        $errors = array();

        if(empty($values['multiselect_ex'])){
            $errors['multiselect_ex'] = "Required.";
        }
        
        return $errors;
    }

For more on validation functions, see (validation function section under construction)