Логотип

Документация по макросам и шаблонам UMI.CMS

webforms add()

Название

%webforms add()% — Выводит форму обратной связи.

Параметры: webforms add([form, who, template = 'webforms', additionalAddresses...])

form

id или имя формы (созданной в административной части) — по умолчанию выводится последняя добавленная форма.

who

id или e-mail адресата (из административной части)

template

Имя шаблона, по которому формируется тело письма. В XSLT-шаблонизаторе игнорируется.

additionalAddresses

Любое количество дополнительных параметров, каждый из которых - id или e-mail адресата (из административной части)

Описание

Макрос отвечает за вывод формы обратной связи. В качестве аргумента who можно указывать как id списка адресатов, так и e-mail. В случае, если такой e-mail есть в одном из списков адресатов, то письмо будет разослано по всему списку.

Набор и типы полей определяется формой, указанной в параметре form.

Для Гостя обязательно заполнение CAPTCHA (защита от автоматических запросов), поэтому в шаблоне должен быть прописан макрос %system captcha()% , в ином случае сообщение через форму обратной связи не сможет быть отправлено Гостем.

<?= $this->render($this->macros('webforms', 'add', array($page->getValue('form_id'))), 'webforms/add') ?>

Макрос возвращает набор доступных списков адресов, существующих на сайте, а также список полей для создания формы по id указанному в параметре form. Если этот параметр отсутствует, то будет выведены данные о последней добавленной форме.

Саму форму необходимо самостоятельно верстать в шаблоне (см. пример ниже).

Пример вызова

udata://webforms/add/832

XML-ответ UData

<udata form_id="832" module="webforms" method="add" generation-time="0.501507">
  <items>
    <item id="27683">Письмо администраторам</item>
    <item id="27686">Письмо в рекламный отдел</item>
  </items>
  <groups>
    <group name="lichnye_dannye" title="личные данные">
      <field name="imya" title="имя" input_name="data[new][imya]"
       type="string" id="9263" required="required"/>
      <field name="familiya" title="фамилия" input_name="data[new][familiya]"
       type="string" id="9264"/>
      <field name="email" title="e-mail" input_name="data[new][email]"
       type="string"  tip="это подсказка" id="9265" required="required"/>
      <field name="soobwenie" title="сообщение" input_name="data[new][soobwenie]" 
       type="text" id="9267" required="required"/>
    </group>
  </groups>
</udata>

В случае если указан параметр who конкретного списка адресов, то вместо ветви items будет присутствовать 2 элемента (address_select и res_to). Содержимое любого из них необходимо указать при верстке формы:

<address_select>
  <input type="hidden" name="system_email_to" value="27683" />
</address_select>
<res_to>
  <input type="hidden" name="system_email_to" value="27683" />
</res_to>

Элементы и атрибуты

<items>

Ветвь, описывающая набор списков адресов, созданных на сайте — элементы item.

<item>

Элемент описывающий отдельный список адресов.

@id

Идентификатор списка адресов

<groups>

Ветвь, описывающая список из групп полей для этой формы.

<group>

Элемент, описывающий отдельную группу полей из списка групп.

<field>

Отдельное поле из группы полей. Данные из атрибутов необходимо использовать при создании формы.

@name

Имя поля

@title

Заголовок поля

@input_name

Имя, необходимое для задания атрибута name у тега <input>

@type

Тип данных для этого поля

@id

Идентификатор поля

@required

Атрибут, указывающий, что это поле является обязательным к заполнению

@tip

Подсказка к полю. Можно использовать для объяснения, что именно должно быть введено в это поле при верстке формы

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

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

В том месте, где необходимо отобразить форму, вызовем макрос:

<xsl:apply-templates select="document('udata://webforms/add/832')/udata" mode="mywebform"/>

Теперь необходимо описать шаблоны обработки результатов макроса. Создаем форму:

