+375 29 606 22 23
Главная / Дополнения для modx / Капча для ajaxForm

scxcaptchaAjaxForm — числовая капча для MODX: AjaxForm, FormIt и FetchIt

Лёгкая и быстрая капча для MODX, работает с AjaxForm, FormIt и FetchIt. Простой код, одноразовые токены. Устанавливается в один вызов.

  • v1.0.1
  • stable
  • MIT
Скачать с сайта Установить из Modstore Документация docs.modx.pro GitHub
Главная / Дополнения для modx / Капча для ajaxForm

Почему это удобно

🔢

Неблокирующая числовая CAPTCHA

Пять цифр, легко читаются человеком, не мешают заполнению формы и надёжно защищают от автоматических отправок.

⚙️

Совместима с AjaxForm, FormIt и FetchIt

Работает через стандартные хуки MODX — AjaxForm, FormIt и теперь FetchIt. Никаких конфликтов с другими дополнениями и сторонними фронтенд-скриптами.

🚀

Простая интеграция

Установите пакет и вставьте вызов

Нажмите «Обновить», чтобы получить картинку
в форму — готово. Поддерживается как обычная отправка, так и динамические формы.

🧠

Умная защита

Проверка honeypot-поля, времени заполнения формы, одноразовые токены и защита от повторных отправок — всё работает автоматически.

🎨

Кастомизация внешнего вида

Меняйте стили классов .scx-* под свой дизайн или подключайте scx.css/scx.js глобально. Поддерживается inline-режим для модальных и динамических форм.

🧩

Работа с модальными и динамическими формами

Используйте includeAssets="inline" — скрипты и стили будут подключаться прямо внутри формы. Подходит для всплывающих окон, чанков и подгружаемых фрагментов.

🔄

Автоматическая перерисовка и удобный UX

После успешной или неудачной отправки капча перерисовывается автоматически, без ошибок «Bad token». Поддерживает события fetchit:success, fetchit:error и fetchit:reset.

Демо

tpl.demo.scx

Этот пример демонстрирует подключение капчи в чанк формы и не отправляет данные — он нужен только для показа работы капчи.
Чтобы сделать рабочее демо, подключайте AjaxForm со сниппетом FormIt, как показано в «Быстром старте». 

// лог появится здесь

Совместимость и требования

MODX: 2.8+ / 3.x
PHP: 7.4+ (рекомендуется 8.x)
Зависимости:
  • GD - Необходим для рендера изображения капчи. Поддерживается в большинстве PHP-хостингов. imagecreate + TrueType
  • TrueType font - Шрифт для прорисовки цифр. Идёт в комплекте с пакетом. DejaVuSansMono.ttf
  • PHP - Рекомендуется PHP 8.x. Используются современные функции (password_hash, строгие типы и др.). 7.4+
Работает с:
  • AjaxForm - Полная поддержка стандартного процесса отправки через AjaxForm.
  • FormIt - Работает как обычный хук FormIt. Нужен только scxCaptchaAjaxFormHook.
  • FetchIt - Поддерживается с версии 1.0.1. Капча автоматически перерисовывается по событиям fetchit:success, fetchit:error, fetchit:reset
Проверено на версиях: последние релизы

Установка

Скачайте архив транспорт-пакета дополнения версии 1.0.1 с этой страницы и сохраните его на компьютер.

Загрузите скачанный файл в директорию:
/core/packages/your-package.transport.zip

/core/packages/your-package.transport.zip

-- Зайдите в панель MODX: Приложения → Установщик
-- Нажмите на птичку   кнопки ЗАГРУЗИТЬ ПАКЕТЫ , в появившемся меню выбирите ИСКАТЬ ПАКЕТЫ ЛОКАЛЬНО
-- В появившемся модальном окне нажмите ДА
-- В списке ниже выберите дополнение scxcaptchaajaxform и нажмите УСТАНОВИТЬ
-- Далее следуйсте инструкциям по установке

Убедитесь, что существует файл TTF-шрифта:
assets/components/scxcaptchaajaxform/fonts/DejaVuSansMono.ttf
Если его нет — будет использован bitmap-фолбэк (капча всё равно работает).

assets/components/scxcaptchaajaxform/fonts/DejaVuSansMono.ttf

Добавьте вызов капчи в вашу форму некэшируемо и подключите хук проверки.

// вставить в чанк с формой

[[!ScxCaptchaAjaxForm]]


// добавить хук ScxCaptchaAjaxFormHook в снипет AjaxForm

[[!AjaxForm?
  &snippet=`FormIt`
  &form=`tpl.AjaxForm.example`
  &hooks=`ScxCaptchaAjaxFormHook, email`
  &validate=`name:required, email:required:email, scx_code:required`
]]


// добавить хук ScxCaptchaAjaxFormHook в снипет Fetchit

[[!Fetchit?
  &snippet=`FormIt`
  &form=`tpl.AjaxForm.example`
  &hooks=`ScxCaptchaAjaxFormHook, email`
  &validate=`name:required, email:required:email, scx_code:required`
]]

Если вы хотите подключить стили и скрипт для всех форм сразу, поместите эти теги в шаблон сайта (например в <head>).

<link rel="stylesheet" href="/assets/components/scxcaptchaajaxform/css/scx.css">
<script src="/assets/components/scxcaptchaajaxform/js/scx.js"></script>

Если форма открывается в модальном окне или подгружается динамически — используйте inline-режим.
Он вставляет стили и JS прямо в форму.

[[ScxCaptchaAjaxForm?
    &includeAssets=`inline`
]]

Быстрый старт

Минимальный пример интеграции

// вставить в чанк с формой
[[!ScxCaptchaAjaxForm]]

