Тэг field — Поле формы

Поле для ввода информации в форму.

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

Обычное текстовое поле:

<field name="title" prompt="Наименование" maxlength="255" help="" />

Выпадающий список:

<field name="category_id" prompt="Категория" maxlength="">
    <choice key="" italic="1">Выберите категорию</choice>
    <choice key="id" field="title" table="categories" /> <!-- ← можно так. Или вот так ↓ -->
    <choice table="">
        <sql>
        <![CDATA[
            SELECT id, title
            FROM categories
            WHERE 1
        ]]>
        </sql>
    </choice>
</field>

Элементы

Атрибуты

Основные

Атрибут Описание Примечание
name * Имя поля. По умолчанию, если не указан table-field или field, совпадает с именем в базе данных. Обязательно к использованию Допустимые символы: [a-zA-Z\d\_], при этом цифра не может быть идти первой. P.S. Хотя программа не будет ругаться, если указан field и не указан name, name лучше всё-равно всегда использовать, потому как без него не тестировалось
type * Тип поля Если атрибут не указан, то по умолчанию тип поля будет string
prompt * Заголовок поля, который выводится перед полем
label Текст, который будет справа от флажка (галочки), если поле типа [type=checkbox]
caption Название поля по-русски По умолчанию = prompt. Пока нигде не используется, но в будущем планируется использовать в конструкторах и конфигураторах формы. Пожалуйста, всегда используйте этот атрибут, если не указаны prompt или label!
noprompt Укажите 1 если оставлять место под Заголвок не требуется. Не вполне очевидный атрибут. _TODO: Описать подробнее
prefix Текст, который будет выводиться перед полем
postfix Текст, который будет выводиться сразу после поля Удобно использовать, например, для указания размерности — postfix="км."
default Значение поля по умолчанию
value Значение, которое будет указано в поле. Если этот атрибут задан, то полученное из базы данных значение, а также атрибут default будут игнорироваться
maxlength Максимальная длина текста, который можно ввести в поле Необходимо указывать такую же длину, как в базе данных
required Если != 0, то поле обязательное для заполнение. Система не даст отправить форму, пока это поле не будет заполнено. Поле считается незаполненным, если там введено пустое значение или 0. _TODO: Уточнить, возможно для int/double полей 0 считается заполнением Когда поле скрыто по условию из condition, оно перестаёт быть обязательным к заполнению
readonly Если !=0, то пользователь не сможет отредактировать значение поля По умолчанию 0. При этом, в отличие от установленного disabled, поле будет сохраняться! Это важное отличие. Также, обратите внимание, что, к сожалению, защиты у этого поля нет — пользователь может отредактировать значение, например, через консоль разработчика. Учитывайте это при проектировании системы
disabled Если !=0, то то пользователь не сможет отредактировать значение поля и в базу данных значение данного поля сохраняться не будет! По умолчанию 0. См. отличие от readonly в описании соответствующего атрибута
continue Если !=0, то следующий за полем элемент (например: другое поле, или text) будет размещён следом, на той же строке По умолчанию 0
interval-next Регулирует расстояние до следующего поля, если continue !=0. Возможны варианты: 0, small, normal По умолчанию normal. Чаще всего, если поля, объединяемые в одну строку тесно друг с другом связаны, используем small
donotquery Если !=0, то значение данного поля не будет загружаться из базы данных и не будет в неё сохранятся По умолчанию 0. Используется, когда поле отстутвует в базе данных, но выячисляется автоматически в loadsql и/или используется в finishsql
hidden Если !=0, то поле будет скрыто. Аналог [type=hidden], но менее надёжный. Тем не менее в некоторых ситуациях бывает необходим По умолчанию 0. Важно! Данный атрибут плохо работает в связке с condition, поведение при таком использовании спецификацией языка не регламентировано и может меняться от версии к версии
title Пока нигде не используется. Хотя в кодах упоминание есть

Использование разных источников данных (таблиц)

Атрибут Описание Примечание
source Имя источника из sources Значение по умолчанию — "main", что соответствует алиасу основной таблицы
table-field, field Имя поля в базе данных. По сути мало чем отличается от name. Используется только в тех случаях, когда а) по каким-то причинам надо заменить имя поля б) в форме используются 2 или более поля с одинаковым именем (но разным source) Оба варианта ничем не отличаются (на момент написания данной статьи). Но лучше использовать field, т.к. он короче. ВАЖНО Не надо указывать field, если он совпадает с name (в 99% случаев)

Настройка размеров полей

