📄 pbForm: Fast and Reliable Form Handling

pbForm is a ready-to-use class for convenient client-side AJAX form validation and submission. It integrates with pbFetch and automatically handles errors, messages, and redirects.

✨ Key Features

• Intercepts form submission: Prevents default submit behavior and sends data via pbFetch using FormData.
• Handles field errors: If the API returns validation errors (e.g., { errors: { email: "Invalid email" } }), it adds CSS classes to fields and displays error messages.
• Supports custom elements: Use data-error="name" and data-custom="name" for flexible markup.
• Auto-clears errors: Removes old errors on re-entry or after successful submission.
• Redirect support: Automatically redirects users if the server returns a redirect response.
• Customizable CSS classes: Configure error and message classes via constructor options or system settings.

⚙️ How to Use

1️⃣ Add pb-form Attribute to Form

<form action="/api/register" method="POST" pb-form>  
  <input name="email">  
  <span data-error="email"></span>  

  <button type="submit">Submit</button>  
</form>

2️⃣ Initialize the Class

With pageblocks_load_scripts enabled, initialization is automatic. For manual setup:

<script src="/assets/components/pageblocks/js/web/pb.fetch.v280.js"></script>  
<script src="/assets/components/pageblocks/js/web/pb.form.v280.js"></script>  
<script>  
  pbFetch.init();  
  new pbForm('form[pb-form]', {  
    errorClass: 'is-invalid',  
    errorMessageClass: 'invalid-feedback'  
  });  
</script>

Options:

• errorClass: CSS class for invalid fields.
• errorMessageClass: CSS class for error message blocks.

Defaults are pulled from system settings:

• pageblocks_field_error – Field error class (default: is-invalid).
• pageblocks_field_msg_error – Error message class (default: invalid-feedback).

3️⃣ Real-World Example with Bootstrap 5

<form class="border rounded-4 p-5" action="/login" method="post" pb-form>  
  <input type="hidden" name="_token" value="{csrf_token}">  
  <input type="hidden" name="honeypot" value="">  

  {if $success_message}  
    <p class="text-center text-success" pb-message>{$success_message}</p>  
  {elseif $error_message}  
    <p class="text-center text-danger text-error" pb-message>{$error_message}</p>  
  {else}  
    <p class="text-center d-none" pb-message></p>  
  {/if}  

  <div class="form-group mb-3">  
    <label for="username" class="mb-2">Username</label>  
    <input type="text"  
           name="username"  
           id="username"  
           class="form-control{if $errors.username} is-invalid{/if}"  
           value="{$old_input.username}">  
    <span class="invalid-feedback" data-error="username">{$errors.username}</span>  
  </div>  

  <div class="form-group mb-3">  
    <label for="password" class="mb-2">Password</label>  
    <input type="password"  
           name="password"  
           id="password"  
           class="form-control{if $errors.password} is-invalid{/if}">  
    <span class="invalid-feedback" data-error="password">{$errors.password}</span>  
  </div>  

  <button type="submit" class="btn btn-dark w-100">  
    <span class="spinner spinner-border spinner-border-sm" 
          pb-spinner 
          aria-hidden="true" 
          style="display:none">
    </span>  
    <span role="status">Login</span>  
  </button>  
</form>

🔍 Key Details

• ✅ Uses <p pb-message> for general success/error messages.
• ✅ Field errors leverage data-error="name" and CSS classes from system settings (field_error and field_msg_error).
• ✅ Submit button auto-disables during requests, with a spinner (via pb-spinner) for loading indication.

🔧 Custom Forms with Alternate Classes

Initialize forms with custom selectors and error classes:

new pbForm('.custom-ajax-form', {  
  errorClass: 'has-error',  
  errorMessageClass: 'field-error'  
});

🗂 Default System Settings

Setting	Default Value	Description
pageblocks_field_error	is-invalid	CSS class for invalid fields
pageblocks_field_msg_error	invalid-feedback	CSS class for error message blocks
pageblocks_msg_success	text-success	Success message classes
pageblocks_msg_error	text-error,text-danger	Error message classes
pageblocks_hidden_class	d-none	Class for hiding message blocks

✅ Summary

pbForm provides a simple yet flexible foundation for AJAX forms with auto-validation and error handling. Just add the pb-form attribute, configure system settings, and your form works without extra JavaScript.