High-Level Architecture
High-Level Architecture
{{model}}",
"styleClasses": "col-md-12" // Or col-md-6 depending on template
}
]
},
"showPanelHeader": true, // This might be a default setting
"title": "My First Page" // This often reflects the page name
}
```
*(Note: The exact structure of default elements can vary. The key is adding the `Data Model Inspector` object correctly into the `fields` array.)*
{% hint style="info" %} The schema editor might seem overwhelming at first, but it's very well organized.
* To help you understand the structure, try clicking the small triangles or arrows often found near the line numbers. This allows you to collapse and expand JSON objects or arrays, making it easier to see the hierarchy.
* Alternatively, while you're learning, you might find it useful to copy your page schema JSON and paste it into an external JSON editor like [jsoneditoronline.org](https://jsoneditoronline.org/) to view and edit it in a different visual format. {% endhint %}
4. **Populating Initial Data (Data Model Tab):**
* Now, switch to the **"Data Model"** tab for your page. This is where you can define some initial data that your page will have when it loads.
* Enter a simple JSON object. The "HTML - Data Model Inspector" element we added to the schema will display this data on the page.
* For example, add:
```json
{
"nameFirst": "John",
"nameLast": "Doe",
"message": "Hello, BetterForms!"
}
```
5. **Save Your Page:**
* **Crucial step:** Click the **"Save"** button to save all your changes to the page schema and data model.
## Viewing Your New Page
You have two main ways to see your page:
1. **Preview within the IDE:** Most page editors have a **"Preview"** button. This will render your page directly within the BetterForms environment.
2. **Preview in Your Site:** To see it as your users would, you often want to preview it within your actual site. To do this, replace the `app.fmbetterforms.com` part of the preview URL (or the IDE's URL) with your own app's domain that you configured (e.g., `myawesomeapp.bfm.app`).
{% hint style="success" %}
Remember to **save** your page *before* previewing it in a new browser tab or window to ensure you see the latest changes!
{% endhint %}
Go ahead and preview this page in your site. You should see the "Data Model Inspector" element displaying the JSON data you entered:
```
{
"nameFirst": "John",
"nameLast": "Doe",
"message": "Hello, BetterForms!"
}
```
(Or however the `{{model}}` renders it).
## Next Steps
Congratulations! You've successfully created a basic page, defined its structure with the schema, added some initial data, and viewed it.
The next step is to learn about [Adding and Configuring Page Elements](/getting-started/ide-quick-tour/first-app/adding-elements) to build more complex and interactive user interfaces.
# 2.3 Understanding & Managing Environments (IDE)
After building your app, you will be taken to the environment management page. Here, you can manage different environments for your app, such as Development, Staging, and Production. This allows you to build, test and deploy your app in a controlled manner.
**Development Environment**
* This is where you will develop and test new features and changes before moving them to staging or production.
**Staging Environment**
* This environment is used for final testing before deployment to production. It mimics the production environment to ensure everything works as expected.
* Click the `"+ New"` button under the Staging section to create a staging environment.
**Production Environment**
* This is the live environment where your end users interact with your app. It should only contain thoroughly tested and stable versions of your app.
* Click the `"+ New"` button under the Production section to create a production environment.
You can switch between environments and manage their settings as needed to ensure a smooth development and deployment workflow.
# 2.4 Adding Elements to Your Page
You've successfully [created your first page](/getting-started/ide-quick-tour/first-app/create-page) and even added a "Data Model Inspector" to see some raw data. Now, let's explore how to add more structured and interactive elements to your page using the Page Schema editor.
The "Page Builder" or Schema Editor in BetterForms is your primary tool for this. It allows you to define, configure, and organize all the components that make up your user interface.
## Understanding the Page Schema for Elements
As you learned, the **Page Schema** is a JSON structure that defines everything on your page. The `fields` array within the schema is where you'll list the individual elements.
```json
{
"schema": {
"fields": [
// Elements like inputs, buttons, HTML blocks, etc., go here
]
},
// ... other page settings ...
}
```
Each object you add to the `fields` array represents a distinct element on your page.
## Using Snippets to Add Elements
The easiest way to add common pre-configured elements is by using the **Snippet Library** in the Schema Editor.
1. **Locate Snippets:** In the Schema Editor interface, you should find a section or search bar for "Snippets."
2. **Find an Element:** Search for the type of element you want to add (e.g., "button," "input," "HTML").
3. **Copy and Paste:** Select the desired snippet and copy it. Then, paste this JSON snippet into the `fields` array in your Page Schema. Remember to add a comma (`,`) after the preceding element if you're adding to an existing list.
This is how you added the "HTML - Data Model Inspector" in the previous step. You can use the same process to add input fields, buttons, and more.
## Organizing Elements with Groups
For more complex pages, you can organize your `fields` into logical `groups`. This helps in structuring your schema and can sometimes influence layout.
```json
{
"schema": {
"groups": [
{
"title": "User Information", // An optional title for the group
"_note": "Section for user details", // A note for schema organization
"fields": [
{ "type": "input", "model": "nameFirst", "label": "First Name" },
{ "type": "input", "model": "nameLast", "label": "Last Name" }
]
},
{
"title": "Actions",
"fields": [
{ "type": "button", "label": "Save", "action": "submitData" }
]
}
]
},
// ...
}
```
* `_note`: This property is purely for your organizational purposes within the schema and doesn't render on the page.
## Common Element Properties
Each element you add will have various properties to configure its behavior and appearance:
* `type`: Specifies the kind of element (e.g., "input", "button", "html"). This is fundamental.
* `label`: Text displayed as the label for an element (e.g., for an input field).
* `model`: For input fields, this links the element to a specific key in your [Page Data Model](/getting-started/ide-quick-tour/first-app/create-page#1-the-data-model).
* `styleClasses`: Allows you to apply CSS classes (e.g., Bootstrap classes like `col-md-6` for layout, or custom classes) to style the element.
* `visible`: Can be set to `false` to hide an element statically.
* `visible_calc`: For dynamic visibility, you can use a calculation based on your data model, e.g., `"visible_calc": "model.isUserAdmin"`.
You'll find many more properties specific to each element type in the [BetterForms Elements reference documentation](/reference/components-overview).
## Basic Input Field Validation
For input fields, you can add validation rules:
* `validator`: Specify a validator type (e.g., `"string"`, `"number"`, `"email"`).
* `validator_calc`: For dynamic validation conditions.
* `errorMsg`: A custom message to display if validation fails.
Example:
```json
{
"type": "input",
"model": "email",
"label": "Email Address",
"validator": "email",
"errorMsg": "Please enter a valid email address."
}
```
Validation can also be triggered by actions, like a button click.
## Tools for Managing the JSON Schema
The Schema Editor provides tools to help you work with the JSON structure, especially for complex pages:
* **Folding/Unfolding:** Look for controls (often in a toolbar or near line numbers) to collapse or expand different levels of your JSON schema. This is very helpful for navigating large schemas.
* **Formatting:** There's usually an option to automatically format your JSON, keeping it neat and readable.
## Editing HTML Content Within Elements
If you add an "html" type element (or other elements that embed HTML), the Schema Editor often provides a dedicated HTML editor:
* **Accessing the Editor:** Typically, clicking on the line number of an HTML field in the schema will open up a more user-friendly HTML editing interface.
* **Features:** This editor might offer features like syntax highlighting, and sometimes even direct data model editing or an AI assistant for HTML generation.
* **Saving:** Remember to save changes within the HTML editor, and then save the overall page schema.
## Next Steps
You now have a basic understanding of how to add and configure elements on your BetterForms page using the Page Schema editor. The key is to:
1. Use snippets to add elements quickly.
2. Understand the basic properties like `type`, `model`, and `label`.
3. Refer to the detailed documentation for each specific element type.
Explore the [BetterForms Elements reference](/reference/components-overview) to see the wide variety of available elements and their specific configuration options. As you build out your first application, you'll become more familiar with these tools and properties.
# 2.5 Understanding Validation
Validation is a crucial part of ensuring data integrity in your BetterForms application. This guide will help you understand how to implement and manage validation in your pages.
## Client-Side Validation
Client-side validation is controlled by the `validator` key in all page elements. This validation happens immediately in the browser, providing instant feedback to users.
### Triggering Validation
Validation does not run automatically. You must trigger client validation with the `validate` action. This action can be added to buttons or other elements to validate the form when needed. Automatic validation can be controlled with the validations settings from the `Page Settings` tab withing the page editor.
### Validator Types
The `validator` key can be set to the following types:
* **number**: Checks that the value is numeric and within the fields min & max range, if defined.
* **integer**: Checks that the value is a valid JavaScript Number and an integer.
* **double**: Checks that the value is a valid number.
* **string**: Checks that the value is a string and its length is within the fields min & max range, if defined.
* **array**: Checks that the value is an array and its length is within the fields min & max range, if defined.
* **date**: Checks that the value is a valid JavaScript Date and between the fields min and max dates, if defined.
* **regexp**: Checks that the value matches the regex defined in the fields schema.pattern.
* **email**: Checks that the value is a plausible looking email address.
* **url**: Checks that the value is a plausible looking http url.
* **creditCard**: Checks that the value is a valid credit card number.
* **alpha**: Checks that the value is a letter.
* **alphaNumeric**: Checks that the value is a letter or a number.
## Custom Validators
You can define your own JavaScript custom validation calculation that will fire the same as the regular validators. By selecting the `validator` type to `calc` and adding a calculation and error message, you can have excellent control over validation.
### Example: Custom Validator
Here's an example of how to define a custom validator:
```json
{
"inputType": "text",
"label": "Some Password",
"model": "password1",
"placeholder": "",
"styleClasses": "w-80",
"type": "input",
"required": true,
"validator": "string"
},
{
"inputType": "text",
"label": "Another Password",
"model": "password2",
"placeholder": "",
"styleClasses": "w-80",
"type": "input",
"required": true,
"validator": "calc",
"validator_calc": "model.password1 == model.password2",
"errorMsg": "The passwords do not match"
}
```
## Server-Side Validation
While client-side validation is useful for providing immediate feedback, sensitive data should also be validated in your FileMaker scripts before committing to the database. This ensures that data integrity is maintained even if client-side validation is bypassed.
## Validation Settings
The **Page Settings** tab allows you to manage validation settings for your page:
* **Validate After Loaded**: Triggers validation routines as soon as the page is loaded. This should be enabled if any fields on the page have validators.
* **Validate After Changed**: Triggers validation routines as soon as a field is changed. This should also be enabled if fields have validators to ensure data integrity.
## Next Steps
You now have a basic understanding of how to implement and manage validation in your BetterForms application. As you build out your first application, you'll become more familiar with these components and how to use them effectively.
Explore the [BetterForms Elements reference](/reference/components-overview) to see the wide variety of available elements and their specific configuration options.
# 2.6 Adding Actions to Your Page
Now that you understand the basics of the Page Data Model and Hooks, let's explore how to add actions to your page in BetterForms. This guide will walk you through the process of setting up and running actions.
## Introduction to Actions
Actions are instructions that tell the BetterForms framework to perform some operation. They can be used to create interactions with the user. Actions can be executed sequentially, and some actions block the execution of the next action until they are complete.
## Types of Actions
### Regular Actions
* ***showModal*** - Renders a modal dialog
* ***hideModal*** - Hides a modal that is non-blocking
* ***showAlert*** - Renders a toaster style alert
* ***path*** - redirects the user to a new page
* ***runUtilityHook*** - runs the `onUtility` hook passing it params
* ***downloadFile*** - downloads a file (link) to the user
* ***runOnCompleteHook*** - runs the `onComplete` hook
* ***clipboard*** - runs `clipboard` action allowing interaction with the clipboard
* ***cookie*** - Allows setting of browser side cookies
* ***wait*** - Waits for specified time or event
* ***emit*** - Vue event bus message emit
* ***scrollTo*** - Scrolls to an element
* ***namedAction*** - Runs a named action. Also requires the `name` key.
* ***function*** - Runs JavaScript
### Authentication Actions
* ***authLogin*** - Performs an authentication login
* ***authLogout*** - Performs logout
* ***authReset*** - Performs a password reset action
* ***authForgot** -* Performs a forgotten password reset hook
* ***authVerify*** - Performs a verification of the verify token
* ***authResend*** - Re/sends the email verification token
* ***authRegister*** - Performs a registration and if successful, runs the `onRegistrationHook`
## Where Actions Can Be Used
Actions can be injected in many places:
* Most hook scripts
* Navigation Menu Items
* Form action elements (buttons)
* Named Actions
* `*_actions` schema keys (where supported)
## Adding Actions to a Page
To add actions to a page, you can use the `actions` key in the page schema. This key can be either an object (for running a single action) or an array of objects (to run a series of actions).
### Example: Adding a Button with Actions
Here's an example of how to add a button with actions to your page:
```json
{
"actions": [{
"action": "showAlert",
"options": {
"text": "This is the alert message text",
"title": "Hello World",
"type": "information"
}
}],
"buttonClasses": "btn btn-primary",
"styleClasses": "col-md-4",
"text": "Show Alert",
"type": "button"
}
```
### Example: Adding a Named Action
You can also use named actions to define a set of actions that can be called from multiple places. Here's an example of how to define a named action:
```json
"namedActions": {
"showCantDoThat": {
"action": "showAlert",
"options": {
"title": "Whoooaa!!",
"text": "You can't do that thing you just did.",
"type": "warning"
}
}
}
```
## Next Steps
You now have a basic understanding of how to add actions to your page in BetterForms. As you build out your first application, you'll become more familiar with these components and how to use them effectively.
Explore the [BetterForms Elements reference](/reference/components-overview) to see the wide variety of available elements and their specific configuration options.
# 2.7 Creating Your First List View
Now that you understand how to add elements and implement validation in your pages, let's explore how to create your first list view in BetterForms. This guide will walk you through the process of setting up and managing a list of rows in your application.
## Introduction to List Views
A list view in BetterForms is a dynamic way to display and manage multiple rows of data. Each row can consist of various fields, allowing you to create complex forms that handle multiple entries, such as address lists or contact details.
> **Note**: For more advanced table-based data display with features like sorting, filtering, and pagination, see [Working with Data Tables](/getting-started/ide-quick-tour/first-app/working-with-data-tables).
## When to Use List Views
List views are ideal for:
* Simple multi-row data entry forms
* Contact lists or address books
* Product lists with basic information
* Any scenario where you need to add/remove rows of similar data
For more complex data display needs (sorting, filtering, pagination), consider using [Data Tables](/getting-started/ide-quick-tour/first-app/working-with-data-tables) instead.
## Using the `listrows` Component
The `listrows` component is used to display and manage a list of rows where each row consists of fields defined in the schema. This allows for the dynamic rendering of forms that include multiple rows of data inputs.
### Example Configuration
Here's an example of how to configure a `listrows` component:
```json
[
{
"isCollapsable": false,
"schema": {
"fields": [
{
"label": "Enter Some Contacts (min. 2 max 4)",
"max": 4,
"min": 2,
"model": "address",
"schema": {
"fields": [
{
"inputType": "text",
"label": "First Name",
"model": "nameFirst",
"styleClasses": "col-md-3",
"type": "input"
},
{
"inputType": "text",
"label": "Last Name",
"model": "nameLast",
"styleClasses": "col-md-3",
"type": "input"
},
{
"inputType": "text",
"label": "Street 1",
"model": "street1",
"styleClasses": "col-md-3",
"type": "input"
},
{
"inputType": "text",
"label": "Street 2",
"model": "street2",
"styleClasses": "col-md-3",
"type": "input"
}
]
},
"styleClasses": "col-md-8",
"type": "listrows"
}
]
}
}
]
```
### Key Attributes
* **`model`**: The data model path where the array of rows is stored. In this case, `address` is the model where each row of contact data is kept.
* **`min`**: Defines the minimum number of rows required (e.g., 2).
* **`max`**: Defines the maximum number of rows allowed (e.g., 4).
* **`schema.fields`**: An array of field configurations that will be displayed in each row. Each field can have its label, model, input type, and layout styling.
### Visual Example
* Each row contains four text input fields
* The \[+]\[-] buttons allow adding/removing rows
* The component enforces a minimum of 2 and maximum of 4 rows
## Best Practices
1. **Set Appropriate Limits**: Always define `min` and `max` values to prevent users from creating too many or too few rows.
2. **Use Consistent Styling**: Apply consistent `styleClasses` to maintain a clean layout.
3. **Validate Each Field**: Consider adding validation rules to individual fields within the rows.
4. **Consider Mobile Layout**: Use responsive classes (like `col-md-3`) to ensure the form looks good on all devices.
## Notes
* The `listrows` component is versatile and can handle different types of input fields like text, checkboxes, and dropdowns.
* The display of Add and Delete icons is automatically handled based on the defined `min` and `max` values.
* Each row's data is stored as an object in the array specified by the `model` attribute.
## Next Steps
You now have a basic understanding of how to create a list view in BetterForms. As you build out your first application, you'll become more familiar with these components and how to use them effectively.
For more advanced data display needs, you can explore:
* [Working with Data Tables](/getting-started/ide-quick-tour/first-app/working-with-data-tables) for complex table-based data display
* [BetterForms Elements reference](/reference/components-overview) for all available components
# 2.8 Understanding Page Data Flow
In BetterForms, the **Page Data Model** and **Hooks** are fundamental to how data flows within your application. This guide will help you understand how these components work together to manage data on your page.
## The Page Data Model
The **Data Model** is a JSON structure that stores all data accessible to the current page. It serves as the foundation for data binding, ensuring that elements like inputs and dynamic content are connected to the underlying data.
### Binding Data to Page Elements
For instance, if your data model includes:
```json
"user": {
"firstName": ""
}
```
You can bind this data to an input field using the following snippet:
```json
{
"inputType": "text",
"label": "First Name",
"model": "user.firstName",
"styleClasses": "",
"type": "input"
}
```
Or, in an HTML content field:
```html
Your first name is: {{ model.user.firstName }}
``` These examples show how the data model connects to elements on the page, allowing for dynamic interaction and updates. ### Default and Development Data Model * **Default Data Model:** This contains the production data that will be loaded into the page's model when the page is first rendered. This data is sent to your FMS via the `onFormRequest` hook. * **Development Data Model:** This is for data used only in the BetterForms IDE. The development data is merged with the default data model during previews, allowing you to work with mock data while building the page. ## Hooks and Data Flow Server hooks are FileMaker-side scripts that BetterForms can trigger during page workflows. Client-side lifecycle named actions such as `onFormLoad` are related, but they are not FileMaker hooks. ### onFormRequest Hook The `onFormRequest` hook is used to pull data from the backend and integrate it into the data model. This hook is triggered when the page is first loaded, allowing you to populate the data model with initial data from your FileMaker Server. ### onUtility Hook The `onUtility` hook is the most common type of scoped hook and is called with the `runUtilityHook` action. This hook allows you to perform actions like saving data back to your FileMaker database. ### Related Lifecycle Named Actions You may also use client-side named actions such as `onFormLoad` to start browser workflows after the page loads. Those workflows can include a `runUtilityHook` action when they need to call FileMaker. ### Controlling Data Sent from the Browser To reduce data transfer and improve performance, you can control what data is sent from the browser to the server using methods like `modelFilterKeys` or `model` to filter the data model. ## Integration Settings The **Integration** tab allows you to manage hooks and validation settings for your page: * **Enable onFormRequest Hook:** When enabled, this will trigger the `onFormRequest` hook script. For most pages that have data coming from the backend, this should be ticked on. * **Send Full Schema in Utility Hooks:** Sends the entire formSchema on hooks, providing more control but may increase transfer time on large schemas. Leave unchecked for better performance unless necessary. ## Next Steps You now have a basic understanding of how the Page Data Model and Hooks work together to manage data flow within your BetterForms application. As you build out your first application, you'll become more familiar with these components and how to use them effectively. Explore the [BetterForms Elements reference](/reference/components-overview) to see the wide variety of available elements and their specific configuration options. # 2.9 Creating Your First Hook Now that you understand the basics of the Page Data Model and Hooks, let's create your first hook in BetterForms. This guide will walk you through the process of setting up and running a simple hook. ## Introduction to Hooks Hooks are scripts that insert themselves into normal workflow, allowing additional control. They can be triggered at various points in the page lifecycle, such as when the page is first loaded or when a utility action is performed. Hooks fall into two categories: * **Common Hooks:** These are not contextual to a specific page and can be called from anywhere. Examples include login or registration hooks. * **Scoped Hooks:** These are bound to a specific page. The `onFormRequest` hook is an example of a scoped hook, which is called when a specific form loads. ## Creating Your First Hook For your first hook, let's enable the `onFormRequest` option for the page you just created. This option can be enabled in the **Integration** tab of the page editor. ### Step 1: Enable the onFormRequest Hook 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 legacy FileMaker file, locate the one called `Klai - onFormRequest - [scopedHookName]` where `[scopedHookName]` is the name of the scoped hook you defined on your page settings. This is the script that is run when the page is first loaded in the browser. ### Step 3: Modify the FileMaker Script You can do anything you want in this script, but the ultimate goal for this example 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. For now, just set the variable to something like this as an example, as long as it's different than what you set on the page's default data model so you can make sure the hook is running properly. ```javascript JSONSetElement ( $$BF_Model ; [ "nameFirst" ; "Jim" ; JSONString ]; [ "nameLast" ; "Bob" ; JSONString ] ) ``` {% hint style="info" %} Notice how we are only modifying the `$$BF_Model` JSON instead of replacing it. This is good practice when working with that global variable because otherwise you could accidentally erase existing data from the user's browser. {% endhint %} ### Step 4: Run the Hook * **Save the FileMaker script.** * **Save your page settings.** * **Refresh your preview tab (or launch it again).** If everything is properly connected, you should see the data set from your FileMaker script on the page instead of the default data model. Even if you succeed here, be sure to review the troubleshooting tips for those times when it doesn't always go as planned. ## Troubleshooting Hooks ### Check the Inbox Every single hook that interacts with your FileMaker server goes through the Helper file, so that's always a great place to start debugging. Open the helper file and click the **Inbox** tab. Show the status toolbar and make sure you are viewing the most recent record. The left side shows you what data came in for a hook, while the right side shows you the data you sent back to the browser. **If the record doesn't show up in the inbox**, then the hook never reached your FileMaker server. * Double-check that the **onFormRequest** is enabled for your page in the Integration tab of the page editor. Then refresh your preview. * Check the BetterForms [user credentials](/getting-started/ide-quick-tour/setup/configure-fm-server) *(see below)* **If you're not sure if the record is in the inbox or not**, clear the inbox (delete all records) then refresh your preview in the browser to double-check if the inbox record was created. **If the inbox record exists but you had unexpected results**, check the outbox payload (the right side) to see the data model that was returned to the browser. You can run the hook locally by clicking the **Run Hook** button. **If the hook runs as expected locally, but not through BetterForms**, then you need to [check the privileges](/getting-started/ide-quick-tour/setup/configure-fm-server) of the BetterForms user. The only differences between how BetterForms runs the script and when you run it locally with that handy button is the user account that runs the script. ### Check Extended Privileges Invalid credentials or misconfigured extended privileges for the BetterForms user is the most common cause of integration problems. Make sure your credentials for the BetterForms user have XML and Data API privileges enabled, and that they match what was configured in your [site settings](/getting-started/ide-quick-tour/first-app/create-app). * BetterForms encrypts these credentials so you would have to re-enter them to verify they are correct. Your current credentials are not viewable from the IDE. ## Next Steps You now have a basic understanding of how to create and run your first hook in BetterForms. As you build out your first application, you'll become more familiar with these components and how to use them effectively. Explore the [BetterForms Elements reference](/reference/components-overview) to see the wide variety of available elements and their specific configuration options. # 2.10 Working with Data Tables This page is a quick starting point for BetterForms data tables. If you are deciding between list-style layouts and data tables: * Use [Creating Your First List View](/getting-started/ide-quick-tour/first-app/creating-your-first-list-view) for simpler repeated record layouts. * Use [Data Tables in the IDE](/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app/4.3-displaying-data-in-tables-page-builder-and-element-config) when you want sorting, filtering, pagination, row actions, or richer table presentation. ## Start Here * [Data Table component reference](/reference/components-overview/common/tables2) * [Data Tables in the IDE](/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app/4.3-displaying-data-in-tables-page-builder-and-element-config) * [Vue-Tables-2 options reference](https://matanya.gitbook.io/vue-tables-2/options-api#options) ## Typical Use Cases * admin and management screens * reporting and analytics views * searchable multi-column record lists * row actions, details, and custom cell rendering Use the reference page for supported BetterForms schema keys, then use the IDE guide for practical setup patterns. # 3. Understanding Core BetterForms Concepts # 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:Your email is: {{model.user.email}}
``` ## Where to Find Data Model in the BetterForms IDE ### Data Model Tab (Primary Interface) 1. **Open any Page** in the BetterForms IDE 2. **Navigate to the Data Model tab** 3. **Two main sections available:** | **Section** | **Purpose** | **When Used** | | -------------------------- | ---------------------------------------- | ---------------------------------------------------------------- | | **Default Data Model** | Production data loaded when page renders | Live application data sent to FileMaker via `onFormRequest` hook | | **Development Data Model** | Mock data for IDE testing | Preview and development in BetterForms IDE only | ### Page Builder Integration The **Page Builder** tab works hand-in-hand with your data model: 1. **Schema Editor** - Define elements that bind to data model keys 2. **Real-time Preview** - See how your data model affects page rendering 3. **Snippets** - Use "HTML - Data Model Inspector" to debug data **Data Model Inspector Snippet:** ```json { "type": "html", "label": "Data Model Inspector", "html": "{{model}}",
"styleClasses": "col-md-12"
}
```
## Data Model Lifecycle
Understanding when and how data flows is crucial:
### 1. Page Load
* **Default Data Model** loads first
* **onFormRequest Hook** (if enabled) can override with FileMaker data
* **Development Data Model** merges for IDE previews only
### 2. User Interaction
* Input fields update data model in real-time
* Changes are reflected immediately in bound elements
* No automatic saving - requires explicit actions
### 3. Data Persistence
* Use `runUtilityHook` action to send data to FileMaker
* FileMaker scripts receive the current data model
* Server can modify and return updated data
## Development vs Production Data
### Development Data Model
**Purpose:** Testing and development without affecting live data
**Features:**
* **IDE Only:** Never sent to FileMaker server
* **Merged with Default:** Combines with default data during previews
* **Caching:** Can be synced across IDE sessions
**Example Use Cases:**
```json
{
"user": {
"firstName": "Test User",
"lastName": "Developer",
"role": "admin"
},
"debugMode": true
}
```
### Default Data Model (Production)
**Purpose:** Real application data used in live environment
**Features:**
* **FileMaker Integration:** Sent to `onFormRequest` hook
* **User Data:** Updated through page interactions
* **Persistence:** Saved via `runUtilityHook` actions
## Data Model Best Practices
### 1. Structure Your Data Logically
**Good:**
```json
{
"user": {
"personal": { "firstName": "", "lastName": "" },
"contact": { "email": "", "phone": "" }
},
"settings": { "theme": "light", "notifications": true }
}
```
**Avoid:**
```json
{
"firstName": "",
"lastName": "",
"email": "",
"phone": "",
"theme": "",
"notifications": ""
}
```
### 2. Use Meaningful Key Names
* Use `user.firstName` instead of `fn`
* Use `invoice.items` instead of `data`
* Be consistent with naming conventions
### 3. Plan for FileMaker Integration
Structure your data model to match how FileMaker will process it:
```json
{
"record": {
"id": "",
"name": "",
"created": ""
},
"metadata": {
"lastModified": "",
"version": ""
}
}
```
## Common Data Model Patterns
### Master-Detail Pattern
```json
{
"invoice": {
"id": "INV-001",
"customer": "Acme Corp",
"total": 0
},
"lineItems": [
{ "product": "Widget A", "qty": 2, "price": 10.00 },
{ "product": "Widget B", "qty": 1, "price": 15.00 }
]
}
```
### Form Wizard Pattern
```json
{
"step1": { "personal": { "firstName": "", "lastName": "" }},
"step2": { "contact": { "email": "", "phone": "" }},
"step3": { "preferences": { "newsletter": false }},
"wizardState": { "currentStep": 1, "completed": false }
}
```
## Troubleshooting Data Model Issues
### Data Not Displaying
1. **Check binding:** Verify `model` property matches data structure
2. **Inspect with HTML:** Use Data Model Inspector snippet
3. **Check console:** Look for JavaScript errors
### Data Not Saving
1. **Verify hook configuration:** Ensure `runUtilityHook` action is configured
2. **Check FileMaker script:** Verify script receives `$$BF_Model` correctly
3. **Test locally:** Use Helper File "Run Hook" button
## Next Steps
Congratulations! You now understand all three core BetterForms concepts:
✅ **Hooks** - Connect to FileMaker scripts\
✅ **Actions** - Control application behavior\
✅ **Data Model** - Manage page data and binding
**Ready to build:** You can now create sophisticated BetterForms applications with confidence.
**What's next:** Explore [Common Customizations](https://github.com/DelfsEngineering/fm-betterforms/blob/master/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app) to learn practical implementation patterns.
{% hint style="info" %}
**Pro Tip:** The Data Model Inspector is your best friend for debugging. Add it to any page when troubleshooting data flow issues.
{% endhint %}
# 4. Common Customizations & Expanding Your App
# 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)
* **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)
* **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)
{% 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 %}
# 4.2 Implementing Page Navigation (Actions & Site Navigation UI)
Navigation is a crucial aspect of any BetterForms application. This section covers both programmatic navigation using actions and setting up site-wide navigation menus that users can interact with.
## Two Types of Navigation in BetterForms
### 1. **Action-Based Navigation**
Navigation triggered by user actions (button clicks, form submissions, etc.)
### 2. **Site Navigation Menu**
Persistent navigation menus that appear on all pages (typically in the sidebar)
## Action-Based Navigation
### Using the `path` Action
The `path` action is the primary way to navigate between pages programmatically:
```json
{
"action": "path",
"options": {
"path": "/dashboard"
}
}
```
This action can be used in:
* **Button actions**
* **Form submissions**
* **Hook responses**
* **Navigation menu items**
### Navigation Button Examples
#### Basic Page Navigation
```json
{
"type": "button",
"text": "Go to Dashboard",
"buttonClasses": "btn btn-primary",
"styleClasses": "col-md-4",
"actions": [{
"action": "path",
"options": {
"path": "/dashboard"
}
}]
}
```
#### Navigation with Data
Pass data to the destination page using query parameters:
```json
{
"type": "button",
"text": "Edit Contact",
"buttonClasses": "btn btn-info",
"styleClasses": "col-md-4",
"actions": [{
"action": "path",
"options": {
"path": "/contact-edit?id=123&mode=edit"
}
}]
}
```
#### External Navigation
Link to external websites:
```json
{
"type": "button",
"text": "Open Documentation",
"buttonClasses": "btn btn-secondary",
"styleClasses": "col-md-4",
"actions": [{
"action": "path",
"options": {
"url": "https://docs.fmbetterforms.com/"
}
}]
}
```
### Save and Navigate Pattern
Common FileMaker developer pattern - save data then navigate:
```json
{
"type": "button",
"text": "Save & Return",
"buttonClasses": "btn btn-success",
"styleClasses": "col-md-4",
"actions": [
{
"action": "runUtilityHook",
"options": {
"type": "save"
}
},
{
"action": "path",
"options": {
"path": "/contact-list"
}
}
]
}
```
## Setting Up Site Navigation in the IDE
### Where to Configure Site Navigation
1. **Open App Settings** in the BetterForms IDE
2. **Navigate to Environment section**
3. **Find the Navigation tab**
4. **Configure your navigation schema**
### Navigation Slugs (URL Mapping)
First, set up navigation slugs to map friendly URLs to page IDs:
```json
{
"default": {
"id": "36D74465-3F11-4CE4-A0FD-370D78C98B86"
},
"dashboard": {
"id": "633D7D10-F8AD-4B6E-8D86-BDC8038D6E91"
},
"contacts": {
"id": "A1B2C3D4-E5F6-7890-1234-567890ABCDEF"
},
"settings": {
"id": "F1E2D3C4-B5A6-9876-5432-10FEDCBA9876"
}
}
```
**Benefits of Navigation Slugs:**
* **Clean URLs:** `/dashboard` instead of `/form/633D7D10-F8AD-4B6E-8D86-BDC8038D6E91`
* **Easy Updates:** Change the page ID in one place to update all references
* **User-Friendly:** URLs are easier to understand and remember
### Navigation Menu Schema
The navigation menu is defined as an array of objects in the **Menu Schema** section:
```json
[{
"sectionLabel": "Main Menu",
"subs": [{
"label": "Dashboard",
"icon": "fa fa-home",
"path": "/dashboard"
}, {
"label": "Contacts",
"icon": "fa fa-users",
"path": "/contacts"
}, {
"label": "Settings",
"icon": "fa fa-cog",
"path": "/settings"
}]
}]
```
### Navigation Menu Structure
**Top Level Properties:**
* `sectionLabel`: Section title (not clickable)
* `subs`: Array of menu items
* `styleClassesSection`: CSS classes for the section
**Menu Item Properties:**
* `label`: Display text
* `icon`: Font Awesome icon class
* `path`: Navigation path (corresponds to slugs)
* `actions`: Alternative to path for complex behaviors
* `visible`: Boolean or `visible_calc` for conditional display
## Advanced Navigation Examples
### Dropdown Menus
Create hierarchical navigation with nested menus:
```json
[{
"sectionLabel": "Main Menu",
"subs": [{
"label": "Dashboard",
"icon": "fa fa-home",
"path": "/dashboard"
}, {
"label": "Contacts",
"icon": "fa fa-users",
"subs": [{
"label": "View All Contacts",
"icon": "fa fa-list",
"path": "/contacts"
}, {
"label": "Add New Contact",
"icon": "fa fa-plus",
"path": "/contact-new"
}, {
"divider": true
}, {
"label": "Import Contacts",
"icon": "fa fa-upload",
"path": "/contact-import"
}]
}]
}]
```
### Action-Based Navigation Items
Use actions instead of direct navigation for complex behaviors:
```json
[{
"sectionLabel": "Main Menu",
"subs": [{
"label": "Logout",
"icon": "fa fa-sign-out",
"actions": [{
"action": "authLogout"
}, {
"action": "path",
"options": {
"path": "/login"
}
}]
}]
}]
```
### Conditional Navigation
Show navigation items based on user permissions:
```json
[{
"sectionLabel": "Main Menu",
"subs": [{
"label": "Admin Panel",
"icon": "fa fa-shield",
"path": "/admin",
"visible_calc": "app.user.role === 'admin'"
}]
}]
```
### Navigation with Badges
Add dynamic badges to navigation items:
```json
[{
"sectionLabel": "Main Menu",
"subs": [{
"html": "\n Messages\n {{app.unreadCount}}\n"
}]
}]
```
## URL Structure and Query Parameters
### BetterForms URL Structure
```
https://yourdomain.fmbetterforms.com/#/dashboard?id=123&mode=edit
```
**Components:**
* `https://yourdomain.fmbetterforms.com` - Your domain
* `#/dashboard` - Navigation slug
* `?id=123&mode=edit` - Query parameters
### Working with Query Parameters
**In FileMaker Scripts:** Access query parameters via the `$$BF_Query` global variable:
```javascript
// In your onFormRequest hook
Set Variable $contactId = JSONGetElement($$BF_Query, "id")
Set Variable $mode = JSONGetElement($$BF_Query, "mode")
```
**In JavaScript/HTML:**
```javascript
// Using BetterForms utility function
const contactId = BF.getQueryParam('id');
const mode = BF.getQueryParam('mode');
```
## IDE Navigation Configuration Workflow
### Step 1: Plan Your Navigation Structure
1. **List all pages** in your app
2. **Group related pages** under logical sections
3. **Determine hierarchy** (which pages need submenus)
4. **Consider user roles** (which pages need conditional access)
### Step 2: Set Up Navigation Slugs
1. **Go to App Settings → Navigation**
2. **Find the Slug Names section**
3. **Add entries** for each page:
```json
{
"dashboard": { "id": "your-page-id" },
"contacts": { "id": "your-page-id" },
"settings": { "id": "your-page-id" }
}
```
### Step 3: Configure Menu Schema
1. **In the Menu Schema section**
2. **Build your navigation structure**:
```json
[{
"sectionLabel": "Main Menu",
"subs": [
// Your menu items here
]
}]
```
### Step 4: Test Navigation
1. **Save your changes**
2. **Test each navigation item**
3. **Verify paths resolve correctly**
4. **Check conditional visibility**
## Best Practices
### 1. **Consistent Navigation Structure**
* Keep navigation consistent across all pages
* Use familiar icons and terminology
* Group related functionality together
### 2. **User-Friendly URLs**
* Use descriptive navigation slugs
* Avoid exposing internal page IDs
* Keep URLs short and memorable
### 3. **Responsive Design**
* Consider mobile navigation experience
* Use appropriate icons for touch interfaces
* Test navigation on different screen sizes
### 4. **Performance Optimization**
* Minimize navigation complexity
* Use conditional visibility judiciously
* Consider caching navigation data
## Integration with FileMaker
### Navigation-Triggered Scripts
Navigation can trigger FileMaker scripts using actions:
```json
{
"label": "Generate Report",
"icon": "fa fa-file-pdf",
"actions": [{
"action": "runUtilityHook",
"options": {
"type": "generateReport",
"reportType": "monthly"
}
}]
}
```
### Dynamic Navigation Updates
Update navigation based on FileMaker data:
```json
{
"label": "Orders",
"icon": "fa fa-shopping-cart",
"path": "/orders",
"visible_calc": "app.user.permissions.includes('view_orders')"
}
```
## Troubleshooting Common Issues
### Navigation Not Working
* Check that navigation slugs are properly configured
* Verify page IDs are correct
* Ensure JSON syntax is valid
### Pages Not Loading
* Confirm target pages exist
* Check page authentication settings
* Verify navigation paths match slug names
### Conditional Navigation Issues
* Test `visible_calc` expressions
* Verify app model data is available
* Check for JavaScript syntax errors
## Next Steps
Now that you understand navigation, you can:
* **Implement 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)
* **Style your navigation** - 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)
* **Learn about authentication** - See [Authentication](/reference/authentication)
{% hint style="info" %}
**URL Best Practice:** Always use navigation slugs instead of direct page IDs for better maintainability and user experience.
{% endhint %}
# 4.3 Displaying Data in Tables (Page Builder & Element Config)
BetterForms provides powerful options for displaying tabular data, from simple list views to advanced data tables. This section covers when to use each approach and how to implement them effectively.
## Two Main Approaches to Displaying Data
### 1. **List Views (`listrows`)**
* Simple multi-row data entry forms
* Add/remove rows functionality
* Good for data input scenarios
* Limited sorting and filtering
### 2. **Data Tables (`tables2`)**
* Advanced data display with sorting, filtering, pagination
* Read-only data presentation
* Complex interactions and custom formatting
* Based on Vue-Tables-2 library
## When to Use Each Approach
| **Use List Views When:** | **Use Data Tables When:** |
| ---------------------------- | -------------------------------------- |
| Users need to add/edit rows | Displaying read-only data |
| Simple data entry forms | Large datasets requiring search/filter |
| Contact lists, address books | Reports and analytics |
| Product catalogs (editable) | User management interfaces |
| Max 20-30 rows | Hundreds or thousands of rows |
## List Views (`listrows`) Implementation
### Where to Add List Views in the IDE
1. **Open your page** in the BetterForms IDE
2. **Navigate to Page Builder tab**
3. **Search for "listrows"** in the snippets
4. **Copy and paste** into your page schema
### Basic List View Structure
```json
{
"type": "listrows",
"label": "Contact List",
"model": "contacts",
"min": 1,
"max": 10,
"styleClasses": "col-md-12",
"schema": {
"fields": [
{
"type": "input",
"inputType": "text",
"label": "First Name",
"model": "firstName",
"styleClasses": "col-md-4"
},
{
"type": "input",
"inputType": "text",
"label": "Last Name",
"model": "lastName",
"styleClasses": "col-md-4"
},
{
"type": "input",
"inputType": "email",
"label": "Email",
"model": "email",
"styleClasses": "col-md-4"
}
]
}
}
```
### Data Model for List Views
Your page's data model should include an array for the list data:
```json
{
"contacts": [
{
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com"
},
{
"firstName": "Jane",
"lastName": "Smith",
"email": "jane@example.com"
}
]
}
```
### Advanced List View Example
```json
{
"type": "listrows",
"label": "Product Inventory",
"model": "products",
"min": 0,
"max": 50,
"styleClasses": "col-md-12",
"schema": {
"fields": [
{
"type": "input",
"inputType": "text",
"label": "Product Name",
"model": "name",
"styleClasses": "col-md-3",
"validator": "string"
},
{
"type": "input",
"inputType": "number",
"label": "Price",
"model": "price",
"styleClasses": "col-md-2",
"validator": "number"
},
{
"type": "input",
"inputType": "number",
"label": "Quantity",
"model": "quantity",
"styleClasses": "col-md-2",
"validator": "number"
},
{
"type": "select",
"label": "Category",
"model": "category",
"styleClasses": "col-md-3",
"values": [
{ "value": "electronics", "label": "Electronics" },
{ "value": "clothing", "label": "Clothing" },
{ "value": "books", "label": "Books" }
]
},
{
"type": "checkbox",
"label": "Active",
"model": "isActive",
"styleClasses": "col-md-2"
}
]
}
}
```
## Data Tables (`tables2`) Implementation
### Where to Add Data Tables in the IDE
1. **Open your page** in the BetterForms IDE
2. **Navigate to Page Builder tab**
3. **Search for "table"** in the snippets
4. **Copy and paste** into your page schema
### Basic Data Table Structure
```json
{
"type": "tables2",
"label": "Customer List",
"model": "customers",
"styleClasses": "col-md-12",
"columns": ["firstName", "lastName", "email", "status"],
"options": {
"filterable": true,
"sortable": true,
"pagination": {
"enabled": true,
"perPage": 10
}
}
}
```
### Data Model for Data Tables
Your page's data model should include an array of objects:
```json
{
"customers": [
{
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"status": "Active"
},
{
"firstName": "Jane",
"lastName": "Smith",
"email": "jane@example.com",
"status": "Inactive"
}
]
}
```
### Advanced Data Table with Custom Formatting
```json
{
"type": "tables2",
"label": "Order Management",
"model": "orders",
"styleClasses": "col-md-12",
"columns": ["orderNumber", "customer", "total", "status", "actions"],
"options": {
"filterable": ["customer", "status"],
"sortable": ["orderNumber", "customer", "total"],
"pagination": {
"enabled": true,
"perPage": 25
},
"texts": {
"count": "Showing {from} to {to} of {count} orders",
"filter": "Search orders:",
"filterPlaceholder": "Type to search..."
}
},
"slots": [
{
"slot": "total",
"html": "${{props.row.total}}"
},
{
"slot": "status",
"html": "{{props.row.status}}"
},
{
"slot": "actions",
"html": ""
}
]
}
```
## Row Click Actions
### Adding Row Click Functionality
```json
{
"type": "tables2",
"label": "Customer List",
"model": "customers",
"styleClasses": "col-md-12",
"columns": ["firstName", "lastName", "email"],
"actions_onRowClick": [
{
"action": "path",
"options": {
"path_calc": "'/customer-detail?id=' + this.params.row.id"
}
}
]
}
```
### Using Named Actions with Row Data
```json
{
"type": "tables2",
"label": "Customer List",
"model": "customers",
"styleClasses": "col-md-12",
"columns": ["firstName", "lastName", "email"],
"actions_onRowClick": [
{
"action": "namedAction",
"name": "viewCustomerDetail"
}
]
}
```
**In your Named Action:**
```javascript
// Access the clicked row data
let customer = action.options.params.row;
let customerId = customer.id;
let customerName = customer.firstName + ' ' + customer.lastName;
```
## Custom Column Formatting with Slots
### Adding Custom HTML to Columns
```json
{
"type": "tables2",
"label": "Product Catalog",
"model": "products",
"columns": ["name", "price", "inventory", "status", "actions"],
"slots": [
{
"slot": "price",
"html": "${{props.row.price}}"
},
{
"slot": "inventory",
"html": "{{props.row.inventory}} units"
},
{
"slot": "status",
"html": "{{props.row.status}}"
},
{
"slot": "actions",
"html": ""
}
]
}
```
### Child Row Expansion
Display additional details when a row is expanded:
```json
{
"type": "tables2",
"label": "Order List",
"model": "orders",
"columns": ["orderNumber", "customer", "total", "status"],
"slots": [
{
"slot": "child_row",
"html": "Shipping Address: {{props.row.shippingAddress}}
Notes: {{props.row.notes}}
Your first name is: {{ model.user.firstName }}
``` These examples show how the data model connects to elements on the page, allowing for dynamic interaction and updates. ### Default Data Model This editor contains the production data that will be loaded into the page's model when the page is first rendered. This data is sent to your FMS via the `onFormRequest` hook. ### Development Data Model This editor is for data used only in the BetterForms IDE. The development data is merged with the default data model during previews, allowing you to work with mock data while building the page. #### Caching and Syncing In the **Models** tab, each key can be configured under **Key Caching**: * **Cache in browser** = local storage * **Cache in tab** = session storage * **Sync with app** = keep that page model key synced with the global app model key This is configured directly in the UI (you do not need to edit JSON paths manually in this screen).  Example of a page model key (`pet`) that has **Sync with app** enabled:  For detailed app model behavior and caching notes, see [App Model](/reference/site-settings/app-model). {% hint style="warning" %} **When returning both App + Model from a hook:** If a key is set to **Sync with app** and your hook returns that same key in both `$$BF_App` and `$$BF_Model`, the **app value is authoritative** for that key. Use `$$BF_App` for the final shared value you want synced across pages. {% endhint %} # Page Integration Settings Explained The **Integration** tab allows you to manage hooks and validation settings for your page. #### **General Hooks** * **Enable onFormRequest Hook**: When enabled, this will trigger the `onFormRequest` hook script. For most pages that have data coming from the backend, this should be ticked on. The data will be integrated into the data model and will overwrite the development data (if present). For more details on hooks, you can reference this page: [Running Your First Hook](/getting-started/ide-quick-tour/first-app/creating-your-first-hook). * **Send Full Schema in Utility Hooks**: Sends the entire formSchema on hooks, providing more control but may increase transfer time on large schemas. Leave unchecked for better performance unless necessary. #### **Validation** * **Validate After Loaded**: Triggers validation routines as soon as the page is loaded. This should be enabled if any fields on the page have validators. * **Validate After Changed**: Triggers validation routines as soon as a field is changed. This should also be enabled if fields have validators to ensure data integrity. # Managing Page Info & Other Settings The **Page Info** tab contains essential settings and metadata for your page. * **UUID**: A unique identifier for the page. * **Description**: You can add a description for internal reference (not displayed to the user). * **Scoped Hook Set Name**: Specify the hook set name for scoped hooks. [Learn more about hooks](/getting-started/ide-quick-tour/3.-understanding-core-betterforms-concepts/3.1-introduction-to-hooks-and-where-to-find-them-in-the-ide). * **Authentication**: Toggle authentication requirements for the page. * **Delete Page**: Permanently delete the page. #### **Misc Form Settings** All settings for your page are defined in JSON format under Misc Form Settings. This includes: * **namedActions**: These are local scripts defined in JSON, specifying action like `onFormLoad`. While it's recommended to edit your scripts and actions in the **Actions** tab, you can also manage them directly in JSON format here. * **Style Classes**: Customize the styling for the body and page using `styleClassesBody` and `styleClassesPage`. * **Other Settings**: Control behaviors like `requestHook`, `sendFullSchema`, and `validateOnBack`. These settings correspond to options available in the **Integration** tab, such as `onFormRequest` and `Send Full Schema in Utility Hooks`. Changes made here will affect the behavior as if they were toggled in the Integration tab. # 5.3 Working with Global Scripts This page is for managing global actions within your app. You can: * Create new scripts by clicking "+ New Script" in the first panel. * The second panel shows your current script, where you can: * Add actions * Rearrange actions via drag-and-drop * Edit action details in the third panel. * Remember to save changes. * In the top-right corner, switch to the **JSON Editor** to work directly with JSON. * Next to the Save button, use the ellipsis to access the **Roll Back** option for reverting to previous versions. # 5.4 Managing App (Site) Settings & Navigation ### **Slug Names** Set the slug or path for each page. * **Slug:** A slug is the part of the URL that identifies a particular page on your site in a more readable way, typically following the domain (e.g., `subdomain.domain.com/``your-slug`). * **(internal) Path:** The full URL path, which can include the slug and any additional routing information (e.g., `subdomain.domain.com``/your-slug`). Remember to save your changes. In the ellipsis dropdown, you can: * **Redirect** to edit the page * **Precache** the page (sync data with the app) * **Add more slugs** for the page * **Preview** the page * **Delete** the page ### **Menu Schema** **Sidebar Navigation Menu Schema:** This section allows you to edit the structure of your sidebar navigation menu. The schema is represented as an array of objects, for example: ```json [{ "sectionLabel": "Menu", "subs": [{ "exact": true, "icon": "fa fa-home", "label": "Home", "path": "/" }] }] ``` * Each object within the `subs` array represents a menu item. * You can customize each menu item by: * Adding your menu text as the **label** * Specifying an **icon** to display before the text * Defining the **path** of the page the menu item links to * You can also apply custom styling with the `"styleClasses"` property and control dynamic rendering using `"visible_calc"`. * **HTML objects** can be included inside `subs` as menu items. * **Nested menus** can be created by using nested `subs` arrays to manage hierarchical navigation. # 5.5 Exploring Further: What to Learn Next You've got the basics down! Now it's time to start building out your app By now you should have been able to see how a BetterForms site can interact with your FileMaker solution. Where you go from here depends on the type of app you're building. Browse the [Common Customizations](https://github.com/DelfsEngineering/fm-betterforms/blob/master/getting-started/ide-quick-tour/4.-common-customizations-and-expanding-your-app) section for additional tips as you're getting started, in addition to the resources listed here on this page: ## Using the Examples The BetterForms interface comes with a host of example pages that can be helpful to understand how certain elements work, or can be used as a great starting template for your own pages. You can navigate to the [examples](https://app.fmbetterforms.com/#/examples) in the sidebar of the [BetterForms IDE](https://app.fmbetterforms.com/#/examples). The pages listed here will function just like your own pages except that you cannot edit them. If you want to use an example in your own app, simply duplicate it from the editor page and it will appear among your forms. ## Using Snippets The most common JSON objects that you will need are stored in the snippets section to the left of the **Schema Editor**. Click the button on the snippet to copy it to your clipboard and paste it in ## Using the Community BetterForms has a great Slack group where you can ask questions, find answers, and connect with other developers using BetterForms. If you're not already a member, request an invite after logging into the dashboard of the [BetterForms IDE](https://app.fmbetterforms.com/#/). ## Using the Forum The Klai Studio forum holds many answers to common questions. [Create an account](https://forum.fmbetterforms.com/) for free and help contribute. # Support & Resources # Getting Help # Learning JSON BetterForms is heavily dependent on JSON for nearly all of its functionality, so knowing how JSON works is crucial to understanding BetterForms. Luckily, if you're new to JSON it's easy to learn! Here are some great articles from around the web that can help your understanding: * **Learn JSON in 10 Minutes (YouTube) -**