# 4.1 Adding & Configuring Buttons (Page Builder)

Buttons are one of the most essential and versatile elements in BetterForms. They serve as the primary way users interact with your application by triggering actions like saving data, navigating pages, or running FileMaker scripts.

## What Makes BetterForms Buttons Powerful?

Unlike simple HTML buttons, BetterForms buttons can:

* **Run namedActions actions** Kike FileMaker script steps
* **Trigger FileMaker scripts** via hooks
* **Navigate between pages** with data
* **Show alerts and modals** for user feedback
* **Execute JavaScript** for advanced interactions

## Where to Add Buttons in the BetterForms IDE

### Using the Page Builder

1. **Open your page** in the BetterForms IDE
2. **Navigate to the Page Builder tab**
3. **Locate the Snippets section** (usually on the left side)
4. **Search for "button"** in the snippets library
5. **Copy and paste** the button JSON into your page schema's `fields` array

### Basic Button Structure

Every button in BetterForms follows this JSON structure:

```json
{
  "type": "button",
  "text": "Button Text",
  "buttonClasses": "btn btn-primary",
  "styleClasses": "col-md-6",
  "actions": [
    // Actions go here (namedAction by default)
  ]
}
```

**Key Properties:**

* `type`: Always "button"
* `text`: The label displayed on the button
* `buttonClasses`: Bootstrap CSS classes for button styling
* `styleClasses`: Layout classes (column width, spacing, etc.)
* `actions`: Array of actions to execute when clicked

## Common Button Types and Examples

### 1. Save Button (Triggers FileMaker Script)

This is the most common button type for FileMaker developers:

```json
{
  "type": "button",
  "text": "Save Record",
  "buttonClasses": "btn btn-success",
  "styleClasses": "col-md-4",
  "icon": "fa fa-save",
  "actions": [{
    "action": "runUtilityHook",
    "options": {
      "type": "save"
    }
  }]
}
```

**How it works:**

* Triggers the scoped FileMaker `onUtility` server hook via `runUtilityHook`
* Passes `type: "save"` as a parameter
* Your FileMaker script receives the current page data model

### 2. Navigation Button (Go to Another Page)

```json
{
  "type": "button",
  "text": "Go to Dashboard",
  "buttonClasses": "btn btn-info",
  "styleClasses": "col-md-4",
  "actions": [{
    "action": "path",
    "options": {
      "path": "/dashboard"
    }
  }]
}
```

**IDE Context:** The path corresponds to navigation slugs you set in App Settings → Navigation.

### 3. Alert Button (Show User Feedback)

```json
{
  "type": "button",
  "text": "Show Message",
  "buttonClasses": "btn btn-warning",
  "styleClasses": "col-md-4",
  "actions": [{
    "action": "showAlert",
    "options": {
      "title": "Success!",
      "text": "Your data has been saved successfully.",
      "type": "success"
    }
  }]
}
```

**Alert Types:** `success`, `error`, `warning`, `info`

### 4. Modal Button (Show Detailed Information)

```json
{
  "type": "button",
  "text": "Show Details",
  "buttonClasses": "btn btn-primary",
  "styleClasses": "col-md-4",
  "actions": [{
    "action": "showModal",
    "options": {
      "title": "Record Details",
      "body": "This modal shows detailed information about the selected record.",
      "icon": "info"
    }
  }]
}
```

### 5. External Link Button

```json
{
  "type": "button",
  "text": "View Documentation",
  "buttonClasses": "btn btn-secondary",
  "styleClasses": "col-md-4",
  "actions": [{
    "action": "path",
    "options": {
      "url": "https://docs.fmbetterforms.com/"
    }
  }]
}
```

## Advanced Button Configurations

### Multiple Actions in Sequence

Buttons can execute multiple actions one after another:

```json
{
  "type": "button",
  "text": "Save and Close",
  "buttonClasses": "btn btn-success",
  "styleClasses": "col-md-4",
  "actions": [
    {
      "action": "runUtilityHook",
      "options": {
        "type": "save"
      }
    },
    {
      "action": "showAlert",
      "options": {
        "title": "Saved!",
        "text": "Record saved successfully.",
        "type": "success"
      }
    },
    {
      "action": "path",
      "options": {
        "path": "/dashboard"
      }
    }
  ]
}
```

### Dropdown Buttons

Create dropdown menus with multiple options:

```json
{
  "type": "button",
  "text": "Actions",
  "buttonClasses": "btn btn-info",
  "styleClasses": "col-md-4",
  "icon": "fa fa-cog",
  "subs": [
    {
      "text": "Edit Record",
      "actions": [{
        "action": "path",
        "options": {
          "path": "/edit"
        }
      }]
    },
    {
      "divider": true
    },
    {
      "text": "Delete Record",
      "actions": [{
        "action": "runUtilityHook",
        "options": {
          "type": "delete"
        }
      }]
    }
  ]
}
```

