FORM_CONVENTIONS(3)             RSX Framework Manual             FORM_CONVENTIONS(3)

NAME
    Form Conventions - Architectural patterns for SPA form loading and saving

SYNOPSIS
    // Action: Load form data
    async on_load() {
        const record = await My_Model.fetch(this.args.id);
        this.data.form_data = {
            id: record.id,
            title: record.title,
            status_id: record.status_id,
        };
    }

    // Template: Bind form data
    <Rsx_Form $data=this.data.form_data $controller="My_Controller" $method="save">

    // Controller: Single save endpoint
    #[Ajax_Endpoint]
    public static function save(Request $request, array $params = []) {
        // Validate, save, return redirect
    }

DESCRIPTION
    The RSX form system follows a traditional server-side form pattern adapted
    for SPA applications. The key principle is: one endpoint for loading form
    state, one endpoint for validating and saving. All data flows through a
    single serializable form_data object.

    This approach mirrors how forms work in traditional Laravel Blade
    applications:
    - Controller::edit() loads data and passes to view
    - Controller::update() validates and saves
    - Both methods live in the same controller, making it easy to verify
      field alignment between load and save

    In RSX SPA, this becomes:
    - Action::on_load() fetches data into this.data.form_data
    - Controller::save() receives form values and persists them
    - Both reference the same field names, ensuring alignment

DATA FLOW

    LOADING:

        1. Action.on_load() fetches data from Model or Controller
        2. Assigns structured object to this.data.form_data
        3. Template passes form_data to <Rsx_Form $data=...>
        4. Rsx_Form.on_ready() calls vals() to distribute values
        5. Each widget receives its value via val(value) setter

    SUBMITTING:

        1. User clicks submit button
        2. Rsx_Form.submit() calls vals() to gather all widget values
        3. Ajax POST sends {field: value, ...} to Controller::method
        4. Controller validates, saves, returns response
        5. On success with redirect, Rsx_Form navigates to result.redirect
        6. On validation error, Rsx_Form displays errors on fields

ACTION RESPONSIBILITIES

    The SPA Action is responsible for loading all data needed by the form.

    on_create() - Set Defaults:

        on_create() {
            // 1. Default form_data for "add" mode
            this.data.form_data = {
                title: '',
                status_id: Project_Model.STATUS_ACTIVE,
                team_members: [],    // Repeater fields start as empty arrays
            };

            // 2. Dropdown options (from model enums or static lists)
            this.data.status_options = Project_Model.status_id_enum_select();

            // 3. Mode detection
            this.data.is_edit = !!this.args.id;
        }

    on_load() - Fetch Data:

        async on_load() {
            if (!this.data.is_edit) return;  // Add mode uses defaults

            // Option A: Simple forms - use Model.fetch()
            const record = await Project_Model.fetch(this.args.id);
            this.data.form_data = {
                id: record.id,
                title: record.title,
                status_id: record.status_id,
            };

            // Option B: Complex forms - use controller endpoint
            // this.data.form_data = await Project_Controller.get_form_data({
            //     id: this.args.id
            // });
        }

    IMPORTANT: on_ready() is for UI interactions only (show/hide, focus).
    Never load data in on_ready() - it runs after vals() has already
    distributed values to widgets.

TEMPLATE PATTERN

    Standard form template structure:

        <Rsx_Form $data=this.data.form_data
                  $controller="Project_Controller"
                  $method="save">

            <% if (this.data.is_edit) { %>
                <Form_Hidden_Field $name="id" />
            <% } %>

            <Form_Field $label="Title" $required=true>
                <Text_Input $name="title" />
            </Form_Field>

            <Form_Field $label="Status">
                <Select_Input $name="status_id" $options=this.data.status_options />
            </Form_Field>

            <Form_Field $label="Team">
                <Form_Repeater $name="team_members"
                    $edit_input="Team_Member_Edit"
                    $display_input="Team_Member_Display"
                />
            </Form_Field>

            <button type="button" class="btn btn-primary"
                    @click=this.sid('form').submit()>
                Save
            </button>
        </Rsx_Form>

    Key points:
    - $data receives the form_data object from Action
    - Field $name attributes match keys in form_data
    - Hidden field for ID only shown in edit mode
    - Repeater field names match array keys in form_data

