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:

BF - onFormRequest - [scopedHookName]

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

Script Naming: The scoped hook name acts like a Get ( LayoutName ) in FileMaker - it tells your script which page context it's running from.

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

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

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.

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

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.

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 to trigger hooks from buttons