<xsl:template match="udata[@module = 'webforms'][@method = 'add']" mode="mywebform">

  <form method="post" action="/webforms/send/">

    
    <input type="hidden" name="system_form_id" value="{@form_id}" />

    
    
    <input type="hidden" name="ref_onsuccess" value="/webforms/posted/" />
    <table>

      <tr>
        <td>Куда отправить:</td>
        <td>
           <select name="system_email_to">
             
             <xsl:apply-templates select=".//item" mode="form-select"/>
           </select>
        </td>
      </tr>
    
      
      <xsl:apply-templates select=".//field" mode="form-fields"/>

      
      <xsl:apply-templates select="document('udata://system/captcha')/udata[url]" />
  
   </table>

   <p><input type="submit" value="Отправить" /></p>

  </form>

</xsl:template>

Далее необходимо описать шаблон, выводящий набор списков адресов:

<xsl:template match="item" mode="form-select">
  <option value="{@id}">
    <xsl:value-of select="." />
  </option>
</xsl:template>

А также, например, 2 шаблона для полей типа string (для ввода таких данных как Имя, Фамилия, e-mail) и text (для ввода самого сообщения):

<xsl:template match="field[@type = 'string']" mode="form-fields">
  <tr>
    <td><xsl:value-of select="@title"/>:</td>
    <td><input type="text" name="{@input_name}"/></td>
  </tr>
</xsl:template>

<xsl:template match="field[@type = 'text']" mode="form-fields">
  <tr>
    <td><xsl:value-of select="@title"/>:</td>
    <td><textarea name="{@input_name}"/></td>
  </tr>
</xsl:template>

Для того, чтобы использовать защитный код, вставлен вызов макроса %system captcha()%, где проверка на наличие элемента url будет гарантировать, что зарегистрированные пользователи CAPTCHA не увидят:

<xsl:apply-templates select="document('udata://system/captcha')/udata[url]" />

Для которого необходимо описать шаблон, например, следующим образом:

<xsl:template match="udata[@method='captcha']">
   <tr>
      <td><label for="{@input_id}">Защитный код:</label></td>
      <td><img src="{url}{@random_string}"/>
      <input type="text" name="captcha"/></td>
   </tr>
</xsl:template>

Вывод формы осуществляется по шаблону, указанному в параметре template. Вы можете не указывать этот параметр, тогда для вывода будет использован шаблон по умолчанию — webforms.tpl. Если в параметре who пустая строка, выводится выпадающий список всех адресатов, указанных во вкладке "Списки адресов".

Используемые шаблоны

Макрос оперирует шаблонами, находящимися в каталоге /tpls/data/reflection/

Используемые блоки шаблона

error_no_form

Вид сообщения об ошибке, что форма с заданным идентификатором не существует

send_successed

Вид сообщения об успешной отправке

address_select_block

Внешнее оформление выбора адреса (для случая выбора одного адреса из всех, существующих в админке)

%options%

строки со значениями (содержимое блока address_select_block_line)

address_select_block_line

Оформление строки со значением

%list-class-first%

в случае, если элемент первый, выводит "first"

%list-class-last%

в случае, если элемент последний, выводит "last"

%list-class-odd%

в случае, если элемент четный, выводит "odd"

%list-class-even%

в случае, если элемент нечетный, выводит "even"

%list-position%

вставляет порядковый номер в списке

%id%

идентификатор адреса

%text%

описание адреса (поле "Описание" в админке)

address_separate_block

Внешнее оформление выбора адреса (для случая выбора одного или нескольких адресов из указанных в макросе — доступно начиная с версии 2.7)

%lines%

строки с адресами из блока address_separate_block_line

address_separate_block_line

Оформление строки со значением

%id%

идентификатор поля

%value%

значение поля — идентификатор адреса

%description%

описание адреса (поле "Описание" в админке)

%list-class-first%

в случае, если элемент первый, выводит "first"

%list-class-last%

в случае, если элемент последний, выводит "last"

%list-class-odd%

в случае, если элемент четный, выводит "odd"

%list-class-even%

в случае, если элемент нечетный, выводит "even"

%list-position%

вставляет порядковый номер в списке

form_block

Внешнее оформление формы (вместе с тегом form)

%form_id%

идентификатор формы (должен обязательно присутствовать, как в дефолтном шаблоне)

%template%

