> ## 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.

# Lookup Shared Table

> Guide to implementing lookup widgets that access Excel file data with advanced filtering and data organization

## 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

<CardGroup cols={2}>
  <Card title="Uploading a Shared Table" icon="upload">
    [Watch Tutorial](https://www.loom.com/share/77f42f030b9f462aa6dc8660bd1ecf37)
    Learn how to upload Excel files as shared tables in the calculator builder
  </Card>

  <Card title="Shared Table Example" icon="table">
    [Watch Tutorial](https://www.loom.com/share/5e5d0dc33d5b48d6b08ffe1f6c6163b4)
    See a complete example of shared table implementation
  </Card>
</CardGroup>

## Visual Presentation

<Info>
  The shared table dropdown interface allows users to select from data imported from Excel files.
</Info>

## Configuration

### Example Code

```json theme={null}
{
  "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

<ResponseField name="type" type="string" required>
  Set to "lookup" to define the widget type
</ResponseField>

<ResponseField name="enableAutosize" type="boolean" default="true">
  Whether or not to enable the autosize function on the lookup. Will only work if the table has preferred sections possible
</ResponseField>

<ResponseField name="sharedTableId" type="string" required>
  The name of the sharedTable to load for the lookup widget
</ResponseField>

<ResponseField name="selector" type="object">
  [Selector Object](https://github.com/ClearCalcs/dev-environment/wiki/Selector-Object) - Data to be displayed/checked in the member selector
</ResponseField>

## Important Considerations

### Excel File Format Requirements

<Warning>
  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.
</Warning>

### 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:

```javascript theme={null}
// 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 ID      | Calculator Link                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| lookup (concrete) | [Steel Beam Calculator](https://calcs.com/organisation/2ad7e5c6-8d23-416d-acb1-5487dc65150a/templates/6d7fc7ed-f6f7-4392-822b-cdee58bab93b) |

## Development Workflow

### JSON File Management

<Info>
  After finishing and reviewing the shared table and calculator:

  1. Upload the JSON file generated from the table (when uploaded to Calcs.com website)
  2. Save it to the `sharedTables` folder within the Calcs.com folder on your computer
  3. This ensures tests load correctly in Buildkite before submitting your PR
</Info>

## 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