Milk Admin

FormBuilder Fetch Methods Reference

Revision: 2025/12/11

Complete reference for FormBuilder methods that enable fetch-based form handling without page reloads.

Quick Links:

Quick Reference Table

Method Purpose Returns
activeFetch() Enables fetch mode for form submission self
asOffcanvas() Sets response type to offcanvas panel self
asModal() Sets response type to modal dialog self
asDom($id) Sets response type to DOM element self
setTitle($new, $edit) Sets dynamic titles for new/edit modes self
dataListId($id) Enables automatic table reload on success self
size($size) Sets modal/offcanvas size self
getResponse() Generates complete JSON response array

Method Details

activeFetch()

Converts form submission and action buttons into fetch calls. Without this method, the page will reload on submit.

FormBuilder::create($model, $page)
    ->activeFetch()  // Enables fetch mode
    ->getForm();

Effect:

  • Form submission becomes AJAX request
  • Submit buttons trigger fetch calls
  • Response must be JSON

asOffcanvas()

Configures the response to display the form in an offcanvas panel (sliding panel from the right).

FormBuilder::create($model, $page)
    ->activeFetch()
    ->asOffcanvas()  // Display in offcanvas
    ->getResponse();

JSON Response Key: offcanvas_end

asModal()

Configures the response to display the form in a centered modal dialog.

FormBuilder::create($model, $page)
    ->activeFetch()
    ->asModal()  // Display in modal
    ->getResponse();

JSON Response Key: modal

asDom($id)

Configures the response to render the form directly into a DOM element.

FormBuilder::create($model, $page)
    ->activeFetch()
    ->asDom('contentWrapper')  // Render in element with ID
    ->getResponse();

Parameters:

  • $id - The ID of the target DOM element

JSON Response Key: element

setTitle($new, $edit = null)

Sets dynamic titles that change automatically based on whether you're creating or editing a record.

FormBuilder::create($model, $page)
    ->setTitle('New Recipe', 'Edit Recipe')  // Different titles
    ->getResponse();

Parameters:

  • $new - Title when creating a new record
  • $edit - Title when editing (optional, defaults to $new)

Auto-detection: The system checks if the record has an ID to determine which title to use.

dataListId($id)

Enables automatic table reload when an action (save/delete) completes successfully.

FormBuilder::create($model, $page)
    ->dataListId('idTableRecipes')  // Table ID to reload
    ->getResponse();

Parameters:

  • $id - The ID of the table to reload

Behavior: When set and action succeeds, automatically adds list => ['id' => ..., 'action' => 'reload'] to response and closes offcanvas/modal.

size($size)

Sets the size of the offcanvas panel or modal dialog.

FormBuilder::create($model, $page)
    ->asOffcanvas()
    ->size('lg')  // or 'sm', 'xl', 'fullscreen'
    ->getResponse();

Available Sizes:

  • sm - Small
  • lg - Large
  • xl - Extra large
  • fullscreen - Full screen

getResponse()

Generates the complete JSON response array based on all configured options.

$response = FormBuilder::create($model, $page)
    ->activeFetch()
    ->asOffcanvas()
    ->setTitle('New Item', 'Edit Item')
    ->dataListId('myTable')
    ->size('lg')
    ->getResponse();  // Returns array

Response::json($response);

Returns: Array with keys:

  • executed_action - Name of executed action (save, delete, etc.)
  • action_success - Whether action succeeded
  • list - Table reload instructions (if dataListId set and success)
  • offcanvas_end / modal / element - Display configuration

Complete Example

A typical fetch-based form implementation:

#[RequestAction('edit')]
public function recipeEdit() {
    $response = ['page' => $this->page, 'title' => $this->title];

    // Build form with fetch methods
    $response = array_merge($response, FormBuilder::create($this->model, $this->page)
        ->activeFetch()                              // Enable fetch mode
        ->asOffcanvas()                              // Display in offcanvas
        ->setTitle('New Recipe', 'Edit Recipe')      // Dynamic titles
        ->dataListId('idTableRecipes')               // Auto-reload table
        ->size('lg')                                  // Large size
        ->getResponse());                            // Generate response

    // Send JSON response
    Response::json($response);
}

Generated JSON Response:

{
    "page": "recipes",
    "title": "My Recipes",
    "executed_action": null,
    "action_success": false,
    "offcanvas_end": {
        "title": "New Recipe",      // or "Edit Recipe"
        "action": "show",            // or "hide" if success
        "body": "
...
",
        "size": "lg"
    }
}

After successful save:

{
    "executed_action": "save",
    "action_success": true,
    "list": {
        "id": "idTableRecipes",
        "action": "reload"
    },
    "offcanvas_end": {
        "title": "Edit Recipe",
        "action": "hide",
        "body": "
...
",
        "size": "lg"
    }
}

Method Chaining

All methods except getResponse() return self, enabling fluent method chaining:

FormBuilder::create($model, $page)
    ->activeFetch()                    // Returns self
    ->asOffcanvas()                    // Returns self
    ->setTitle('New', 'Edit')          // Returns self
    ->dataListId('myTable')            // Returns self
    ->size('lg')                       // Returns self
    ->getResponse();                   // Returns array

Common Patterns

Pattern 1: Offcanvas with Auto-Reload

->activeFetch()
->asOffcanvas()
->setTitle('New Item', 'Edit Item')
->dataListId('myTableId')
->getResponse()

Pattern 2: Modal with Custom Size

->activeFetch()
->asModal()
->setTitle('Add User', 'Edit User')
->size('xl')
->getResponse()

Pattern 3: DOM Element Replacement

->activeFetch()
->asDom('formContainer')
->setTitle('Form Title')
->getResponse()

Related Documentation