Form Handling

This document describes the form handling system in the Hotelaro codebase. It covers the mechanisms for AJAX form submission, CSRF protection, client-side validation, and notification systems (using toastr/Toastify). The focus is on the reusable scripts and patterns that enable secure, user-friendly, and consistent form interactions across the application.

For information about file uploads and asset management, see File Management. For details on utility functions and shared helpers, see Common Helpers.

Purpose and Scope

The form handling system provides:

A standardized way to submit forms asynchronously (AJAX) without page reloads.
Built-in CSRF (Cross-Site Request Forgery) protection for all form submissions.
User feedback via notification popups (success, error, info, warning) using the toastr/Toastify system.
Support for dynamic UI updates, such as button state changes and redirecting after successful actions.

This system is used throughout both the admin backend and public-facing website for login, registration, booking, configuration, and other interactive forms.

High-Level Flow

Diagram: "Form Handling System Overview"

Core Components

1. AJAX Form Submission

AJAX form submission is handled by JavaScript/jQuery scripts that intercept the form's submit event, prevent the default browser behavior, and send the form data to the server using $.ajax.

File: app/Views/common_script/formsubmit.php

File: inc/themes/backend/Admin/Views/submitit.php

Key Features:

Uses FormData to serialize form fields, supporting file uploads.
Appends CSRF token to the request.
Updates the submit button text to indicate progress.
Handles server responses to update the UI and notify the user.

Table: Main AJAX Form Handling Scripts

File Path	Usage Context	Key Elements Handled
app/Views/common_script/formsubmit.php	General forms	CSRF, toastr, redirects
inc/themes/backend/Admin/Views/submitit.php	Admin backend forms	toastr, redirects

2. CSRF Protection

All AJAX form submissions include CSRF tokens to prevent cross-site request forgery. The token is:

Appended to the FormData payload.
Sent as a custom header (X-CSRF-TOKEN).
Refreshed on each response (the new token is set in a hidden input for the next request).

Relevant Code:

csrf_hash() and csrf_token() are used to generate and append the token.
The server returns a new CSRF token in the response, which is updated in the form.

3. Notification System (toastr/Toastify)

User feedback is provided via notification popups using a custom wrapper around Toastify.js, exposed as a toastr object with methods for different message types.

File: inc/themes/backend/Admin/Views/toster.php

Key Features:

toastr.success(message), toastr.error(message), toastr.warning(message), toastr.info(message)
Customizable appearance and icons.
Used in AJAX form handlers to display server response messages.

Table: Toastr Notification Methods

Method	Description
toastr.success(msg)	Show success notification
toastr.error(msg)	Show error notification
toastr.warning(msg)	Show warning notification
toastr.info(msg)	Show info notification

4. UI State Management

The form handling scripts update the UI based on the server response:

Change button text to indicate loading or completion.
Redirect the user if locationChange is present in the response.
Reset button text and CSRF token after completion.

Relevant Code:

Button state changes
Redirect logic

Mapping: System Names to Code Entities

Diagram: "Form Handling Code Entity Map"

Example: AJAX Form Submission Lifecycle

Diagram: "AJAX Form Submission Lifecycle"

"toastr (toster.php)"
"Server (Controller)"
"Browser JS (formsubmit.php)"
"User"
"toastr (toster.php)"
"Server (Controller)"
"Browser JS (formsubmit.php)"
"User"
"Submit form"
"POST form data + CSRF"
"JSON {status, message, new_csrf_token, locationChange}"
"Show notification"
"Update button, redirect if needed"

Error Handling and Validation

If the server returns an error status, the error message is shown via toastr.error.
If the AJAX request itself fails (e.g., network error), a generic error is shown and the button is reset.
Client-side validation can be added before the AJAX call, but is not included in the provided scripts.

Summary Table: Key Code Entities

Entity / Symbol	Description	File(s)
formsubmit.php	General AJAX form handler	app/Views/common_script/formsubmit.php
submitit.php	Admin-specific AJAX form handler	inc/themes/backend/Admin/Views/submitit.php
toster.php	Toastr/Toastify notification system	inc/themes/backend/Admin/Views/toster.php
csrf_hash(), csrf_token()	CSRF token generation (server-side)	app/Views/common_script/formsubmit.php

Integration Points

Backend Controllers: Must return JSON responses with status, message, new_csrf_token, and optionally locationChange.
Frontend Forms: Should use the provided scripts for consistent behavior and security.
Notification System: All user feedback should use the toastr interface for consistency.