> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget FAQs

> Frequently asked questions about implementing and configuring widgets in Calcs.com templates

This page contains frequently asked questions and common issues encountered when working with widgets in the Calcs.com template builder.

## General Widget Questions

<AccordionGroup>
  <Accordion title="Can a computed result include both text and numbers?">
    The computed portion of the calculator doesn't support mixed data types in a single result. However, you can work around this limitation using a two-widget approach:

    1. **Primary Equation Widget**: Performs the numerical calculation
    2. **Secondary Text Widget**: Combines the computation output with text using the `print()` function

    The secondary widget can be toggled to be invisible using the `visibleIf` property with conditional statements.

    **Example Implementation:**

    ```json theme={null}
    // Primary computation widget
    {
      "type": "computed",
      "referenceId": "beam_capacity",
      "equation": [
        {
          "condition": "@default",
          "result": "@moment_strength * @safety_factor"
        }
      ],
      "hidden": true
    }

    // Secondary text display widget
    {
      "type": "computed", 
      "referenceId": "capacity_display",
      "equation": [
        {
          "condition": "@default",
          "result": "print('Beam capacity: ', @beam_capacity, ' kN·m')"
        }
      ],
      "visibleIf": "@beam_capacity > 0"
    }
    ```
  </Accordion>

  <Accordion title="How do I reference data from lookup widgets?">
    The method depends on the type of lookup widget:

    **Data Table Lookups:**

    ```javascript theme={null}
    // Get selected row index
    selectedIndex = @my_lookup

    // Access specific column data
    columnValue = dataTableValue(@my_lookup, selectedIndex, columnIndex)
    ```

    **Shared Table Lookups:**

    ```javascript theme={null}
    // Direct column access using column reference ID
    columnValue = @my_lookup.columnReferenceId
    ```

    **Toggle Lookups:**

    ```javascript theme={null}
    // Toggle returns 0 or 1
    isEnabled = (@my_toggle == 1)
    ```
  </Accordion>

  <Accordion title="What's the difference between 'hidden' and 'visibleIf' properties?">
    These properties control widget visibility in different ways:

    **`hidden` Property:**

    * Static visibility control set at design time
    * When `true`, widget is never shown to users
    * Value can still be set in presets and referenced by other widgets
    * Useful for intermediate calculations or data storage

    **`visibleIf` Property:**

    * Dynamic visibility control based on conditions
    * Evaluated in real-time based on other widget values
    * When condition is `false`, widget is hidden and cannot be referenced
    * Useful for conditional user interface flows

    ```json theme={null}
    // Static hidden widget
    {
      "hidden": true,
      "referenceId": "internal_calc"
    }

    // Conditionally visible widget  
    {
      "visibleIf": "@load_type == 1",
      "referenceId": "wind_load_factor"
    }
    ```
  </Accordion>

  <Accordion title="How do I create multi-step calculations?">
    Break complex calculations into multiple equation widgets:

    1. **Intermediate calculations** can be hidden from users
    2. **Final results** can reference intermediate steps
    3. **Display widgets** can format and present results

    ```json theme={null}
    // Step 1: Hidden intermediate calculation
    {
      "type": "computed",
      "referenceId": "moment_demand", 
      "hidden": true,
      "equation": [{"condition": "@default", "result": "@load * @span^2 / 8"}]
    }

    // Step 2: Hidden intermediate calculation  
    {
      "type": "computed",
      "referenceId": "moment_capacity",
      "hidden": true, 
      "equation": [{"condition": "@default", "result": "@section_modulus * @yield_stress"}]
    }

    // Step 3: Final visible result
    {
      "type": "computed",
      "referenceId": "utilization_ratio",
      "equation": [{"condition": "@default", "result": "@moment_demand / @moment_capacity"}]
    }
    ```
  </Accordion>

  <Accordion title="How do I handle units in calculations?">
    Calcs.com has built-in unit handling:

    * **Input widgets** automatically handle unit conversion
    * **Equation widgets** inherit units from inputs
    * **Unit-aware functions** maintain dimensional consistency

    **Best Practices:**

    * Define units in input widget `unit` property
    * Use consistent base units throughout calculations
    * Let the system handle conversions automatically
    * Check the "What's NOT unit-aware" documentation for exceptions
  </Accordion>

  <Accordion title="Can I create custom validation rules?">
    Yes, using the `check` functionality in equation widgets:

    ```json theme={null}
    {
      "type": "computed",
      "referenceId": "beam_check",
      "equation": [
        {
          "condition": "@utilization_ratio <= 1.0",
          "result": "PASS"
        },
        {
          "condition": "@default", 
          "result": "FAIL"
        }
      ],
      "check": {
        "condition": "@utilization_ratio <= 1.0",
        "pass": "Beam capacity is adequate",
        "fail": "Beam is overstressed - increase section size"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Widget-Specific Questions

<AccordionGroup>
  <Accordion title="When should I use a Data Table vs Shared Table lookup?">
    **Use Data Table when:**

    * Data is simple and can be defined in the builder
    * Limited number of options (typically \< 50 rows)
    * Data doesn't change frequently
    * No external data source maintenance required

    **Use Shared Table when:**

    * Data is complex or extensive (> 50 rows)
    * Data is maintained in Excel externally
    * Multiple templates need the same data
    * Advanced filtering capabilities are needed
    * Data includes multiple related columns
  </Accordion>

  <Accordion title="How do I create dependent dropdowns?">
    Use the `visibleIf` property and data filtering:

    ```json theme={null}
    // Primary lookup
    {
      "type": "lookup",
      "referenceId": "material_type",
      "dataTable": [["Steel"], ["Concrete"], ["Timber"]]
    }

    // Dependent lookup - only visible for steel
    {
      "type": "lookup", 
      "referenceId": "steel_grade",
      "visibleIf": "@material_type == 0",
      "dataTable": [["Grade 300"], ["Grade 350"], ["Grade 400"]]
    }
    ```
  </Accordion>

  <Accordion title="How do I handle dynamic widget arrays?">
    For dynamic numbers of similar widgets, consider:

    1. **Subsheet Widgets** for complex linked calculations
    2. **Table Widgets** for simple data entry arrays
    3. **Loop-based equation widgets** for calculations over arrays

    See the Subsheet Widget documentation for advanced scenarios.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="My widget references aren't working">
    Common issues and solutions:

    **Check Reference IDs:**

    * Ensure `referenceId` is unique across the template
    * Verify spelling in widget references (case-sensitive)
    * Use valid JavaScript identifier format (no spaces, special chars)

    **Check Visibility:**

    * If `visibleIf` is false, widget cannot be referenced
    * Ensure referenced widgets exist and are visible

    **Check Data Types:**

    * Ensure data types match expected input types
    * Verify lookup indices are within valid range
  </Accordion>

  <Accordion title="Circular reference errors">
    **Causes:**

    * Widget A references Widget B, and Widget B references Widget A
    * Subsheet commonInputs that depend on derived data

    **Solutions:**

    * Identify the dependency chain
    * Break circular dependencies with intermediate widgets
    * Use hidden widgets for one-way data flow
    * Review subsheet commonInput configurations
  </Accordion>

  <Accordion title="Performance issues with large datasets">
    **Optimization strategies:**

    * Use Shared Tables instead of large Data Tables
    * Implement data filtering to reduce displayed options
    * Consider breaking large calculations into smaller steps
    * Use `hidden: true` for intermediate calculations
    * Minimize complex `visibleIf` conditions on frequently updated widgets
  </Accordion>
</AccordionGroup>

## Getting Help

If you encounter issues not covered in this FAQ:

1. **Check the specific widget documentation** for detailed configuration options
2. **Review existing templates** with similar functionality
3. **Test in isolation** by creating a minimal example
4. **Contact the development team** with specific error messages and widget configurations

<Info>
  This FAQ is regularly updated based on common questions from template developers. If you have suggestions for additional topics, please reach out to the development team.
</Info>