# 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**](/reference/actions-processor/actions_overview/runutilityhook.md) action anywhere that [actions](/reference/actions-processor.md) can run
  * typically used on a button that's intended to save data back to your FileMaker database

Client-side lifecycle named actions such as `onAppLoad` and `onFormLoad` are documented separately. They can start browser workflows and may include `runUtilityHook`, but they are not FileMaker hook scripts.

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

{% content-ref url="/pages/mrv6DkpGdbIHwUm5UiOM" %}
[Script Hooks](/reference/hooksoverview.md)
{% endcontent-ref %}

For client lifecycle named actions, see:

{% content-ref url="/pages/MHTiS34urb6JjeyIRv14" %}
[Lifecycle Hooks](/reference/hooksoverview/lifecycle-hooks.md)
{% endcontent-ref %}

## 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.

{% hint style="info" %}

#### **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.
{% endhint %}


---

# 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.1-introduction-to-hooks-and-where-to-find-them-in-the-ide.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.