шаблон, по которому выводилась форма

%address_select%

блок выбора адреса

%groups%

группы полей и поля

reflection_block

Выводит блок оформления для формы.

%groups%

Выводит список групп полей для редактирования.

reflection_group

Выводит блок оформления группы полей для редактирования.

%title%

Выводит название группы полей.

%name%

Выводит идентификатор группы полей.

%fields%

Выводит список полей для редактирования.

reflection_field_string

Выводит элемент формы для редактирования строковых полей.

%title%

Выводит название поля.

%name%

Выводит идентификатор поля.

%value%

Выводит значение поля.

%tip%

Выводит подсказку, если она указана в шаблонах данных для этого поля.

%input_name%

Выводит значение атрибута name для тега input, чтобы система могла корректно получить эти значения после отправки формы.

%type%

Выводит тип поля.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_text

Выводит элемент формы для текстовых полей.

%title%

Выводит название поля.

%name%

Выводит идентификатор поля.

%value%

Выводит значение поля.

%input_name%

Выводит значение атрибута name для тега input, чтобы система могла корректно получить эти значения после отправки формы.

%type%

Выводит тип поля.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_boolean

Выводит элемент формы для полей типа «Кнопка-флажок».

%title%

Выводит название поля.

%name%

Выводит идентификатор поля.

%checked%

Выводит «checked» если значение поля равно «да», в противном случае не выводит ничего.

%input_name%

Выводит значение атрибута name для тега input, чтобы система могла корректно получить эти значения после отправки формы.

%type%

Выводит тип поля.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_relation

Выводит элемент формы для полей типа «Выпадающий список». Обычно это обрамляющий тег select.

%title%

Выводит название поля.

%name%

Выводит идентификатор поля.

%type-id%

Если поле связано с каким-либо справочником, то выводится id этого справочника.

%values%

Выводит список возможных значений для выбора, используя блоки шаблонов reflection_field_relation_option и reflection_field_relation_option_a . Если эти блоки в шаблоне не заданы, то будут использованы теги option.

%input_name%

Выводит значение атрибута name для тега input, чтобы система могла корректно получить эти значения после отправки формы.

%type%

Выводит тип поля.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_relation_option

Выводит вариант выбора для выпадающего списка (reflection_field_relation), если он еще не выбран.

%name%

Выводит название варианта.

%id%

Выводит id варианта.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_relation_option_a

Выводит вариант выбора для выпадающего списка (reflection_field_relation), если он еще не выбран.

%name%

Выводит название варианта.

%id%

Выводит id варианта.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_multiple_relation

Выводит элемент формы для полей типа «Выпадающий список с множественным выбором». Обычно это обрамляющий тег select с атрибутом multiple.

%title%

Выводит название поля.

%name%

Выводит идентификатор поля.

%type-id%

Если поле связано с каким-либо справочником, то выводится id этого справочника.

%values%

Выводит список возможных значений для выбора, используя блоки шаблонов reflection_field_multiple_relation_option и reflection_field_multiple_relation_option_a . Если эти блоки в шаблоне не заданы, то будут использованы теги option.

%input_name%

Выводит значение атрибута name для тега input, чтобы система могла корректно получить эти значения после отправки формы.

%type%

Выводит тип поля.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_multiple_relation_option

Выводит вариант выбора для выпадающего списка (reflection_field_multiple_relation), если он еще не выбран.

%name%

Выводит название варианта.

%id%

Выводит id варианта.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_multiple_relation_option_a

Выводит вариант выбора для выпадающего списка (reflection_field_multiple_relation), если он еще не выбран.

%name%

Выводит название варианта.

%id%

Выводит id варианта.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

reflection_field_file

Выводит элемент формы для полей типа «Файл».

%title%

Выводит название поля.

%name%

Выводит идентификатор поля.

%value%

Выводит путь до файла, если он уже загружен.

%input_name%

Выводит значение атрибута name для тега input, чтобы система могла корректно получить эти значения после отправки формы.

%type%

Выводит тип поля.

%required%

Выводит слово "required" в случае, если поле обязательно для заполнения.

%required_asteriks%