### Button Groups

Group related buttons together:

```json
{
  "type": "button",
  "styleClasses": "col-md-8",
  "groupClasses": "btn-group",
  "group": [
    {
      "type": "button",
      "text": "Save",
      "buttonClasses": "btn btn-success",
      "actions": [{
        "action": "runUtilityHook",
        "options": {
          "type": "save"
        }
      }]
    },
    {
      "type": "button",
      "text": "Cancel",
      "buttonClasses": "btn btn-secondary",
      "actions": [{
        "action": "path",
        "options": {
          "path": "/cancel"
        }
      }]
    }
  ]
}
```

## Button Styling and Layout

### Bootstrap Button Classes

Use these `buttonClasses` for different button styles:

| Class               | Appearance             |
| ------------------- | ---------------------- |
| `btn btn-primary`   | Blue primary button    |
| `btn btn-success`   | Green success button   |
| `btn btn-danger`    | Red danger button      |
| `btn btn-warning`   | Yellow warning button  |
| `btn btn-info`      | Light blue info button |
| `btn btn-secondary` | Gray secondary button  |

### Size and Layout Classes

**Button Sizes:**

* `btn-lg` - Large button
* `btn-sm` - Small button
* `btn-block` - Full-width button

**Layout Classes (styleClasses):**

* `col-md-6` - Half width
* `col-md-4` - One-third width
* `col-md-12` - Full width

### Adding Icons

Icons enhance button usability:

```json
{
  "type": "button",
  "text": "Save",
  "icon": "fa fa-save",
  "buttonClasses": "btn btn-success",
  "styleClasses": "col-md-4"
}
```

**Common Font Awesome Icons:**

* `fa fa-save` - Save icon
* `fa fa-edit` - Edit icon
* `fa fa-trash` - Delete icon
* `fa fa-plus` - Add icon
* `fa fa-home` - Home icon

## Integration with FileMaker

### Passing Data to FileMaker Scripts

When using `runUtilityHook`, the current page data model is automatically sent to your FileMaker script:

**BetterForms Button:**

```json
{
  "actions": [{
    "action": "runUtilityHook",
    "options": {
      "type": "createContact",
      "priority": "high"
    }
  }]
}
```

**FileMaker Script Access:**

```javascript
// In your FileMaker onUtility hook script:
$type = JSONGetElement($$BF_Payload, "type")  // "createContact"
$priority = JSONGetElement($$BF_Payload, "priority")  // "high"
$modelData = JSONGetElement($$BF_Payload, "model")  // Complete page data
```

### Conditional Buttons

Show buttons based on data conditions:

```json
{
  "type": "button",
  "text": "Edit",
  "buttonClasses": "btn btn-primary",
  "styleClasses": "col-md-4",
  "visible_calc": "model.user.role === 'admin'",
  "actions": [{
    "action": "path",
    "options": {
      "path": "/edit"
    }
  }]
}
```

## Best Practices for Button Implementation

### 1. **Use Descriptive Text**

* ✅ "Save Contact" instead of "Save"
* ✅ "Delete Record" instead of "Delete"

### 2. **Provide Visual Feedback**

* Use appropriate button colors (success for save, danger for delete)
* Include relevant icons
* Show loading states for long operations

### 3. **Consider User Experience**

* Group related actions together
* Use confirmation dialogs for destructive actions
* Provide clear navigation paths

### 4. **Test Button Actions**

Use the **Actions tab** in the page editor to test button actions before deploying.

## Troubleshooting Common Issues

### Button Not Responding

* Check that the `actions` array is properly formatted
* Verify hook names match your FileMaker scripts
* Test actions individually in the Actions tab

### FileMaker Script Not Triggering

* Ensure the page is using the expected scoped hook set
* Check that your FileMaker script exists and is properly named
* Verify server connectivity in App Settings

### Styling Not Applied

* Check Bootstrap class names for typos
* Ensure proper JSON syntax with quotes
* Test with basic classes first

## Next Steps

Now that you understand buttons, you can:

* **Combine buttons with navigation** - See [4.2 Page Navigation](/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app/4.2-implementing-page-navigation-actions-and-site-navigation-ui.md)
* **Add buttons to data tables** - See [4.3 Displaying Data in Tables](/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app/4.3-displaying-data-in-tables-page-builder-and-element-config.md)
* **Style your buttons** - See [4.4 Basic App Styling](/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app/4.4-basic-app-styling-site-styling-ui.md)

{% hint style="info" %}
**Live Examples:** Check out the [BetterForms button examples](https://app.fmbetterforms.com/#/apps/pages/edit?id=5251675D-4A4D-4FE1-AD35-5D5B038CA924) to see these concepts in action.
{% 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/4.-common-customizations-and-expanding-your-app/4.1-adding-and-configuring-buttons-page-builder.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.