3.1 Introduction to Hooks (and where to find them in the IDE)

What is a Hook Script?

A hook script is a script that inserts itself into normal workflow allowing additional control. See: https://en.wikipedia.org/wiki/Hooking. You interact with your application and the web client via hooks scripts.

BetterForms hooks fall into 2 categories:

Common hooks are scripts that are not contextual to a specific page. Typically they can be called from anywhere and do not contain information about the user's current page. (Eg: A login or registration hook are common hooks.) Common hooks are unified by a Site and therefore configured in the site settings.

Scoped hooks are bound to a specific page. Most of the hook scripts you will use throughout BetterForms will be scoped hooks. Scoped hooks are unified by the form and therefore configured in the form editor.

Where to Find Hooks in the BetterForms IDE

Common Hooks

Common hooks are configured at the Site level:

1. Navigate to your App (Site) Settings in the BetterForms IDE

2. Go to the Environment section

3. Look for the Named Actions or Hooks tab

4. Here you can configure site-wide hooks like onLogin, onRegistration, etc.

Scoped Hooks

Scoped hooks are configured at the Page level:

1. Open any Page in the BetterForms IDE

2. Navigate to the Integration tab

3. You'll find options like:

   • Enable onFormRequest Hook - triggers when the page loads

   • Send Full Schema in Utility Hooks - for data control

4. The Scoped Hook Set Name (set in Page Info) determines which FileMaker scripts will handle this page's hooks

When do Hooks run?

A hook script can be triggered in a variety of places, here are just a few of the most common examples:

• onLogin - a common hook used when a user first logs in to the web client

• onFormRequest - a scoped hook that's optionally triggered when a page is first loaded

  • typically used to push data from FileMaker to the user

• using the runUtilityHook action anywhere that actions can run

  • typically used on a button that's intended to save data back to your FileMaker database

For a full reference of all available hooks, see this page:

Script Hooks

How to name Hooks

The next few steps will ask you to create names for both a common hook set and a scoped hook set. Here are few tips to keep in mind:

• The names of hooks are internal to your application and never displayed to the user

• It's best to keep them short but descriptive for easy legibility

• Hook names do not need to be unique throughout your site (see tip below)

• As long as the names match between BetterForms and FileMaker, everything will work just fine.

FileMaker Analogy

A scoped hook name is referenced similarly to Get ( LayoutName ) in FileMaker. When a script is run, the scoped hook name is used to let your server-side script know the context that the user is sitting in.

This allows you to group scripts that run from the context of the same page together in your FileMaker scripts. Since these name don't need to be unique, you can group multiple pages together by having them share the same scoped hook name and your FileMaker scripts will see them as effectively the same page.