Выводит звёздочку (*) в случае, если поле обязательно для заполнения.

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

Создайте файл sample.tpl в директории /tpls/data/reflection/ и напишите в нем следующий код:

<?php

$FORMS = Array();

$FORMS['error_no_form'] = '<b>Форма не определена</b><br />Обратитесь к администрации ресурса';

$FORMS['send_successed'] = 'Ваше сообщение отправлено';

$FORMS['form_block'] = <<<END
<form enctype="multipart/form-data" method="post" action="/webforms/send/">
 <input type="hidden" name="system_form_id" value="%form_id%" />
 <input type="hidden" name="system_template" value="%template%" />
 %address_select%
 %groups%
</form>
END;

$FORMS['address_select_block']  = <<<END
<table border="0" width="500">
    <tr>
        <td>
            Получатель
        </td>

        <td>
            <select name="system_email_to" style="width: 200px">
                %options%
            </select>
        </td>
    </tr>
</table>
END;

$FORMS['address_select_block_line']  = <<<END
 <option value="%id%">%text%</option>
END;

$FORMS['reflection_block'] = <<<END
 %groups%
 %system captcha()%
 <input type="submit" value="Отправить" />
END;

$FORMS['reflection_group'] = <<<END

 <b>%title%</b><br />

 <table border="0" width="500">
  %fields%
 </table>

END;

$FORMS['reflection_group_address'] = <<<END

<table border="0" width="500">
    <tr>
        <td>
            Получатель
        </td>

        <td>
            <select name="system_email_to" style="width: 200px">
                %options%
            </select>
        </td>
    </tr>
</table>

END;

$FORMS['reflection_field_string'] = <<<END

 <tr>
  <td>
   %title%:
  </td>

  <td>
   <input type="text" name="%input_name%" value="%value%" size="50" />
  </td>
 </tr>

END;

$FORMS['reflection_field_text'] = <<<END

 <tr>
  <td>
   %title%:
  </td>

  <td>
   <textarea name="%input_name%" style="width: 200px">%value%</textarea>
  </td>
 </tr>

END;

END;

$FORMS['reflection_field_boolean'] = <<<END

 <tr>
  <td>
   %title%:
  </td>

  <td>
   <input type="hidden" id="%input_name%" name="%input_name%" value="%value%" />
   <input onclick="javascript:document.getElementById('%input_name%').value = this.checked;" type="checkbox" %checked% value="1" />
  </td>
 </tr>

END;

$FORMS['reflection_field_file'] = <<<END

 <tr>
  <td>
   %title%:
  </td>

  <td>
            <input type="file" name="%input_name%" />
  </td>
 </tr>
END;

$FORMS['reflection_field_relation'] = <<<END
    <tr>
        <td>
            %title%:
        </td>

        <td>
            <select name="%input_name%" style="width: 205px" class="textinputs">
                <option />
                %options%
            </select>
        </td>
    </tr>

END;

$FORMS['reflection_field_relation_option'] = <<<END
    <option value="%id%">%name%</option>
END;

$FORMS['reflection_field_relation_option_a'] = <<<END
    <option value="%id%" selected="selected">%name%</option>
END;

$FORMS['reflection_field_multiple_relation'] = <<<END
    <tr>
        <td>
            %title%:
        </td>

        <td>
            <select name="%input_name%" class="textinputs" multiple>
                <option />
                %options%
            </select>
        </td>
    </tr>

END;

$FORMS['reflection_field_multiple_relation_option'] = <<<END
    <option value="%id%">%name%</option>
END;

$FORMS['reflection_field_multiple_relation_option_a'] = <<<END
    <option value="%id%" selected="selected">%name%</option>
END;

?>

В шаблоне можно использовать любое количество полей ввода информации, где имя полей ввода строится по шаблону: data[any_field_name]. Для того, чтобы указать метку (label) поля, используйте <input type="hidden" name="labels[any_field_name]" value="Метка поля" />.

Создайте страницу «Обратная связь» в модуле «Структура». В редакторе содержимого страницы введите макрос %webforms add('','', 'sample')%. Сохраните страницу.