<!-- AjaxForm -->
[[!AjaxForm?
    &snippet=`FormIt`
    &form=`tpl.demo.scx`
    &hooks=`scxCaptchaAjaxFormHook,email`
    &validate=`name:required, email:required:email, scx_code:required`
]]


<!-- FormIt (чистый вариант) -->
[[!FormIt?
    &form=`tpl.demo.scx`
    &hooks=`scxCaptchaAjaxFormHook,email`
    &validate=`name:required, email:required:email, scx_code:required`
]]


<!-- FetchIt (динамическая форма) -->
<form data-fetchit>
    [[!ScxCaptchaAjaxForm? &includeAssets=`inline`]]

    <input type="text" name="name" placeholder="Имя">
    <input type="email" name="email" placeholder="E-mail">

    <button type="submit">Отправить</button>
</form>

Капча вставляется некэшируемо в чанк формы ([[!ScxCaptchaAjaxForm]]).
Пример работает с AjaxForm, FormIt и FetchIt. В inline-режиме капча подходит для модальных и динамически подгружаемых форм.

Настройки и параметры

Имя
Тип
По умолчанию
Описание
ttl
integer
Время жизни токена в секундах. Используйте для увеличения/уменьшения срока действия капчи. [[ScxCaptchaAjaxForm? &ttl=`900`]]
includeAssets
list
Как подключать CSS/JS: head — в (по умолчанию); inline — вернуть вместе с HTML формы (для модалок, AJAX, FetchIt); none — не подключать ассеты автоматически. [[ScxCaptchaAjaxForm? &includeAssets=`inline`]] [[ScxCaptchaAjaxForm? &includeAssets=`none`]]
render
boolean
Возвращать ли HTML-блок капчи: 1 — да (по умолчанию); 0 — вернуть только ассеты без вывода HTML. Полезно, если капча выводится вручную или JS-методом. [[ScxCaptchaAjaxForm? &render=`0`]]
Имя
Описание
Пример
scx_hp
Honeypot — поле-ловушка, должно оставаться пустым.
scx_ts
Время рендера формы в миллисекундах. Защита от моментальной отправки формы (>= 300 мс).
scx_code
Ответ пользователя — пятизначный код, который он видит на изображении.
scx_token
Скрытый токен текущей капчи. Используется для валидации и одноразовости кода.
Ключ
Тип
По умолчанию
Описание
no_system_settings
string
Пакет scxcaptchaAjaxForm не добавляет собственных системных настроек — всё настраивается параметрами сниппета ScxCaptchaAjaxForm.

Примеры использования

Минимальная интеграция на статичной странице. Ассеты подключаются автоматически в (по умолчанию).

[[!ScxCaptchaAjaxForm]]

[[!AjaxForm?
    &snippet=`FormIt`
    &form=`tpl.AjaxForm.example`
    &hooks=`scxCaptchaAjaxFormHook,email`
]]

Форма открывается во всплывающем окне или подгружается по AJAX. Стили и скрипт капчи возвращаются вместе с HTML формы.

[[!ScxCaptchaAjaxForm?
    &includeAssets=`inline`
]]

[[!AjaxForm?
    &snippet=`FormIt`
    &form=`tpl.AjaxForm.modal`
    &hooks=`scxCaptchaAjaxFormHook,email`
]]

Подключаем CSS/JS капчи, но не выводим HTML-блок. Полезно, если разметка капчи вставляется вручную или через отдельный чанк.

[[!ScxCaptchaAjaxForm?
    &render=`0`
]]

Ассеты подключаются в шаблоне сайта, а сниппет отвечает только за HTML капчи. Удобно, когда капча используется на многих страницах.

<!-- В шаблоне (head) -->
<link rel="stylesheet" href="/assets/components/scxcaptchaajaxform/css/scx.css">
<script src="/assets/components/scxcaptchaajaxform/js/scx.js"></script>

<!-- В чанке формы -->
[[!ScxCaptchaAjaxForm?
    &includeAssets=`none`
]]

Форма отправляется через FetchIt. Капча автоматически перерисовывается по событиям fetchit:success, fetchit:error и fetchit:reset.

<form data-fetchit>
    <!-- Поля формы -->

    [[!ScxCaptchaAjaxForm?
        &includeAssets=`inline`
    ]]

    <button type="submit">Отправить</button>
</form>

FAQ

Убедитесь, что вызов капчи не кэшируется:
&#91;&#91;!ScxCaptchaAjaxForm&#93;&#93;
Страница и captcha.php должны быть на одном домене.
В 1.0.1 улучшена логика: токен очищается корректно, и капча перерисовывается без ошибок.

Убедитесь, что вызов капчи не кэшируется:
&#91;&#91;!ScxCaptchaAjaxForm&#93;&#93;
Страница и captcha.php должны быть на одном домене.
В 1.0.1 улучшена логика: токен очищается корректно, и капча перерисовывается без ошибок.

Обязательные поля:

  • scx_hp — honeypot (должно быть пустым)

  • scx_ts — время рендера (timestamp)

  • scx_code — ответ пользователя (5 цифр)

  • scx_token — токен текущей капчи

Все эти поля генерирует сниппет автоматически.

Переопределяйте классы в своём CSS:
.scx-captcha, .scx-img, .scx-refresh, .scx-input, .scx-hp
Или подключайте scx.css глобально.
Для модалок используйте &includeAssets="inline".

Готовы попробовать?

Установить Смотреть документацию
Лицензия: MIT. Поддержка: info@sait-modx.by.

История изменений

1.0.0
1.0.1
Как бы Вы хотели связаться?

Связь с нами