arc-humans-interface-db/docs/RETOOL_INLINE_SETUP.md

# Retool Inline Setup Guide - Single File Version

This guide shows you how to use the inline versions that don't require separate JavaScript queries.

## File Overview

1. **arcRender_retool_inline.js** - Main puzzle renderer (training + test input)
2. **arcRender_testOutput_inline.js** - Test output/answer renderer (separate, with toggle)

## Step-by-Step Setup

### Step 1: Create Database Query

1. Add a **SQL Query** component
2. Name it: `arcPuzzleQuery`
3. Query:

```sql
SELECT id, json
FROM your_table_name
WHERE id = {{ selectProblem.value }}
-- Replace with your actual table name
```

### Step 2: Create Problem Selector (Optional)

1. Add a **Select** component
2. Name it: `selectProblem`
3. Set **Data source** to a query:

```sql
SELECT id, id as label FROM your_table_name ORDER BY id
```

4. Set the select to trigger `arcPuzzleQuery` on change

### Step 3: Add Main Puzzle HTML Component

1. Add an **HTML** component
2. Copy the **ENTIRE contents** of `arcRender_retool_inline.js`
3. Paste it wrapped in `{{ ... }}`:

```javascript
{{
  (function() {
    // ... PASTE ENTIRE arcRender_retool_inline.js CONTENT HERE ...
  })()
}}
```

4. **IMPORTANT:** Edit line 13 in the pasted code to match your query name:
```javascript
const queryData = arcPuzzleQuery.data; // Change if your query has different name
```

### Step 4: Add Test Output HTML Component (Optional)

1. Add a **Toggle** or **Checkbox** component
2. Name it: `toggleShowAnswer`

3. Add another **HTML** component (below the main one)
4. Copy the **ENTIRE contents** of `arcRender_testOutput_inline.js`
5. Paste it wrapped in `{{ ... }}`:

```javascript
{{
  (function() {
    // ... PASTE ENTIRE arcRender_testOutput_inline.js CONTENT HERE ...
  })()
}}
```

6. **IMPORTANT:** Edit these lines in the pasted code:
   - Line 15: `const shouldShow = toggleShowAnswer.value;` (your toggle name)
   - Line 25: `const queryData = arcPuzzleQuery.data;` (your query name)

## Quick Copy-Paste Example

### For Main Puzzle Display:

```javascript
{{
  (function() {
    const queryData = arcPuzzleQuery.data; // YOUR QUERY NAME

    if (!queryData || queryData.length === 0) {
      return '<div style="color: orange; padding: 20px; font-family: Arial;">No puzzle data available.</div>';
    }

    const row = queryData[0];
    let puzzleData;
    try {
      puzzleData = typeof row.json === 'string' ? JSON.parse(row.json) : row.json;
    } catch (e) {
      return '<div style="color: red; padding: 20px;">Error: ' + e.message + '</div>';
    }

    // ... rest of the code from arcRender_retool_inline.js ...
  })()
}}
```

## Customization

### Change Query Name
Find this line in the code:
```javascript
const queryData = arcPuzzleQuery.data; // YOUR QUERY NAME HERE
```

Change `arcPuzzleQuery` to your actual query component name.

### Change Column Name
If your JSON column is not named `json`, change this line:
```javascript
puzzleData = typeof row.json === 'string' // Change 'json' to your column name
```

### Change Toggle Name (for test output)
Find this line in the test output code:
```javascript
const shouldShow = toggleShowAnswer.value; // YOUR TOGGLE NAME HERE
```

## Layout Example

```
┌─────────────────────────────────────┐
│  Select: [Problem Dropdown ▼]       │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  HTML Component 1                    │
│  (Main Puzzle - Training + Test)    │
│  {{ arcRender_retool_inline.js }}   │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  [✓] Show Test Answer                │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  HTML Component 2                    │
│  (Test Output - Answer)              │
│  {{ arcRender_testOutput_inline.js }}│
└─────────────────────────────────────┘
```

## Troubleshooting

### "queryData is not defined"
- Make sure your query is named correctly
- Check that the query has run successfully
- Verify with `{{ arcPuzzleQuery.data }}` in a text component

### "Cannot read property 'json' of undefined"
- Query returned no data
- Check your WHERE clause and selected value
- Test query manually in SQL editor

### JSON parsing error
- Check if your json column is text or already an object
- Try logging: `{{ typeof arcPuzzleQuery.data[0].json }}`
- Adjust the parsing logic accordingly

### Nothing displays
- Check browser console (F12) for errors
- Make sure HTML component has sufficient height
- Try a simple test first: `{{ "test" }}`

### Grids look wrong
- Make sure the JSON structure is correct
- Check that it has `train` and `test` properties
- Verify with: `{{ JSON.stringify(arcPuzzleQuery.data[0]) }}`

## Advantages of Inline Version

✅ **Single component** - No separate JavaScript query needed
✅ **Self-contained** - All code in one place
✅ **Easy to customize** - Just edit the HTML component
✅ **No dependencies** - Works immediately after paste

## Performance Note

The inline version recalculates on every Retool state change. For better performance with many components on the page, consider using the separate JavaScript query version ([arcRender_retool.js](arcRender_retool.js)) instead.