FetchIt — Submit Forms Without Reloading

FetchIt is a modern, lightweight component for MODX Revolution designed for submitting and processing forms using the native Fetch API. It replaces legacy solutions (like AjaxForm), enabling forms to work without page reloads and without relying on heavy libraries like jQuery.

Why choose FetchIt?

• No dependencies. The component runs on pure JavaScript. You don’t need to include jQuery, which speeds up site loading and improves PageSpeed.
• Lightweight. The script weighs only ~5 KB and is included with the defer attribute, without blocking page rendering.
• Flexibility. Easily integrates with any CSS frameworks (Bootstrap, Tailwind) and JS notification libraries (Notyf, SweetAlert2).
• Easy migration. The functionality is very similar to AjaxForm + FormIt, making the transition intuitive.

Installation

FetchIt is available for free installation via the “Package Installer” in the MODX admin panel. Main sources:

• Official MODX repository.
• Add-on store modstore.pro.
• GitHub repository (for manual building).

Quick Start

Running the form requires just two steps: preparing the HTML markup (chunk) and calling the snippet on the page.

1. Creating a form chunk

Create a chunk (for example, tpl.MyForm) with the following markup. Please note the following important attributes:

• Fields (input, textarea) must have a name attribute.
• The submit button must have type="submit".
• To display validation errors, use spans with the data-error="field_name" attribute.

<form action="[[~[[*id]]]]" method="post">
    <div class="form-group">
        <label for="name">Имя:</label>
        <input type="text" name="name" id="name" value="[[+fi.name]]" class="form-control" required>
        <!-- Сюда FetchIt вставит текст ошибки при валидации -->
        <span class="error" data-error="name">[[+fi.error.name]]</span>
    </div>

    <div class="form-group">
        <label for="email">Email:</label>
        <input type="email" name="email" id="email" value="[[+fi.email]]" class="form-control" required>
        <span class="error" data-error="email">[[+fi.error.email]]</span>
    </div>

    <div class="form-group">
        <label for="message">Сообщение:</label>
        <textarea name="message" id="message" class="form-control" required>[[+fi.message]]</textarea>
        <span class="error" data-error="message">[[+fi.error.message]]</span>
    </div>

    <button type="submit" class="btn btn-primary">Отправить</button>
    
    <!-- Сообщения об успехе/ошибке (опционально) -->
    [[+fi.success:is=`1`:then=`<div class="alert alert-success">[[+fi.successMessage]]</div>`]]
    [[+fi.validation_error:is=`1`:then=`<div class="alert alert-danger">[[+fi.validationErrorMessage]]</div>`]]
</form>

2. Calling the Snippet

Place a call to FetchIt on the page where the form should be. Inside FetchIt, we call the standard FormIt for email processing and validation.

Important! The snippet must be called uncached (with the exclamation point [[!FetchIt]]).

[[!FetchIt?
    &snippet=`FormIt`
    &form=`tpl.MyForm`
    &hooks=`email`
    &emailSubject=`Новое сообщение с сайта`
    &emailTo=`info@mysite.com`
    &validate=`name:required,email:required:email,message:required`
    &validationErrorMessage=`Пожалуйста, исправьте ошибки в форме!`
    &successMessage=`Спасибо! Ваше сообщение успешно отправлено.`
]]

Snippet Parameters

FetchIt accepts its own parameters to customize frontend behavior, and passes all unknown parameters to the snippet handler (FormIt by default).

JavaScript API and Events

FetchIt provides a powerful API for interacting with a form on the client. You can intercept the submission process, modify data, or display custom notifications.

Main Events

• fetchit:before — Fires before submitting. A great place for additional JavaScript validation or adding data to FormData.
• fetchit:success — Fires upon a successful response from the server (success: true).
• fetchit:error — Fires upon an error (validation failed or a server error).

Example 1: Adding data before submitting

document.addEventListener('fetchit:before', (e) => {
    const { form, formData } = e.detail;
    // Добавляем произвольное поле, которого нет в верстке
    formData.append('page_title', document.title);
    console.log('Форма отправляется...');
});

Пример 2: Всплывающие уведомления (Notyf)

FetchIt “из коробки” не навязывает стили уведомлений. Вы можете подключить любую библиотеку, например, Notyf.

// Подключите JS и CSS библиотеки Notyf в шаблоне заранее
const notyf = new Notyf();

document.addEventListener('fetchit:success', (e) => {
    const { response } = e.detail;
    // response.message приходит из параметра &successMessage
    notyf.success(response.message || 'Форма успешно отправлена!');
});

document.addEventListener('fetchit:error', (e) => {
    const { response } = e.detail;
    // response.message содержит &validationErrorMessage или ошибку хука
    notyf.error(response.message || 'Произошла ошибка.');
});

Processing with a Custom Snippet

If you need to process data more complex than FormIt allows, you can specify your snippet in the &snippet parameter. The $FetchIt object is available within it for returning standardized responses.

Call:

[[!FetchIt?
    &form=`myForm`
    &snippet=`myCustomHandler`
]]

Сниппет myCustomHandler:

<?php
// Fetching data
$name = $_POST['name'] ?? '';

// Basic validation
if (empty($name)) {
// Returning an error. The second argument is an array of field errors to highlight.
return $FetchIt->error('Validation error', [
'name' => 'The name field is required'
]);
}

// Some logic (writing to the database, API request...)

// Returning success
return $FetchIt->success('Everything went fine!', [
'custom_data' => 'Some data for JS'
]);

Working with files

FetchIt automatically handles file uploads. You don’t need to manually assemble the FormData object or specify specific headers—the component will do it automatically.

To send attachments:

1. Add the enctype="multipart/form-data" attribute to the form tag.
2. Add the <input type="file" name="attachment"> field.
3. In the snippet call, don’t forget to specify the attachment hook, for example, the standard email (FormIt will automatically process the files and attach them to the email if the field name matches the settings).

<form action="[[~[[*id]]]]" method="post" enctype="multipart/form-data">
<!-- Other fields --> 
<div class="form-group"> 
<label>Attach file:</label> 
<input type="file" name="file" class="form-control-file"> 
</div> 
<button type="submit">Submit</button>
</form>

Migrating from AjaxForm

If you’re used to using AjaxForm, switching to FetchIt will be painless. The main differences concern JavaScript events.

Example: Integration with SweetAlert2

You can use beautiful modal windows instead of the standard alert() or Notyf. Example of connecting SweetAlert2:

// Handling a successful submission
document.addEventListener('fetchit:success', (e) => {
const { response } = e.detail;

Swal.fire({
title: 'Great!',
text: response.message,
icon: 'success',
confirmButtonText: 'Close'
});
});

// Error Handling
document.addEventListener('fetchit:error', (e) => {
const { response } = e.detail;

Swal.fire({
title: 'Error!',
text: response.message || 'Check that the fields are filled in correctly',
icon: 'error',
confirmButtonText: 'OK'
});
});

Conclusion

FetchIt is the “gold standard” for forms in modern MODX. It frees your site from legacy jQuery, speeds up page load times, and gives the developer full control over the data submission process via a convenient JS API.

Use it for contact forms, callback forms, calculators, and any other interactive elements where speed and flexibility are important.