Record Behaviors: API Reference

Record Behavior scripts interact with the platform through a secure, well-defined set of APIs. These APIs are provided as a single object to your script's default export, allowing you to destructure only the tools you need. They are the only bridge from the secure WASM sandbox to the application and are guaranteed to work identically on both the client and the server.

export default async ({ $form, $db, $user, $ai }) => {
  // Your logic here...
}

The $form API

The $form object is your primary tool for all form interactions. It allows you to read form state, get and set field values, and dynamically change a field's appearance and behavior.

Form-Level Properties & Methods

Property / Method	Description
$form.event	(Read-only) A string indicating the current event: 'load', 'update', or 'submit'.
$form.updatedFields	(Read-only) In an update event, this is an array of field names that were changed in the latest batch of user input that triggered this execution. Due to the platform's intelligent execution model, this may contain multiple fields.
$form.record()	Returns an object containing the current values of all fields in the form. Note: In an update event, this excludes the value of the currently active freeform field to prevent processing incomplete data.
$form.updated(...fieldNames)	In an update event, returns true if any of the specified fields were part of the latest batch of changes that triggered the event. Use this to write highly performant UI logic.
$form.error(message | null)	Sets or clears a form-level error message. An error set during a submit event will block the save operation.
$form.info(message | null)	Sets or clears a form-level informational message.

Field-Level API

Call $form('fieldName') to get a fluent API object for a specific field. All methods are chainable.

Method	Description
.value()	Returns the current value of the field.
.set(newValue)	Sets a new value for the field.
.visible(boolean)	Shows (true) or hides (false) the field.
.required(boolean)	Makes the field mandatory (true) or optional (false).
.editable(boolean)	Makes the field editable (true) or read-only (false).
.error(message | null)	Sets or clears a validation error message displayed directly below the field.
.info(message | null)	Sets or clears an informational message displayed below the field.

Example Usage:

export default async ({ $form }) => {
  // Get the value of the 'status' field
  const status = $form('status').value();

  // If the status is set to 'Completed', set the 'completed_at' date
  // to the current time and make the field read-only.
  if (status === 'Completed' && $form.updated('status')) {
    $form('completed_at')
      .set(new Date().toISOString())
      .editable(false);
  }
}

---

The $db API

The $db object provides a secure, read-only GraphQL interface to your database. This is the only way to fetch data from within a script. It works in all events on both client and server.

The Simple Advantage: Security by Design

By restricting database access to read-only GraphQL queries, the platform architecturally prevents Record Behaviors from making unauthorized or arbitrary mutations, ensuring your core business logic remains the single source of truth for writes.

• .query(queryString, variables): Executes a GraphQL query.
  • queryString: A string containing the GraphQL query.
  • variables: An optional object of variables for the query.
  • Returns: A promise that resolves to the query result.

Example:

export default async ({ $form, $db }) => {
  // When a product is selected in an order form, fetch its price and tax rate.
  if ($form.event === 'update' && $form.updated('product_id')) {
    const productId = $form('product_id').value();

    if (productId) {
      const { product } = await $db.query(
        `query getProduct($id: ID!) {
          product: com_example_ecommerce__product(id: $id) {
            price
            tax_rate
          }
        }`,
        { id: productId }
      );

      if (product) {
        $form('unit_price').set(product.price);
        $form('tax_rate').set(product.tax_rate);
      }
    }
  }
}

---

The $user API

The $user object provides read-only access to the current authenticated user's information. It is available in all events on both client and server.

Available Properties:

Property	Type	Description
id	string	The unique ID of the user.
name	string	The full name of the user.
email	string	The email of the user.

Example:

export default async ({ $form, $user }) => {
  // On a new record, if the 'assignee_id' field is empty,
  // default it to the current user.
  if ($form.event === 'load' && !$form('assignee_id').value()) {
    console.log(`Assigning task to user: ${$user.name} (${$user.id})`);
    $form('assignee_id').set($user.id);
  }
}