CONTROLLER RESPONSIBILITIES

    Load Endpoint (Optional):

        For complex forms with relationships, provide a dedicated load endpoint:

            #[Ajax_Endpoint]
            public static function get_form_data(Request $request, array $params = [])
            {
                $project = Project_Model::find($params['id']);

                return [
                    'id' => $project->id,
                    'title' => $project->title,
                    'status_id' => $project->status_id,
                    // Repeater data as arrays
                    'team_members' => $project->team->map(fn($t) => [
                        'user_id' => $t->user_id,
                        'role_id' => $t->role_id,
                    ])->toArray(),
                ];
            }

        This keeps the Action simple and ensures server controls the data shape.

    Save Endpoint:

        #[Ajax_Endpoint]
        public static function save(Request $request, array $params = [])
        {
            // 1. VALIDATE
            $errors = [];

            if (empty($params['title'])) {
                $errors['title'] = 'Title is required';
            }

            if (!empty($errors)) {
                return response_form_error('Please correct errors', $errors);
            }

            // 2. SAVE MAIN RECORD
            $project = !empty($params['id'])
                ? Project_Model::find($params['id'])
                : new Project_Model();

            $project->title = $params['title'];
            $project->status_id = $params['status_id'];
            $project->save();

            // 3. SYNC RELATIONSHIPS
            // Repeater sends array: [{user_id: 1, role_id: 2}, ...]
            $project->team()->detach();
            foreach ($params['team_members'] ?? [] as $member) {
                $project->team()->attach($member['user_id'], [
                    'role_id' => $member['role_id'],
                ]);
            }

            // 4. RETURN REDIRECT
            Flash_Alert::success('Saved successfully');
            return ['redirect' => Rsx::Route('Project_View_Action', $project->id)];
        }

FIELD ALIGNMENT

    The critical benefit of this pattern is ensuring field alignment between
    load and save. Keep both endpoints in the same controller file:

        // Controller file shows the complete data contract
        class Project_Controller extends Rsx_Controller_Abstract
        {
            // LOAD: These fields go INTO the form
            public static function get_form_data(...) {
                return [
                    'id' => ...,
                    'title' => ...,
                    'status_id' => ...,
                    'team_members' => [...],
                ];
            }

            // SAVE: These same fields come BACK from the form
            public static function save(...) {
                $params['id'];
                $params['title'];
                $params['status_id'];
                $params['team_members'];
            }
        }

    When adding a new field:
    1. Add to get_form_data() return array
    2. Add to save() parameter handling
    3. Add to template Form_Field
    4. Add to on_create() defaults (for add mode)

    All four locations are easily verified by searching the field name.

REPEATER FIELDS

    Repeater fields collect multiple values into an array.

    Simple Repeaters (array of IDs):

        // form_data
        this.data.form_data = {
            client_ids: [1, 5, 12],
        };

        // Controller receives
        $params['client_ids']  // [1, 5, 12]

        // Sync
        $project->clients()->sync($params['client_ids'] ?? []);

    Complex Repeaters (array of objects):

        // form_data
        this.data.form_data = {
            team_members: [
                {user_id: 1, role_id: 2},
                {user_id: 5, role_id: 1},
            ],
        };

        // Controller receives
        $params['team_members']  // [{user_id: 1, role_id: 2}, ...]

        // Sync with pivot data
        $project->team()->detach();
        foreach ($params['team_members'] ?? [] as $member) {
            $project->team()->attach($member['user_id'], [
                'role_id' => $member['role_id'],
            ]);
        }

KEY PRINCIPLES

    1. SERIALIZABLE STATE
       form_data must be JSON-serializable. No model instances, no
       functions, no circular references. Plain objects and arrays only.

    2. SINGLE SUBMIT
       One Ajax call sends all form data. No per-field saves, no partial
       updates. The form is atomic - it succeeds or fails as a unit.

    3. SERVER SYNCS RELATIONSHIPS
       Controller receives arrays from repeaters and syncs them server-side.
       Delete removed items, add new items, update changed items.

    4. ACTION LOADS, FORM DISTRIBUTES
       Action's on_load() prepares form_data as a plain object.
       Rsx_Form's on_ready() distributes values to widgets via vals().
       Widgets never know where data came from.

    5. CONTROLLER ALIGNMENT
       Keep get_form_data() and save() in the same file. This makes it
       trivial to verify field names match between load and save.

VALIDATION RESPONSES

    Success with redirect:

        return ['redirect' => Rsx::Route('View_Action', $id)];

    Validation errors:

        return response_form_error('Please correct errors', [
            'title' => 'Title is required',
            'email' => 'Invalid email format',
        ]);

    Rsx_Form automatically displays field errors below each Form_Field.

COMMON MISTAKES

    Loading data in on_ready():

        // WRONG - on_ready() runs AFTER form already populated
        on_ready() {
            this.data.form_data = await Controller.get_data();
        }

        // CORRECT - on_load() runs BEFORE render
        async on_load() {
            this.data.form_data = await Controller.get_data();
        }

    Non-serializable form_data:

        // WRONG - Model instance is not serializable
        this.data.form_data = await Project_Model.fetch(id);

        // CORRECT - Extract plain object
        const record = await Project_Model.fetch(id);
        this.data.form_data = {
            id: record.id,
            title: record.title,
        };

    Field name mismatch:

        // form_data uses 'name'
        this.data.form_data = { name: 'Test' };

        // Template uses 'title' - VALUE WILL BE EMPTY
        <Form_Field $label="Title">
            <Text_Input $name="title" />

SEE ALSO
    forms_and_widgets(3), jqhtml(3), ajax(3)

RSX Framework                    December 2024             FORM_CONVENTIONS(3)