isSelected

The isSelected() method is used within the VCC Live script interface to determine whether a specific field, such as a checkbox or a radio button, is currently checked (selected) or populated by the agent. It is often used in validation logic, dynamic interface updates (like showing/hiding other fields), or branching decision trees based on what an agent has ticked.

Description

vcc.isSelected(field: string, [value: string], [key: string]): bool

Parameters

field
The name of the field.

value
The value you want to look for.

key
The name of the value property (DEFAULT: valueid).

Return values

bool

If the value parameter is missing, it returns true if:

• text field – the field is not empty
• simple field – there is a selected value
• multiple field – there are selected values

If the value parameter exists, it returns true if:

• text field – the value of the field is the same as the given value (the 3rd parameter is unused in this case)
• simple field – there is a selected element and its property defined by the key is the same as the given value.
• multiple field – there are selected values whose properties defined by the key are the same as the given value.

Use cases with explanation

Use case 1. Validating a mandatory consent checkbox

Frequently, scripts require agents to read a mandatory compliance statement and check a box reflecting the customer’s consent before proceeding to the next page. You can use vcc.isSelected() in the beforeValidation hook to enforce this.

$('page').onLoad = function() {
// Assume 'chk_customer_consent' is the checkbox ID
 if (!vcc.isSelected("chk_customer_consent")) {
    alert("You must obtain and register the customer's consent before proceeding.");
   }
};

Use case 2. Dynamically showing/hiding additional input fields

You can bind an event handler to a checkbox so that when an agent selects it, a set of extra address fields becomes visible. To show or hide a field, modify its hidden property using vcc.getController().

$("order_details", "chk_different_shipping").afterSetData = function() {
    // Check if the 'Different Shipping Address' checkbox is selected
    if (vcc.isSelected("order_details", "chk_different_shipping")) {
        // Show the shipping address text fields by setting hidden to false
        vcc.getController("order_details", "txt_shipping_city").hidden = false;
        vcc.getController("order_details", "txt_shipping_street").hidden = false;
    } else {
        // Hide the shipping address text fields by setting hidden to true
        vcc.getController("order_details", "txt_shipping_city").hidden = true;
        vcc.getController("order_details", "txt_shipping_street").hidden = true;
        
        // Optionally clear their values when hidden
        vcc.setFieldValue("txt_shipping_city", "");
        vcc.setFieldValue("txt_shipping_street", "");
    }
};

Use case 3. Calculating preliminary quotes based on selected add-ons

When agents are upselling services with multiple add-on options (represented by checkboxes), vcc.isSelected() can be used to dynamically calculate the total price as checkboxes are ticked.

// Function wrapper to recalculate total
function recalculateTotal() {
    var basePrice = 50; 
    var addOnPrice = 0;

    // Check if the 'Premium Support' add-on checkbox is selected
    if (vcc.isSelected("chk_premium_support")) {
        addOnPrice += 15;
    }

    // Check if the 'Extended Warranty' add-on checkbox is selected
    if (vcc.isSelected("chk_extended_warranty")) {
        addOnPrice += 25;
    }

    var totalPrice = basePrice + addOnPrice;
    
    // Update a read-only field with the new total
    vcc.setFieldValue("txt_total_price", "$" + totalPrice);
}

// Bind the recalculation function to the afterSetData event of both checkboxes
$("sales_tab", "chk_premium_support").afterSetData = recalculateTotal;
$("sales_tab", "chk_extended_warranty").afterSetData = recalculateTotal;

Notes

• vcc.isSelected() evaluates the live, current state of the DOM element on the screen.
• This method is intended for binary selection inputs like checkboxes and radio buttons, but it can also be used for text fields
• Combining vcc.isSelected() with vcc.getController('field').hidden is a powerful way to build reactive, clutter-free agent scripts by progressively revealing form fields only when needed.