Атрибут Описание Примечание
size Размер поля в условных единицах =) За условную единицу принимается 9px. Но в какой-то момент это может поменяться
width Размер поля в пикселях Лучше по возможности избегать использования width, а если и используете, то выставлять кратным 9 — это необходимо, чтобы форма смотрелась аккуратно.Чтобы не сидеть каждый раз с калькулятором, можно использовать, например, математические функции: width="{ { \\# 9*15 } }" (135px). Ещё дополнение: px указывать НЕ надо.
prompt-size Размер prompt-а в условных единицах Используется, когда поле является продолжением предыдущего (т.е. когда у предшествующего поля или другого элемента стоит атрибут [continue=1]). P.S. Про условные единицы, см. атрибут size
prompt-width Размер prompt-а в условных единицах Используется, когда поле является продолжением предыдущего (т.е. когда у предшествующего поля или другого элемента стоит атрибут [continue=1]). В идеале также должне быть кратен 9! См. атрибут width
prefix-size [ ] Пока не реализован (_TODO)
prefix-width Ширина префикса (см. атрибут prefix) в пикселях В идеале также должне быть кратен 9! См. атрибут width. Если не задан, то высчитывается автоматически, как количество букв * 9
postfix-size [ ] Пока не реализован (_TODO)
postfix-width Ширина постфикса (см. атрибут postfix) в пикселях В идеале также должне быть кратен 9! См. атрибут width. Если не задан, то высчитывается автоматически, как количество букв * 9
cols Количество колонок у [type=checkboxgroup]. По умолчанию — 1. Когда-то этот атрибут был и у [type=textarea], но сейчас эта возможность отключена.
maxheight Максимальная высота поля типа [type=textarea] в пикселях Нет уверенности, что это работает =(
height Можно указать высоту поля в пикселях (px можно не ставить). Или в любых других единицах. Пример: "22", "3em" Толком не проверялось.
rows Количество строк у [type=textarea] Аналогичен соответствующему атрибуты в html

Динамические значения

Атрибут Описание Примечание
sqlfordefault (устарел) Содержит запрос для получения значения по умолчанию Может также быть тегом внутри field (чаще всего так и бывает). Важно! Лучше вместо этого использовать mod[on=create]
sqlforupdate (устарел) Содержит запрос для получения значения при обновлении поля при срабатывании onchange[do=update] Может также быть отдельным тегом внутри field (чаще всего так и бывает). Важно! Лучше вместо этого использовать mod[on=update]
sqlforvalue (устарел) Содержит запрос для получения значения поля, которое будет устанавливаться всегда — при создании новой записи, при открытии существющей записи на редактирования и при вызове обновления посредством onchange[do=update] Может также быть отдельным тегом внутри field (чаще всего так и бывает). Важно! Лучше вместо этого использовать mod[on=all]
reload-on-update Полезный, но редакоиспользуемый атрибут. Если !=0, то при обновлении поля, значение будет загружено заново из базы / или взято из значения по умолчанию По умолчанию 0 — т.е. при обновления поля в нём остаётся значение, которое было изменено пользователем. _TODO: уточнить алгоритм работы атрибута

Настройка стиля

Атрибут Описание Примечание
prompt-bold Делает жирным prompt
label-bold Делает жирным label Только для [type=checkbox]
align Пока не реализовано (_TODO) (Но, кстати, этот атрибут есть в html/text)
inline Расположить [type=radiobutton] или [type=checkboxgroup] значения в одну строку
pullright Для полей [type=dropdown] значение !=0 говорит, что выпадающий список должен быть выравнен относительно правого края поля. В фильтрах по умолчанию - 1, в формах — 0
dropup Для полей [type=dropdown] значение !=0 говорит, что выпадающий список должен открываться наверх. По умолчанию 0 — т.е. открывать вниз. При этом вне зависимости от значения, расчёт открытия будет вестись автоматически исходя из положения поля на странице — так, чтобы оно поместилось. Просто будет отдаваться предпочтение том или иному варианту

Удобство работы с формой

Атрибут Описание Примечание
select Если "auto", то будет автоматически произведен выбор поля, если там всего одно ненулевое значение.
hide-if Возможные значения: "empty", "one choice".
focused Если !=0, то при открытии поля ставит фокус на поле.
tabindex Позволяет менять последовательность, в которой будут переключаться поля по нажатию клавиши TAB. При этом -1 — не переключаться на поле при нажатии клавиши TAB. Если 0 или не задан, то устанавливается автоматически, как в HTML. Аналогичен соответствующему атрибуту в HTML. Использовалось активно в модуле сменных медосмотров, можно посмотреть там
preserve Сохранять значения поля в COOKIES при выборе фильтра или при сохранении формы. При открытии формы или списка, значение поле будет браться из соответствующей COOKIE. При этом COOKIES общие для фильтров и полей. Имя переменной в COOKIES определяется на основе атрибута preserve-name. Удобно использовать для полей «Организация» и «Подразделение», а также для фильтров-«настроек» — например, «включать дочерние подразделения» или «показывать дату в формате ГГГГ-ММ-ДД». ВАЖНО В некоторых модифицкациях QForm не работает без явного указания preserve-name. Мы это исправили, но ещё не во всех проектах
preserve-name Имя для переменной COOKIE, в которую сохранять значение поля К значению поля в куках добавляется префикс ps_
preserve-expires Срок хранения COOKIE. Аналогичен параметру expires при сохранении COOKIE По умолчанию 0 — т.е. до конца сессии
speech Включает голосовой ввод для поля [ ] Раньше работало. Сейчас временно не работает (_TODO)

Управление доступом

Атрибут Описание Примечание
minrole Минимальная роль, которая должна быть у пользователя, чтобы было доступно редактирование поля _TODO: Вставить ссылку на статью про управление правами доступа

Настройки режима просмотра / печати

Атрибут Описание Примечание
printable Если =0, то поле не будет выводиться при открытии формы на просмотр По умолчанию 1
print-empty Не выводит поле при открытии формы на печать / просмотр, если оно пустое Толком нигде пока не тестировалось, хотя функционал есть уже очень давно

Подсказки для ввода

Атрибут Описание Примечание
placeholder Текст, который будет написано в «фоне» на самом поле, когда оно ничем не заполнено. Действие аналогично действую соответствующего атрибута в HTML. _TODO: Вставить пример.
hint Синоним placeholder. Используется только если placeholder не задан
help
helpkey, help-key
helptype, help-type

Обработка при сохранении

Атрибут Описание Примечание
null
clear

Модификация HMTL / CSS полей

Атрибут Описание Примечание
inputparams
cssstyle, css-style
cssclass, css-class

Ограничение текстового ввода

В особенности актуально для полей типов combobox и autocomplete.

Атрибут Описание Примечание
ucfirst
strict
strict-punct
strict-space
trim Если 1, то при сохранении будут обрезаться начальные и концевые символы из trim-chars.
trim-chars
mask
mask-strict
noreturn Запрещает перенос строки у [type=textarea] поля.

Ограничение числовых полей (для типов: int, double, float, money)

Атрибут Описание Примечание
unsigned
minval
maxval
stepper
ctrlstep
shiftstep

Ограничение полей даты и времени (для типов: date, datetime, time)

Атрибут Описание Примечание
startdate
startdate-field
startdate-shift
starttime
enddate
enddate-field
enddate-shift
endtime

Обработка полей с choice (для типов: dropdown, radiobutton, checkboxgroup, autocomplete)

Атрибут Описание Примечание
unique
allowhtml Может перезаписывать allowhtml у всех choice. Лучше не использовать.
nowrap Не переносить строку, если не помещает по ширине (в таком случае, она будет обрезаться). По умолчанию 1

Обработка полей типа dropdown

Атрибут Описание Примечание
extended Показывать строку поиска. По умоланию: "0"
external-select-url
external-select

Обработка полей типа checkboxgroup

Атрибут Описание Примечание
extended Показывать строку поиска. По умоланию: "0"
separator Разделитель, который будет использоваться, в случае, если сохранение идёт в поле таблицы По умолчанию: ","

Обработка полей типа autocomplete

Атрибут Описание Примечание
restricted
allowbr Только для [type=autocomplete]
search-anywhere
separator

Ограничение полей файлов и изображений (для типов: file, img)

Атрибут Описание Примечание
multiple Если 1, то допустима множественная загрузка файлов. Не уверен, как это работает. [ ] _TODO: Описать
accept MIME-типы для файлов, которые допустимо загружать
file-size Допустимый минимальный размер файла. Не уверен, как это работает. [ ] _TODO: Описать

Обработка полей типа password

Атрибут Описание Примечание
repeat Крайне редко используемый атрибут. Актуален только для [type=password]. Если 1 — то после ввода пароля будет предложено повторить его. По умолчнию 0. Не уверен, что атрибут работает.

Обработка полей типа qmap

Атрибут Описание Примечание
icon Для [type=qmap] В разработке. Не тестировалось
class Для [type=qmap] В разработке. Не тестировалось
btntitle Для [type=qmap] В разработке. Не тестировалось
embeded Для [type=qmap] В разработке. Не тестировалось

results matching ""

    No results matching ""