Named Actions (Action Scripts)

Named actions are reusable action arrays. They are the closest BetterForms equivalent to a FileMaker script name plus script steps.

Defining Named Actions

• formSchema.form.namedActions are scoped to the current page. In the IDE, define these in the Scripts tab for the page.
• site.content.namedActions are globally scoped and can be called from anywhere in the app.

Execution

Named actions can be executed from several contexts.

Context	Syntax eg
[actions array]	"xxx_actions" : [ { your namedActions} ]	A named action is just an action that calls other named Action scripts.
HTML	<button @click="namedAction('saveData',{person: model.person})"> ... </button>	Calling from from HTML you can use the method namedAction
JavaScript	BF.namedAction('saveData',{person: model.person})	When calling from JS, use the Klai functions library.

Lookup Order

When BetterForms processes a namedAction, it resolves the name in this order:

1. the active page/window form.namedActions
2. site.content.namedActions
3. registered component-scoped named actions
4. legacy processNamedAction event-bus listeners, if no named action was found

This means page-level named actions override app-level ones of the same name.

Schema

Named actions look like any other actions array, with just the name of the action as the key. They can either be a single action like the showCantDoThat example, or an array of actions like goToMyAccount.

"namedActions": {
    "showCantDoThat": {
        "action": "showAlert",
        "options": {
            "title": "Whoooaa!!",
            "text": "You can't do that thing you just did.",
            "type": "warning"
        }
    },
    "goToMyAccount": [{
        "action": "path",
        "options": {
            "path": "/account"
        }
    }]
}

Reserved Names (> v0.8.13)

Some names are used by built-in client workflows.

These reserved names are part of the client-side lifecycle / workflow system. They are not the same thing as FileMaker server hooks.

Reserved name	Scope	What it does
onFormLoad	Page-level named action	Runs just after a form/page is loaded in the browser
onAppLoad	App-level named action	Runs just after the app/site is loaded
onLogin	App-level named action	Runs after the user is authenticated on the client
appIsOnline	App-level named action	Runs when BetterForms detects the app has come back online
appIsOffline	App-level named action	Runs when BetterForms detects the app has gone offline
onDeployPost	App-level named action	Runs when the live app receives a post-deploy message after a deployment completes

onFormLoad

onFormLoad runs after the page/form has loaded.

• Define it on the page's form.namedActions
• If actions were generated in an onFormRequest hook, those actions are queued before onFormLoad
• A common pattern is to render the page, then run follow-up browser actions or a runUtilityHook

onAppLoad

onAppLoad runs after the app/site loads in the browser.

• Define it in app-level named actions
• Use it for app-wide startup work such as populating browser-side flags, loading libraries, or setting up PWA behavior
• BetterForms can skip it when the _onAppLoad=0 query parameter is present

onLogin

onLogin is a client-side named action that runs after the user authenticates.

• Define it in app-level named actions
• Use it for post-login client workflows such as populating client-side state or running follow-up UI actions
• This is separate from the FileMaker onLogin server hook

The normal login flow can involve both:

1. BetterForms authenticates the user.
2. BetterForms runs the FileMaker onLogin server hook.
3. BetterForms can also run the client-side named action site.content.namedActions.onLogin.

appIsOnline / appIsOffline

These app-level named actions are triggered when BetterForms detects an online/offline status change in the browser.

• Define them in app-level named actions
• Use them for reconnect UX, retry messaging, or online/offline banners
• They are browser-state workflows, not FileMaker hooks

onDeployPost

onDeployPost is an app-level named action that BetterForms can run when a deployment completes and the live app receives the post-deploy message.

• Define it in app-level named actions
• Available in Editor v125+
• This behavior works across supported basecode apps; the requirement is the Editor version that publishes the deploy behavior
• Use it for app-specific post-deploy UX such as custom messaging, partial refresh logic, cache invalidation, or controlled redirects/reloads

When a deploy completes, BetterForms sends a post message to the target app domain.

Before showing the shared fallback UI, BetterForms checks for a named action called onDeployPost.

• If site.content.namedActions.onDeployPost exists for the current app/site context, BetterForms runs that named action instead of the default footer UI
• If no onDeployPost named action is present, BetterForms shows the shared fallback UI

Default Fallback UI

The shared fallback is a bottom-of-screen refresh banner with:

• Title: Refresh needed
• Versioned title when available: Refresh needed (V<version>)
• Body text: An update is available. Save your work and refresh this page.
• Action button: Refresh

If deploy notes are provided, those notes are shown instead of the generic fallback body text.

Payload Passed To onDeployPost

The deploy message payload includes:

• source with value deploy
• reason
• deployedAt
• version
• note
• idEnvironment
• idApp

For the broader distinction between lifecycle hooks and FileMaker hooks, see Lifecycle Hooks and Common Hooks.

Usage

As an action in a standard array of actions:

{
    "action": "namedAction",
    "name": "showCantDoThat", //the name your named action
    
    //all options set here are merged into the options of the named actions
    "options": {
        "id": "12345" 
    }
}

In an HTML element using @click:

// Shows a button that triggers a namedAction called goToMyAccount
<button @click="namedAction('goToMyAccount',{id: '12345'})"  type="button">
     <i class="icon-user"></i> Show Account
</button>

In this example, goToMyAccount is the name of the named action and the {id: '12345'} is the options array that will be passed to the named action. In JavaScript, JSON keys do not need to be in quotes.

Sequence

If a namedAction is called while other actions are still in the queue, the namedAction will run first and get inserted at the front of the actions queue. You can think of this as a sub-script where the namedAction runs first and then the remaining actions continue. This allows you to reuse code and is particularly useful in the global scope.

If a name is not found in page, site, or registered component actions, BetterForms falls back to the legacy processNamedAction event-bus path for older component listeners.

---

See Also

• Lifecycle Hooks - Reference for onAppLoad, onFormLoad, and component lifecycle named actions
• Common Hooks - Reference for FileMaker server hooks such as onLogin
• Creating Components with Third-Party Libraries - Learn how to use named actions in component lifecycle hooks (onBeforeMount, onMount, etc.) to integrate JavaScript libraries
• BF.libraryLoadOnce() - Dynamic library loading utility for use in function actions
• Component Best Practices - Guidelines for creating custom components