Хуки

Хуки FormIt¶

Хуки это скрипты, которые запускаются во время обработки FormIt. Они всегда выполняются в том порядке, в котором они указаны в свойстве. Если, например, у вас есть ловушка электронной почты, за которой следует ловушка проверки, электронное письмо будет отправлено до того, как произойдет проверка. Если какой-либо хук не сработает, последующие за ним не будут выполняться.

Хуки также могут быть именами Сниппетов, которые затем будут выполнять сниппет в качестве хука. Сниппет должен возвращать true в случае успеха и false в случае неудачи.

Есть три типа хуков:

• preHook, указанный в свойстве preHooks в сниппете FormIt, который выполняется при загрузке формы. Полезны для предварительной загрузки значений.
• renderHook, указанный в свойстве renderHooks в сниппете FormIt, который выполняется, когда форма загружается и предварительные preHooks хуки уже завершены. Полезно для обработки полей и ошибок перед отрисовкой формы, как это используется в Formalicious.
• Обычный хук, указанный в свойстве hooks в сниппете FormIt, который выполняется после проверки формы. Полезно для пользовательской пост-обработки.

Использование preHooks¶

Просто укажите preHook в свойстве preHooks в вызове сниппета FormIt. Встроенных preHooks хуков нет, но если у вас есть например preHook под названием loadCustomValues, то вызов будет таким:

[[!FormIt? &preHooks=`loadCustomValues`]]

Formit перед загрузкой формы запустит сниппет loadCustomValues. Вы можете установить поля в форме следующим образом:

<?php
$hook->setValue('name','Иван Петров');
$hook->setValue('email','[email protected]');
return true;

Или альтернативно использовать ->setValues:

<?php
$hook->setValues(array(
    'name' => 'Иван Петров',
    'email' => '[email protected]',
));
return true;

Обратите внимание, что использование здесь метода setValues() сделает соответствующие Плейсхолдеры доступными для вашего блока электронной почты; эффект ручной установки значений аналогичен добавлению скрытых полей в вашу форму.

Вы также можете делать все, что хотите, в preHook. Не забудьте вернуть true, если ваш preHook или hook успешны. Если вы хотите добавить в поле сообщение об ошибке:

$hook->addError('user','Пользователь не найден.');
return $hook->hasErrors();

Использование параметра renderHooks¶

Просто укажите renderHook в свойстве renderHooks в вашем вызове сниппета FormIt. Встроенных хуков для renderHooks нет, но если у вас например есть renderHook с именем buildSessionFields, то можно сделать вот так:

// Получить конфигурацию Formit и возможные заданные значения
$formit =& $hook->formit;
$values = $hook->getValues();

// Получить данные сеансов
$values = array_merge($_SESSION['preset_fields_from_session'], $values);
$fields = array();
foreach ($values as $value) {
    // $value = array('label' => '', 'name' => '')
    $fields[] = $modx->getChunk('fieldChunk', $value);
}
$modx->toPlaceholder('extraFields', implode(PHP_EOL, $fields));

С новой системой хуков стало проще создавать пользовательские формы из сессий, базы данных или данных API.

Использование хуков¶

Просто укажите хук в свойстве hooks при вызове сниппета FormIt. Например, следующий вызов загружает хук-перехватчик спама и хук отправки электронной почты:

[[!FormIt? &hooks=`spam,email`]]

Встроенные Хуки¶

Вот список встроенных хуков, поставляемых вместе с FormIt:

• email
• redirect
• spam
• math
• recaptcha
• FormItAutoResponder

Хук redirect (если используется) всегда должен быть указан последним в списке хуков. Помните, что хуки выполняются в том порядке, в котором они указаны в свойстве Formit.

Произвольные хуки¶

Любой Cниппет можно использовать как настраиваемый хук с Formit. Сниппет должен возвращать true в случае успеха и либо false, либо массив сообщений об ошибках в случае неудачи (см. ниже). Если фрагмент возвращает false, хуки, перечисленные после сниппета в параметре hooks, не будут выполняться. Если фрагмент не найден, будут выполняться следующие за ним в списке хуки.

Использование пользовательских хуков¶

Чтобы использовать собственный хук, просто добавьте имя Сниппета в параметр &hooks. Хуки будут выполняться в том порядке, в котором они указаны в параметре &hooks. Ваш сниппет может находиться в любой позиции в списке.

Доступ к полям формы FormIt в хуке¶

Поля Formit формы доступны через API интерфейс хуков. Пример:

$email = $hook->getValue('email');
$allFormFields = $hook->getValues();

Если вы хотите задать значения полей, вам нужно будет получить к ним доступ следующим образом:

$hook->setValue('email','[email protected]');
$hook->setValues(array(
    'name' => 'Иван Петров',
    'books' => 'Голодные игры,Убить пересмешника,1984',
));

Если вы хотите установить поле массива (например группу флажков с тем же именем, или мультиселект) в preHook, вам нужно прежде применить json_encode значение массива.

$hook->setValue('hobbies',json_encode(array('music','films','books')));

Доступ к свойствам FormIt scriptProperties (конфигурация)¶

Свойства, переданные вызову сниппета FormIt, доступны в свойстве config объекта $formit, представленного в хуке.

$hook->formit->config['key']

Пользовательские значения возвращаемые хуком¶

Сниппеты должны вернуть успешный результат - return true. При неудаче сниппет может установить сообщения об ошибках в переменной ошибки и вернуть false. В любом случае, хуки, перечисленные после пользовательского в параметре &hooks, не будут выполняться.

Объект fiHooks доступен в сниппете как $hook, который может быть использован для возврата общих сообщений об ошибках из сниппета:

$errorMsg = 'Пользователь не найден';
$hook->addError('user',$errorMsg);
return false;

Опять же, помните - если ваш хук завершится успешно, убедитесь, что у вас есть возврат положительного результата return true; в конце вашего хука. Если вы используете "return false;" или не возвращаете никакое значение, FormIt будет считать, что хук завершился неудачно. Кроме того, убедитесь, что любые пользовательские хуки, которые вы указываете, располагаются перед хуком перенаправления redirect в свойстве &hooks.

Хуки на базе файлов¶

FormIt, начиная с версии 2.0.0+, поддерживает файловые хуки и прехуки. Это означает, что вы можете указать в FormIt путь к файлу PHP для использования в качестве пользовательского хука. Например:

[[!FormIt?
&hooks=`[[++assets_path]]hooks/my.hook.php`
]]

Здесь будет осуществлен поиск хука в assets/hooks/my.hook.php. Если файл найден, он будет работать с хуком из него.