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:

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:

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 {{ ... }}:

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

4. IMPORTANT: Edit line 13 in the pasted code to match your query name:

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 {{ ... }}:

{{
  (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:

{{
  (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:

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:

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:

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) instead.