# 3.2 Running Your First Hook (Practical Example)

Now that you understand the basics of hooks from the previous section, let's create your first hook in BetterForms. This guide will walk you through the practical process of setting up and running a simple hook.

## What You'll Accomplish

In this practical example, you'll:

* Enable the `onFormRequest` hook for a page
* Locate and modify the corresponding FileMaker script
* Push data from FileMaker to your browser
* Learn basic troubleshooting techniques

## Step-by-Step: Creating Your First Hook

### Step 1: Enable the onFormRequest Hook

The `onFormRequest` hook is triggered when a page is first loaded, making it perfect for your first hook example.

1. **Navigate to the Integration Tab:**
   * In the BetterForms IDE, open the page you want to add a hook to
   * Go to the **Integration** tab
2. **Enable the onFormRequest Hook:**
   * Find the **Enable onFormRequest Hook** option and toggle it **ON**
   * This will trigger the `onFormRequest` hook script when the page is first loaded

### Step 2: Locate the FileMaker Script

From the scripts you pasted into your FileMaker file (during helper file setup), locate the one called:

`Klai - onFormRequest - [scopedHookName]`

Where `[scopedHookName]` is the name of the scoped hook you defined in your page settings.

{% hint style="info" %}
**Script Naming:** The scoped hook name acts like a `Get ( LayoutName )` in FileMaker - it tells your script which page context it's running from.
{% endhint %}

### Step 3: Modify the FileMaker Script

You can do anything you want in this script, but for this example, the goal is to push data back to the browser. This is accomplished by setting the `$$BF_Model` global variable to a JSON object containing the data.

**Example Script Code:** Set the variable to something like this (make it different from your page's default data model so you can verify the hook is working):

```javascript
JSONSetElement ( $$BF_Model ; 
    [ "nameFirst" ; "Jim" ; JSONString ];
    [ "nameLast" ; "Bob" ; JSONString ]
)
```

{% hint style="info" %}
**Best Practice:** Notice how we are only **modifying** the `$$BF_Model` JSON instead of replacing it. This is good practice because otherwise you could accidentally erase existing data from the user's browser.
{% endhint %}

### Step 4: Test Your Hook

1. **Save the FileMaker script**
2. **Save your page settings** in the BetterForms IDE
3. **Refresh your preview tab** (or launch it again)

**Expected Result:** If everything is properly connected, you should see the data set from your FileMaker script on the page instead of the default data model.

## Troubleshooting Your First Hook

Even if you succeed, review these troubleshooting tips for when things don't go as planned:

### Check the Helper File Inbox

Every hook that interacts with your FileMaker server goes through the Helper file, making it the best place to start debugging.

1. **Open the Helper file** and click the **Inbox** tab
2. **Check for records:** The left side shows incoming data; the right side shows outgoing data
3. **Look at timestamps** to find your most recent hook call

**Common Scenarios:**

| **If this happens...**                        | **Then try this...**                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
| **No record appears in inbox**                | Hook never reached FileMaker - check if onFormRequest is enabled, verify credentials |
| **Record exists but unexpected results**      | Check the outbox payload (right side) - data model returned to browser               |
| **Works locally but not through BetterForms** | Check user privileges - BetterForms user vs. your admin credentials                  |

### Check Extended Privileges

Invalid credentials or misconfigured extended privileges is the most common cause of integration problems.

**Verify your BetterForms user has:**

* **XML** extended privileges enabled
* **Data API** extended privileges enabled
* Credentials match what was configured in your site settings

{% hint style="warning" %}
**Credential Security:** BetterForms encrypts credentials so you can't view them from the IDE. You'll need to re-enter them to verify they're correct.
{% endhint %}

### Debug Using Helper File Tools

1. **Clear the inbox** (delete all records) to start fresh
2. **Refresh your preview** to generate a new hook call
3. **Use the "Run Hook" button** in the Helper file to test locally
4. **Compare local vs. remote results** to identify privilege issues

## Next Steps

Congratulations! You've successfully run your first hook. This foundation will serve you throughout your BetterForms development.

**What to explore next:**

* Try the `runUtilityHook` action (typically used with save buttons)
* Experiment with different data in `$$BF_Model`
* Learn about [BetterForms Actions](/getting-started/ide-quick-tour/3.-understanding-core-betterforms-concepts/3.3-introduction-to-actions-and-action-scripts-ide-context.md) to trigger hooks from buttons


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.klai.studio/getting-started/ide-quick-tour/3.-understanding-core-betterforms-concepts/3.2-running-your-first-hook-practical-example.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.