Checkbox Widget

The Checkbox widget allows users to select one or multiple options from a predefined list. It provides flexible data sourcing options and comprehensive validation capabilities.

Overview#Direct link to Overview

The checkbox widget renders as a group of checkboxes that users can interact with to make selections. It supports various data sources including static lists, database collections, reports, and external databases.

Basic Configuration#Direct link to Basic Configuration

Global Settings#Direct link to Global Settings

Name: The display label for the checkbox group Variable/Model: The data model variable that will store the selected values Default Value: Pre-selected options when the widget loads

Data Source Configuration#Direct link to Data Source Configuration

The checkbox widget supports multiple data source types:

Static Data#Direct link to Static Data

• Custom List: Select from predefined static lists
• Configure label and value properties for each option

Collection Data#Direct link to Collection Data

• Collection: Connect to database collections
• Query: Filter and customize data retrieval
• Aggregation: Use advanced aggregation queries for complex data processing
• Sort By: Define sorting field and direction (1 for ascending, -1 for descending)
• Limit: Restrict the number of options displayed

Report Data#Direct link to Report Data

• Report: Connect to existing reports
• Query: Apply filters to report data
• Aggregation: Use aggregation pipelines on report data

External Database (EDS)#Direct link to External Database (EDS)

• Database: Connect to external database connections
• EDS Source: Define SQL queries or database-specific operations

Variable Data#Direct link to Variable Data

• Use existing interface variables as data source
• Automatically binds to {model}_vb variable

Properties Configuration#Direct link to Properties Configuration

Label Property: Define which field contains the display text

• Static use: firstName
• Dynamic use: $.firstName + ' - ' + $.lastName

Value Property: Define which field contains the stored value

• Static use: ref
• Dynamic use: $.ref + ' - ' + $.name

Validation & Rules#Direct link to Validation & Rules

Screen-Based Validation#Direct link to Screen-Based Validation

Configure widget behavior across different screens:

Available: Control widget availability per screen

Visible: Show/hide widget conditionally

Required: Make selections mandatory

Disabled: Prevent user interaction

Advanced conditions can be set using variables with {{variable_name}} syntax.

Validation Rules#Direct link to Validation Rules

Add custom validation rules:

• Required: Ensure at least one option is selected
• Min/Max Selection: Control selection count (for multiple selection)
• Custom Rules: Define specific validation logic
• Error Messages: Customize validation feedback

Style Configuration#Direct link to Style Configuration

Layout Options#Direct link to Layout Options

• Layout: Choose between Block or Inline display
• Border: Add borders around checkbox options
• Width: Set widget width (e.g., "100%", "300px")

CSS Customization#Direct link to CSS Customization

• Class Names: Add custom CSS classes
• Dynamic Classes: Use conditional styling based on data

Events#Direct link to Events

The checkbox widget supports several events:

onChange#Direct link to onChange

Triggered when checkbox selection changes

// Access selected values and data
SF_input.value; // Selected values array
SF_input.SF_data; // Selected objects array
SF_input.SF_currentIndex; // Current loop index

onClick#Direct link to onClick

Custom click handler with access to:

• Selected values
• Complete data objects
• Current context information

Working with Actions and SF_input#Direct link to Working with Actions and SF_input

Attaching Actions to onChange Event#Direct link to Attaching Actions to onChange Event

The checkbox widget's onChange event allows you to execute custom Actions whenever the user changes their selection. This is particularly useful for:

• Filling related fields with data from selected options
• Triggering cascading updates in other form fields
• Fetching additional data from the backoffice based on selection
• Implementing conditional logic based on selected values

How to Attach an Action#Direct link to How to Attach an Action

1. Navigate to the Global section in the checkbox widget configuration
2. Find the On Change event field (or On Click depending on your interface version)
3. Write plain JavaScript directly in the action field
4. Your code executes automatically when the selection changes

Accessing Values with SF_input#Direct link to Accessing Values with SF_input

The checkbox widget provides rich data access through the SF_input object. Unlike simple input fields, checkboxes can return both the selected values and the complete data objects from your data source.

SF_input Structure for Checkbox Widget#Direct link to SF_input Structure for Checkbox Widget

{
  value: [/* Array of selected values */],
  SF_data: [/* Array of complete selected objects */],
  SF_currentIndex: /* Loop index if widget is inside a loop */
}

Understanding SF_input Properties#Direct link to Understanding SF_input Properties

Practical Examples#Direct link to Practical Examples

Example 1: Access Selected Values#Direct link to Example 1: Access Selected Values

// Get the array of selected values
console.log(SF_input.value);
// Output: ['value1', 'value2', 'value3']

// Check how many items are selected
const selectionCount = SF_input.value.length;

// Check if a specific value is selected
const isSelected = SF_input.value.includes('value1');

Example 2: Access Complete JSON Objects (SF_data)#Direct link to Example 2: Access Complete JSON Objects (SF_data)

This is the most powerful feature - accessing the full data objects, not just the values:

// Access the complete data objects for selected items
console.log(SF_input.SF_data);
// Output: [
//   { id: '001', name: 'Product A', price: 100, category: 'Electronics' },
//   { id: '002', name: 'Product B', price: 200, category: 'Clothing' }
// ]

// Extract specific properties from selected items
const selectedNames = SF_input.SF_data.map(item => item.name);
const totalPrice = SF_input.SF_data.reduce((sum, item) => sum + item.price, 0);

// Use the first selected item's data
if (SF_input.SF_data.length > 0) {
  const firstItem = SF_input.SF_data[0];
  model.selected_category = firstItem.category;
  model.selected_supplier = firstItem.supplier;
}

Best Practices#Direct link to Best Practices

1. Always Check SF_data Length: Before accessing SF_data, verify it's not empty

   if (SF_input.SF_data && SF_input.SF_data.length > 0) {
     // Your code here
   }
   

2. Use SF_data for Rich Information: When you need more than just the value, always use SF_data to access the complete object

3. Handle Multiple Selections: Remember that checkbox returns arrays, so use array methods appropriately

4. Validate Data Existence: Check if properties exist before accessing nested data

   const supplierName = SF_input.SF_data[0]?.supplier?.name || 'Unknown';
   

5. Performance Considerations: For large datasets or complex operations, consider debouncing your onChange actions

6. Clear Documentation: Comment your action code to explain the business logic for future maintenance

Configuration Examples#Direct link to Configuration Examples

Basic Static Checkbox#Direct link to Basic Static Checkbox

Collection-Based Checkbox#Direct link to Collection-Based Checkbox

Advanced Features#Direct link to Advanced Features

Query Customization#Direct link to Query Customization

For collection and report data sources, you can define custom queries:

Aggregation Queries#Direct link to Aggregation Queries

Enable aggregation for complex data operations:

Conditional Visibility#Direct link to Conditional Visibility

Set advanced visibility conditions:

Best Practices#Direct link to Best Practices

1. Data Source Selection: Choose the appropriate data source type based on your needs
2. Performance: Use limits and efficient queries for large datasets
3. User Experience: Provide clear labels and meaningful validation messages
4. Responsive Design: Consider mobile layouts when choosing inline vs block display
5. Accessibility: Ensure proper labeling for screen readers

Troubleshooting#Direct link to Troubleshooting

Empty Options: Verify data source configuration and query syntax

Selection Not Saving: Check model variable name and validation rules

Performance Issues: Implement pagination or filtering for large datasets

Styling Issues: Verify CSS class names and responsive design settings