Skip to main content

​
Widget Core Function

UI Experience: Dropdown list for the user
Data Organization: Allows engineers to import Excel sheets into the calculator builder, providing access to complex external datasets.

​
Key Features

  • Import Excel sheets directly into the calculator builder
  • Store and access the row index of selected items
  • Access entire rows of data once a user makes a selection
  • Advanced filtering capabilities with custom filter functions
  • Support for large, complex datasets

​
Video Tutorials

Uploading a Shared Table

Watch Tutorial Learn how to upload Excel files as shared tables in the calculator builder

Shared Table Example

Watch Tutorial See a complete example of shared table implementation

​
Visual Presentation

Shared table dropdown interface

​
Configuration

​
Example Code

{
  "type": "sheetTemplateWidgets",
  "attributes": {
    "type": "lookup",
    "label": "Material Selection",
    "symbol": "mat",
    "defaultValue": "0",
    "visibleIf": "",
    "enableAutosize": true,
    "sharedTableId": "steel_sections",
    "selector": {},
    "referenceId": "material_lookup",
    "references": "AS 4100",
    "description": "Select steel section from shared table",
    "authorNotes": "",
    "referenceImage": ""
  }
}

​
Configuration Parameters

​
type
string
required
Set to “lookup” to define the widget type
​
enableAutosize
boolean
default:"true"
Whether or not to enable the autosize function on the lookup. Will only work if the table has preferred sections possible
​
sharedTableId
string
required
The name of the sharedTable to load for the lookup widget
​
selector
object
Selector Object - Data to be displayed/checked in the member selector

​
Important Considerations

​
Excel File Format Requirements

You CAN’T upload ANY Excel file in the Calculator Builder. It needs to be in a specific format. Refer to previously created Excel files for the correct format.

​
Default Values

The “default value” for lookup tables are the “row index” of the cell location (starting from 0).

​
Data Filtering

When implementing filtering in the “Lookup Data Filter Function”, consider the following: The result of the f(row) = function MUST be a boolean in the dataFilter equation. Think of the syntax with parentheses: f(row) = (row[n] == "Cell Value").

​
Key Points:

  1. Single Function Definition: You can’t and multiple f(row) function definitions. It must be a single function definition.
  2. Row-by-Row Processing: The function runs on one row at a time, so the logic must reflect that fact. One row cannot equal “Cell 1” AND “Cell 2” simultaneously. You want an or there.
  3. Array Column Limitation: Columns that include arrays cannot be considered in dataFilter functions.

​
Correct Filter Examples:

// Multiple value matching
f(row) = (row[n] == "Cell 1" || row[n] == "Cell 2")

// Using isIncluded function
f(row) = isIncluded(row[n], ["Cell 1", "Cell 2"])

​
Examples from Current Calculators

Reference IDCalculator Link
lookup (concrete)Steel Beam Calculator

​
Development Workflow

​
JSON File Management

After finishing and reviewing the shared table and calculator:
  1. Upload the JSON file generated from the table (when uploaded to ClearCalcs website)
  2. Save it to the sharedTables folder within the ClearCalcs folder on your computer
  3. This ensures tests load correctly in Buildkite before submitting your PR

​
Best Practices

  1. Excel Format: Always follow established Excel formatting conventions from previous shared tables
  2. Testing: Test filtering functions thoroughly with various data combinations
  3. Performance: Consider the size of your shared table and its impact on load times
  4. Documentation: Include clear author notes explaining the data structure and any special filtering logic
  5. Version Control: Always include the JSON file in your repository for CI/CD compatibility
⌘I