Вход для клиентов и партнеров
в начало сайта
Партнерская программаОнлайн демоСкачатьКарта сайта
 

Регламент
Документация
Часто задаваемые вопросы (FAQ)
Решения типовых вопросов
Форум поддержки
Библиотека разработчика

Посмотрите демо-ролики и убедитесь в том, что "Twilight CMS" очень удобна в управлении, понятна и проста.

Бесплатно скачайте "Twilight.Basic", установите на своем компьютере и изучите систему более детально.

Если вам нужно установить "Twilight CMS" на существующий сайт или разработать новый - обращайтесь в отдел интеграции.

 

Ваше имя
Ваш Email
Вопрос
Twilight.basic
  • Узнайте больше
  • Сравните версии
  • Twilight.selection
  • Узнайте больше
  • Сравните версии
  • Twilight.evolution
  • Узнайте больше
  • Сравните версии
  •  
    Главная // Библиотека разработчика // Справочники // Макроподстановки //

    Form


    Назначение

    Вывод форм для отправки данных на сервер и обработка результатов их заполнения пользователями.

    Ключи

    html Строка, псевдоним страницы или имя файла-шаблона c формой находящегося в папке Templates. Псевдоним страницы используется, когда тело формы необходимо показывать или редактировать через админзону. Поскольку это очень редкий случай, рекомендуется всегда использовать шаблоны. Для шаблонов с расширением .html расширение можно опускать.

    Начиная с версии 5 в данный ключ можно также передать строку, содержащую форму целиком. Этот вариант предназначен для упрощенной генерации форм макросом GenerateForm, который достаточно вставить вместо значения ключа (см. примеры в конце статьи). Хотя при желании строку можно сформировать и вручную.

    redirect_after Строка, псевдоним страницы, на которую перейдет пользователь после отправки формы. Если он не задан – пользователь останется после отправки данных на текущей странице.
    savetodb Строка, содержит имя таблицы (файла .dat в папке Data), в которую будет добавлена новая запись с данными из формы. Необязательный ключ.
    email_label Строка, содержит идентификаторы (значения поля label) шаблонов писем из справочника Data/email _notifications.dat через запятую. Шаблон каждого письма может содержать подстановки вида %fieldname% или $fieldname$, вместо которых будут подставляться значения из полей формы с соответствующим названием.

    Внимание: замена значений $fieldname$ в письме для полей из базы, куда пишется информация из формы, но которые в форме отсутствуют возможна только при включении режима savetodb. Это нужно если в письме необходимо указать поле numberid (пример применения: нумерация заказов), id или любое другое служебное поле, автоматически создаваемое системой и дописываемое к информации из формы.

    captcha Строка, принимающая значение "истина" при установке в одно из значений: "yes", "on", "true", "истинное логическое выражение" (1). При значении "истина" включается проверка на корректно заполненное контрольное поле, сгенерированное сервисом $Captcha[]$.
    condition Составное условие выполнения макроса.
    redirect_captcha_error Строка, псевдоним страницы на которую нужно отправить пользователя, если он некорректно введен контрольный код с картинки (Captcha).
    redirect_revote_error Строка, псевдоним страницы, на которую нужно перейти если пользователь пытается проголосовать повторно в течение определенного периода времени (обычно 1 сутки). Ключ имеет смысл только для форм, которые выводятся через макрос Poll (для форм голосований).

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

    redirect_unique_error Псевдоним страницы, на которую будет редиректнут пользователь если он введет данные в форме, которые противоречат уникальности (если задано ключом uniquefields).
    uniquefield Строка, имена полей через запятую, значение которых посланное через форму не должно уже быть в соответствующих полях других записей в базе. Проще говоря, если задать в этом ключе "email, login", то не будут приниматься формы в которых в полях email или login встретятся значения, которые уже есть в базе. В общем случае, при нарушении этого правила данные не будут сохранены и не будет посылаться email оповещение (если заданы соответствующие опции), но можно редиректнуть пользователя на страницу с описанием ошибки.
    uniquetable Таблица, в которой проверять uniquefield. Если ключ не задан, то будет использована таблица, заданная в savetodb.
    idaliasfromfield Строка, перечень полей (через запятую) на основании которых требуется сгенерировать idalias (ЧПУ) для записи.

    Алгоритм генерации: строки объединяются, транслитерируются в английские буквы, лишние символы заменяются на "_", оставляется только 8 слов или менее. При невозможности создать уникальный ЧПУ будет добавлено число в конец строки.

    Далее сгенерированное значение может быть скорректировано через админзону.

    trimfields Строка, если имеет значение on|yes|true|1 заставляет макрос обрезать все лидирующие и замыкающие пробелы во всех полях, пришедших с формы перед записью и дальнейшей обработкой. По умолчанию опция выключена.
    convertimages Строка, составная инструкция для системы, позволяющая обработать изображения, которые были загружены через форму на сайт через поле type="file". Имеет вид "ширина, высота, режим преобразования, итоговый формат", например "800, 600, bound, jpg".

    Ширина и высота результирующего изображения задается в целых пикселах. Режимы идентичны применяемым в макросе Thumbnail (bound, boundcrop, strict). Выходной формат может быть один из jpg/gif/png, но рекомендуется применять "jpg". Возможно укороченное написание с указанием только первых двух или трёх параметров, тогда по умолчанию будут использованы значения bound для режима масштабирования и jpg для формата вывода.

    Идея: пользователь может через форму загрузить не только jpg/gif/png файлы, но и bmp (с цифровика) или tiff (из полиграфии). Также, линейные размеры изображений с фотоаппарата или полиграфического качества обычно очень большие, хранить такие изображения на сервере плохо (занимают много места) и требуется много памяти при их обработке. Если использовать данный ключ, то можно сразу при загрузке уменьшить изображение и перевести его в формат, пригодный для отображения на веб-странице через браузер.

    Максимальные размеры ширины и высоты для преобразования ограничены как 4000 пикселов, а минимальные как 20. Если разработчик задаст размеры, выходящие за эти границы, будут заданы значения ширина=800, высота=600.

    Максимальный размер загружаемых файлов в байтах задается через preferences.xml (ключ maxuploadsize). Разработчику нужно не забыть увеличить его значение, если допускается загрузка больших изображений.

    На файлы других форматов (не графические) данный ключ влияния не оказывает.

    watermarkimages Строка, составная инструкция для системы, позволяющая обработать изображения, которые были загружены через форму на сайт через поле type="file". Имеет вид "путь к изображению с водяным знаком, ориентация знака на изображении", например "/Sites/twl_ru/Images/watermark.png, SouthEast".

    Варианты ориентации идентичны применяемым в макросе Watermark.

    Водяной знак наносится после масштабирования, если оно было задано ключом convertimages.

    addtocatalog Сложная строка параметров вида

    folderid, titlefield, <last>|first, on|<off>

    Символом <> выделено значение "по умолчанию". Первый параметр, folderid, является идентификатором папки, куда необходимо добавить новый элемент каталога. При этом ему при создани будет назначен заголовок, который лежит в поле формы titlefield. last или first определяют куда добавлять новый элемент - в конец папки или в начало, а on или off - какое состояние у флага "опубликован" будет при создании.

    ignorefields Строка, в которой через запятую перечисляются поля, которые пришли из формы на сайте, но не должны попасть в базу. Обычно используется для блокировки ряда полей при редактировании профилей пользователей.
    updatemode Логическое значение: при on, true, 1 или yes разрешает обновление уже существующей записи в базе, находя её по переданному полю с именем id. По умолчанию функция отключена, и в случае передачи в форме поля id оно будет проигнорировано, а запись в базе - добавлена.
    savetodbcondition Составное условие, только при выполнении которого данные будут записаны в базу. Обычно используется для проверки введенных данных, например, совпадения пароля при модификации профиля пользователя.
    shadowfields Перечень полей через запятую, которые в форме являются чекбоксами и селектами в режиме множественного выбора, которые не отсылаются формой в положении, когда чекбокс снят или все опции в селекте сняты. Применяется только в режиме updatemode: on.
    filenamepostfix Строка, которая будет добавляться к каждому имени файла, который будет загружен пользователем в Uploads/User через форму, после имени. По умолчанию, к уникальному 32 символьному идентификатору не добавляется ничего.
    filenameprefix Строка, которая будет добавляться к каждому имени файла, который будет загружен пользователем в Uploads/User через форму, до имени. По умолчанию, к уникальному 32 символьному идентификатору не добавляется ничего.

    Комментарии

    Формирование HTML кода формы при вызове макроса

    Есть два варианта сформировать форму на странице:

    1. В ключ html вставляется макрос GenerateForm, который полностью генерирует код формы и присваивает её элементам css классы, с помощью которых можно изменять их внешний вид и расположение. Это самый простой и быстрый способ, который предназначен для простых случаев или для отладки. Разработчик не может влиять в этом случае на HTML, генерируемый системой, но может изменять DOM с помощью javascript манипуляций.

    2. Если в ключе html лежит строка вида <FORM ...>...</FORM> или задано имя шаблона, куда для удобства работы этот код вынесен отдельным файлом, то разработчик получает возможность произвольным образом сверстать свою форму в HTML/CSS, а также навесить на неё свои javascript обработчики. Это очень гибкий и полностью настраиваемый вариант. При этом разработчик обязан соблюсти одно правило. Атрибут action формы обязан присутствовать и он должен быть установлен пустой строкой: action="". Если атрибута action в тэге FORM нет, сервер будет выдавать 405 ошибку при попытке отправки формы.

    Возможности макроса

    После заполнения на сайте формы посетителем и отправки данных на сервер Система может:

    • отклонить данные, если они попадают под определения в черных списках;
    • отклонить данные, если система определяет отправителя как спам-бот;
    • отклонить данные, если в настройках включена captcha и пользователь ввел неверный код;
    • проверить данные на предмет наличия определенных полей в базе и отказать пользователю в их сохранении при определенных разработчиком условиях;
    • отклонить часть данных, если некоторые поля запрещены к модификации через страницы сайта;
    • отправить письмо сгенерированное по определенному шаблону;
    • записать данные в таблицу .dat. Сохраненные из форм данные могут быть далее подключены в админзоне как обычный справочник, который может просматриваться и/или редактироваться;
    • создать элемент в каталоге в определенной папке;
    • автоматически сформировать ЧПУ для новой записи;
    • обрезать крайние пробелы в поступивших полях;
    • если загружены графические файлы то на лету уменьшить их, проставить водяные знаки, конвертировать из формата в формат (например, из BMP в JPG) и записать в базу уже обработанное изображение.

    Как видно, макрос насыщен логикой. Это один из самых сложных макросов Системы. Далее описаны способы использования его возможностей, остальное должно быть понятно из описания ключей в таблице выше.

    Отправка писем

    Письма отправляются различными способами для NT и Unix платформ. В 99% случаев на Unix площадке используется программа sendmail, которая не требует специальной авторизации. Путь и ключи к sendmail прописываются в preferences.xml. Там же прописаны адреса, куда и от чьего имени по умолчанию отправляется вся почта с сайта. Они могут быть переопределены в шаблоне письма, которые хранятся в email_notifications.dat и обычно подключены в админзоне под именем "Служебные функции/Шаблоны email оповещений".

    Шаблон письма - это тело письма и набор полей с адресами (кому, копия, скрытая копия, от кого и т.п.). В теле шаблона и полях с адресами можно использовать подстановки вида $fieldname$ для вывода значений, полученных из формы. Также возможно применение некоторых простых макросов, типа DataField и News.

    Дополнительная информация в письмах

    Начиная с версии 4.39 при включенном модуле сбора статистики "StrataStat" (см. preferences.xml) система запоминает начальную страницу каждого посещения и начальный реферер - адрес, откуда посетитель пришел на сайт. Затем система автоматически добавляет эту информацию в конец письма, которое отправляется после заполнения любой формы. Это нужно, чтобы прямо в письме (обычно это заявки с сайта или формы обратной связи) было видно по какому запросу в поисковике был найден сайт, или с какого сайта-донора пришел посетитель.

    Данные о реферерах хранятся всего сутки (чтобы не замусоривалась база), поэтому если форму заполнит человек, ранее посещавший сайт - в конце письма не будет никакой информации. Также, если реферер был пустым, либо браузер пользователя не разрешает работать с cookies эта функция также ничего не добавит к письму.

    Выключить данную возможность можно только с отключением "StrataStat", но вряд ли это кому-то придет в голову. Показывать источники клиентов сразу в теле заявки - супер-нужная и уникальная функция.

    Сохранение форм в базу данных

    Если $Form[]$ указано сохранять данные в справочник, то к полям, которые пришли из формы, принудительно будут добавлены поля ip и proxy, в которые будут помещены IP адреса машины с которой посланы данные (если возможно определить) и IP адрес прокси-сервера (если использован и возможно определить). Данная функция предназначена для целей защиты сервера от спамеров или "шутников" путем блокировки нежелательных IP адресов в настройках сервера исходя из статистики. Нужно учесть, что если форма на странице имела поля с такими именами, то данные из формы будут утеряны, поэтому рекомендуется использовать другие имена полей.

    Если не заданы ключи savetodb и email_label, то форма просто передаст управление на указанную в redirect_after страницу, на которой параметры из формы могут быть распознаны через метаподстановку $IN_field$. Такое применение типично для механизма авторизации, где достаточно передать параметры login и password на любую страницу, требующую авторизации на сайте.

    Внимание! Макрозамена $IN_id$ на странице, куда происходит редирект (задается в ключе onsuccess) выдает не идентификатор записи, которая получится в базе в результате сохранения данных из формы, а другое служебное значение. Идентификатор записи можно получить через $IN_recordid$. Это необходимо, например, когда сразу после сохранения требуется обработать сохраненную запись через RegistrationConfirm или произвести с ней еще какие-либо действия. $IN_recordid$ реализован только в версиях 4.40 и выше.

    Сохранение в базу полей с текстовым и HTML содержимым

    По умолчанию, предполагается, что в форме могут быть поля типа textarea, где посетители сайта могут писать в том числе и многострочные тексты, отбивая абзацы переносами строк. Чтобы в дальнейшем это можно было легко выводить на страницах сайта без дополнительного форматирования, система (исторически так сложилось) принудительно конвертирует переносы строк в HTML тэги <BR>.

    Если разработчик сайта решает задействовать в форме WYSIWYG редакторы типа tinyMCE, которые обычно достаточно легко интегрируются поверх существующих textarea полей, то такой подход ломает контент. С каждым сохранением переносы строк множатся, и расстояния между абзацами увеличиваются. Чтобы заставить макрос не трогать контент и сохранять его "как есть" в форме необходимо вставить такое поле:

    <INPUT type=hidden name="hid_wysiwyg" value="1">

    Так как в имени присутствует префикс hid_, система не будет сохранять это поле в базу. Его непустое значение скажет системе не трогать контент формы и писать его в базу "как есть". Если разработчику в дальнейшем потребуется дополнительное форматирование, он может сделать его на этапе вывода контента на страницу с помощью макроса Replace и других.

    Отправка файлов пользователями через формы

    Если в форме присутствуют поля типа file (<input type="file" name="yourfieldname">), то в форме обязательно должны быть прописаны метод отправки данных POST и способ кодирования multipart/form-data, примерно так:

    <form action="" enctype="multipart/form-data" method="POST">

    Если форма генерируется макросом GenerateForm, то это будет сделано автоматически.

    Файлы, принимаемые через такие формы будут сохранены в специальной системной папке (Uploads/User), имя файла пойдет в базу данных в поле yourfieldname. Далее вы можете его оттуда использовать стандартным образом, в том числе прислать в письме ссылку на этот файл для проверки модератором.

    Внимание:

    • Чтобы механизм файловой отправки заработал необходимо активировать ключ uploadfilesenabled в preferences.xml (значения on, true, yes или 1, как обычно);
    • Файловая отправка в целях безопасности разрешена только для следующих расширений: gif, jpg, jpeg, jpe, png, tiff, tif, bmp, swf, rtf, doс/docx, xls/xlsx, ppt/pptx, zip, rar, arj, pdf и возможно в будущем будут добавлены еще какие-то очевидно часто используемые и не влияющие на безопасность сервера файлы. Файлы с остальными расширениями будут немедленно уничтожены после загрузки на сайт;
    • Имена файлов модифицируются системой и содержат случайный ключ, чтобы злоумышленники не могли обращаться к ним если они пытаются загрузить на сайт что-то нехорошее (еще один уровень защиты);
    • Максимальный размер файла ограничивается в переменной maxuploadsize в preferences.xml, если она не задана максимальный размер ограничен 30000 байт.

    ПРЕДУПРЕЖДЕНИЕ. Если вы включили прием файлов на сайте, администратору нужно будет постоянно контролировать сайт на предмет исчерпания дискового пространства. Рекомендуется максимально ограничить размер файлов для загрузки и максимизировать доступное для сайта пространство на диске. Мы настоятельно рекомендуем периодически проверять папку Uploads/User на предмет наличия лишних файлов. Делать это придется по FTP, пока в системе нет средств для отслеживания её содержимого, хотя при включенном механизме квот на сервере система будет оповещать в админзоне о заканчивающемся дисковом пространстве.

    Защита форм от спама

    Формы на сайте обычно заполняет человек разумный (homo sapiens) или программа (бот). Борьба с ботами, забивающими формы ненужной владельцу сайта информацией осуществляется с помощью CAPTCHA (см. макрос Captcha). Но иногда необходимо блокировать отсылку форм от определенных людей, которые могут рассылать ненужную рекламу владельцу сайта вручную, повторно слать заявки на регистрацию после отказа, писать оскорбительные сообщения и тому подобное.

    Начиная с версии 4.46 система всегда использует для фильтрации вводимой пользователем информации "черный список" значений, который хранится в файле blacklist.dat (см. www.twl.ru/tsdn/file_formats/blacklist_dat). Если файл пустой, то значения формы фильтроваться не будут.

    Редактирование профилей пользователей и других записей в базе

    С помощью Form можно достаточно просто организовать регистрацию пользователей, просто добавляя в таблицу новые учетные записи с их профилями. Чтобы дать возможность пользователю редактировать эти данные в будущем, требуется включить режим обновления (ключ updatemode), который позволит передавать в форме (обычно через hidden поле) id редактируемой записи. Если какие-то параметры в базе редактировать запрещено, например, логин, то обязательно нужно перечислить запрещенные поля в ключе ignorefields. Также, чтобы авторизованный пользователь не смог модифицировать чужой профиль, разработчик ОБЯЗАН прописать в ключе savetodbcondition такой формы проверку на соответствие логина и пароля, или какой-то альтернативный способ идентификации нужной записи, поскольку сам по себе id не является секретной информацией и может быть вычислен по параметрам в URL или другими способами.

    Важно: HTML формы не отправляют поля типа чекбокс, если он выключен (без галочки), на сервер. Для заполнения обычных форм с сохранением в базу это неважно, т.к. если в базе нет такого поля, то это равносильно тому, что оно пустое. Но в случае, когда в базе уже есть запись, и значение такого поля равно on (чекбокс был включен на момент сохранения записи), а в процессе редактирования существующей записи через форму чекбокс выключили, то непередача такого поля на сервер приведет к тому, что значение не будет изменено. То есть, чекбокс не сбросится. Чтобы этого избежать, обычно в форме программируют на javascript проверку всех таких полей и отсылают подготовленные данные с искуственно сгенерированным полем. Чтобы разработчик этим не занимался, достаточно перечислить поля типа checkbox в ключе shadowfields, если вы работаете в режиме обновления данных (updatemode: on).

    Важно: обычно, если в форме при редактировании своего профиля пользователь стирает поле полностью, он хочет чтобы значение стерлось и в базе. Это значит, что получая пустое поле из формы его нужно писать в базу. Но это не так для полей типа file. Если у пользователя в профайле есть какой-то файл, например, графический аватар, или его резюме в вордовом файле, то во время редактирования у вас в форме поле выбора файла будет пустым. Если после загрузки такой формы нажать на "Сохранить", в базе запись обнулится, так как поле было пустым, и файл, загруженный ранее, будет потерян. Поэтому, система при сохранении полей типа file с пустыми значениями файл на сервере не трогает и в базе поля не обновляет. Но пользователю нужно дать две возможности: просмотреть загруженный ранее файл (делается обычным образом, выводя ссылку на файл или изображение в форме) и возможность удалять ранее загруженный файл с сервера, если ему он более не нужен (обнулять поле). Для этого нужно делать отдельную страницу, куда передавать данные о том, какое именно поле в какой записи какой таблицы нужно очистить, там же ОБЯЗАТЕЛЬНО проверять, чтобы имя поля нельзя было подставить какое хочешь (вопрос защиты информации от ушлых пользователей), на которой будет стоять RegistrationConfirm и обнулять нужное поле через set_fields_values.

    Примеры

    Пример №1. Типовое использование - форма обратной связи.
    $Form[html: FeedbackForm; redirect_after: feedback-result; savetodb: feedbacks; email_label: order_admin, order_client]$

    Пример №2. Вызов формы с полями для загрузки фотографий. Включены режимы обрезания пробелов и автоматического уменьшения фотографий, загружаемых пользователями на сайт, поле email уже находящееся в базе не допускается повторять в новых записях, ЧПУ автоматически генерируются для каждой новой записи по полям title и description.

    $Form[html: FeedbackForm; redirect_after: feedback-result; savetodb: news; email_label: email_feedback; uniquefield: email; redirect_unique_error: bademail; idaliasfromfield: title,description; trimfields: on; convertimages: 800, 600, bound, jpg]$

    Пример №3. Редактирование существующего профиля пользователя.

    $Form[html: EditUserForm; redirect_after: editprofile-ok; savetodb: registers; savetodbcondition: $IN_id$=$UserProfile[field: id; userset: registers]$; updatemode: on; blacklist: blacklist_reg; shadowfields: status_checkbox]$

    При этом предполагается, что все текущие значения полей в форме заполняются из профиля пользователя примерно таким образом (это фрагмент файла EditUserForm):

    ...
    <TR>
        <TD align=right>Фамилия</TD>
        <TD><INPUT name=lastname size=50 value="$XMLize[$UserProfile[field: lastname; userset: registers]$]$"></TD>
    </TR>
    <TR>
        <TD align=right>Страна</TD>
        <TD>$OptionList[table: countries; name: country; optiontitle: title; optionvalue: iso; selected: iso=$UserProfile[field: country; userset: registers]$; noemptyoption: on; sort: title, asc, auto]$</TD>
    </TR>
    <INPUT type=hidden name="id" value="$XMLize[$UserProfile[field: id; userset: registers]$]$">
    ...

    Обратите внимание, что если вы не знаете, будут ли в полях присутствовать кавычки, чтобы не получилось вот так: value="колхоз "Заветы Ильича"", мы используем макрос XMLize чтобы получить value="колхоз &quot;Заветы Ильича&quot;".

    « к списку макроподстановок

    версия для печати

     
    © 2003-17 Страта Технологии (создание сайтов, разработка cms), Twilight CMS in english.
    Наш адрес: Москва, пр. Маршала Жукова д.51
    Тел.: (495) 222-6436, E-mail: , карта сайта, условия использования информации о CMS
    Звоните через Skype:  

    Реклама: