Поля компонента

Управление полями доступно на странице управления компонента во вкладе “Поля”. Также все поля компонента отображаются в левой панели под названием компонента при нажатии на иконку плюса. Добавление нового поля возможно как на странице со списком полей, так и при наведении на название компонента (надо нажать на появившуюся иконку).

Общие настройки поля

Название поля

Заполняется латинскими буквами: Name, Image, Text, Description, Price и пр.. При добавлении этого поля в таблицу MessageX, где хранятся данные этого компонента, будет добавлена колонка с этим названием.

Описание поля

Название, которое будет фигурировать в формах добавления/изменения: Имя, Фото, Текст, Описание, Цена и пр.

Связанное поле

В данное поле можно поместить дополнительное содержимое: js-скрипт, строку-подсказку, html-код и т.д. В содержимом можно использовать макропеременную %ID, при выводе она будет заменёна на идентификатор поля. Вывод содержимого происходит для поля с именем $field_name компонента $class_id. Если $class_id не указан - автоматически подставляется текущий класс. Для вывода содержимого в нужном месте воспользуйтесь функцией:

nc_field_extension($field_name, $class_id = null);

Примеры вывода:

# Вывод содержимого из поля Name
echo nc_field_extension('Name');

# Вывод содержимого из поля Caption, компонент №579
echo nc_field_extension('Caption', 579);

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

Примечание. Внизу этого поля, как и у многих других, выводятся галочки “включить редактор”, “переносить строки” и “на весь экран”, которые могут помочь при редактировании большого количества кода в поле.

Обязательно для заполнения

Если настройка установлена, то для сохранения формы добавления/изменения объекта потребуется заполнение этого поля компонента.

Возможен поиск по данному полю

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

Использовать в табличном списке объектов

В панели администрирования на странице раздела (вкладка редактирования) в правой части шапки есть иконка переключения между шаблонами отображения объекта: стандартным и табличным. Табличное представление строится автоматически: на каждый объект приходится строка таблицы. Если установить эту настройку для некоторого поля, то значение этого поля будет отображаться в таблице для каждого объекта.

Приоритет

Значение данного поля определяет приоритетность вывода полей в компоненте и далее в формах добавления/редактирования объекта.

Значение по умолчанию

Будет записано данное значение, если поле не заполнено.

Тип доступа к полю

Если объекты этого компонента будут доступны для добавления/изменения посетителями сайта, некоторые поля можно сделать доступными только администраторам (пользователям с административными полями): например, пользователь может оставить вопрос или претензию, а администратор - ответить на ее; в таком случае полю “Ответ” надо присвоить доступ только для администратора. Также поле можно сделать недостуным никому: это может быть применимым, например, для вычисляемых полей, значения которых формируются программно при добавлении/изменении объекта.

Типы полей и зависимые от типа настройки

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

Строка

Cимвольное поле, максимально может содержать 255 символов.

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

• Email — при добавлении/изменении значения в поле будет проверяться его соответствие формату электронной почты
• URL — при добавлении/изменении значения в поле будет проверяться его соответствие формату URL
• HTML-строка — формат, при выборе которого HTML-разметка в переменной $f_ИмяПоля выводится без изменений (для поля без выбранного формата HTML-разметка экранируется). Данный тип доступен с версии 5.8.0.17311.
• Телефон — при добавлении/изменении значения в поле будет проверяться его соответствие формату телефонного номера.
  Телефонный номер состоит из 7 цифр с необязательным кодом города (он может быть в скобках) и кодом страны ( перед ним может стоять знак «+» ). Группы цифр могут разделяться символом «-», пробелы и знаки табуляции игнорируются. Примеры правильного заполнения поля с форматом «Телефон»:
  1234567
  123-45-67
  8-123-45-67
  8 (000) 123-45-67
  8-000-123-45-67
  +7 000 123 45 67
• Тэги — формат, необходимый для модуля «Облако тегов».
• Пароль — формат, необходимый для создания поля, символы в котором будут скрыты «звёздочками»

Для вывода записи данного типа достаточно указать переменную:

<?= $f_имяполя; ?>

Для данного типа поля можно указать опцию «Транслитерация», с помощью которой будет формироваться ключевое слово объекта.

Целое число

Формат для этого типа поля не предусмотрен. В поле данного типа может быть введено только целое число (1, 56, 1024, 56255 и т. д.).

Для вывода записи данного типа достаточно указать переменную:

<?= $f_имяполя; ?>

Текстовой блок

Поле (для ввода будет использован элемент формы <textarea>). Для этого типа поля доступны следующие параметры:

• разрешать ли HTML-теги
• превращать перенос строки в тег <br/>
• встроить ли визуальный редактор в поле для редатирования. Настроить панели можно настроить в меню «Настройки → Настройки WYSIWYG»
• размер текстового блока

Для вывода записи данного типа достаточно указать переменную:

<?= $f_имяполя; ?>

Для использования типографирования текста включите одноимённую опцию

Также для типографирования можно воспользоваться функцией nc_format_typo().

Список

Список значений (для ввода будет использован выпадающий список <select>); возвращает значение указанной записи списка. В поле «Формат» можно указать латинское название списка (название таблицы), содержимое которого будет использоваться при выводе списка возможных значений.

Пример: при заполнении анкеты нужно сделать выбор города пользователем из выпадающего списка. Для этого нужно создать сам список с перечислением городов и подключить его к создаваемому полю. Если список носит название «Region», в поле «Формат» нужно будет вписать название списка, то есть «Region».

Для вывода данных в компоненте будут доступны переменные:

• $f_имяполя — содержит выбранное из списка значение.
• $f_имяполя_id — содержит ID выбранного значения.
• $f_имяполя_value — содержит значение дополнительного поля выбранного элемента списка.
• $f_имяполя_settings — массив с пользовательскими настройками выбранного элемента списка.

В том случае, если в поле «Формат» ввести только название списка, в форме добавления или редактирования будет отображаться выпадающий список. Выпадающий список можно изменить на ряд radiobutton'ов дописав в имени списка radio через двоеточие. Таким образом «Region» будет изменён на «Region:radio».

Логическая переменная

Логическое поле (да/нет); при выводе записи возвращает 1 (да) или 0 (нет). Если у поля параметр «обязательно для заполнения» выключен, то будет выводиться блок radiobutton'ов (не важно, да, нет). Если этот параметр включен, будет выводиться checkbox. Формат для этого типа поля не предусмотрен.

Пример: при заполнении анкеты пользователь при ответе на вопрос может поставить галочку, если ответ утвердительный:

В компоненте можно сделать вывод переменной:

<?= $f_mobile?>

Но в этом случае будет выведена только цифра 1 или 0, поэтому лучше используя проверку вывести обычное описание:

Мобильные телефон: <?= ($f_mobile==1?"Есть":"Нет")?>

Файл

Поле типа «файл» (для ввода будет использован элемент формы <input type="file">, возвращает URL файла, его настоящее название и размер. В поле «формат» может быть указан максимальный размер файла в байтах. При необходимости через двоеточие может быть указан также и возможный тип файла (mime type).

Например:

• 1048576 — файл объёмом не более 1048576 байт любого типа.
• 200000:application/pdf — файл объёмом не более 200000 байт, только pdf-файл.
• 2500000:image/* — файл объёмом не более 2500000 байт, только изображение (jpg, png и т.д.).
• 2000000:video/* — видеофайл любого типа.
• 200000:image/jpg,video/* — файл объёмом не более 2500000 байт, только изображение jpg, либо видеофайл любого типа

Тип файловой системы влияет на вариант загрузки и хранения файла:

1. Простая

Файлы хранятся в директории /netcat_files/. Имя файла на диске состоит из идентификатора поля, символа подчеркивания, идентификатора сообщения и расширения файла.

2. Стандартная

На диск записывается оригинальное имя файла (если оно содержит кириллицу — то символы переведутся в «транслит», если такой файл уже существует, то к новому добавится числовой индекс через подчеркивание). По умолчанию, файл записывается в директорию netcat_files/sub/cc/, где sub — номер раздела, сс — номер компонента в разделе.

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

$f_ИмяПоля['folder'] = 'ИмяДиректории';

Имя директории должно содержать только латинские буквы, подчеркивание и дефис. Для разделений директорий между собой (для создания вложенной структуры) используется символ «/», например:

$f_Picture['folder'] = 'Image/foto';

3. Защищённая

Так же как и в случае с «стандартной» файловой системой, файлы записываются в директорию netcat_files/sub/cc/. На диск записывается захэшированное имя файла. Так же в таблице Filetable для каждого файла создается своя запись. Такой тип хранения файлов затрудняет получение файла подбором имени, но в этом случае создаётся нагрузка на базу данных.

Для файлов этого типа можно задать атрибут «Закачиваемый». В этом случае при обращении к файлу браузер предложит его сохранить, а не показать. Так же для файлов данного типа можно считать количество обращений к ним, для этого надо задать атрибут «Считать количество скачиваний».

Может быть иконкой

Если этот признак установлен, то в форме добавления/изменения объекта у данного поля появится опция выбора иконки из библиотеки системы. 

Структура таблицы Filetable имеет следующий вид:

В списке объектов и на странице просмотра объекта, при наличии поля типа «Файл», доступны переменные:

• $f_имяполя — ссылка на файл
• $f_имяполя_url — прямая ссылка на файл (для ФС «Защищенная»)
• $f_имяполя_name — оригинальное (изначальное) имя файла
• $f_имяполя_type — MIME-тип файла
• $f_имяполя_size — размер файла в байтах
• $f_имяполя_download — количество запросов (скачиваний) файла (при ФС «Защищенная»)

В условие добавления:

• $f_имяполя — массив с ключами name, size, type

В действии после добавления:

• $f_имяполя — ссылка на файл
• $f_имяполя_name — оригинальное (изначальное) имя файла
• $f_имяполя_type — MIME-тип файла
• $f_имяполя_size — размер файла в байтах

Работа с файлами для сайтов, разделов, макетов дизайна и пользователей аналогична.

Для изображений доступны дополнительные функции:

• $f_Image->as_img($attributes) - вывод тега img с заполненным адресом файла атрибутом href и атрибутами из массива $attributes. В этом массиве хранятся пары “ключ-значение” для атрибутов тега img; например, для вывода атрибута title со значением “Фотография” надо написать так: $f_Image->as_img(array('title' => 'Фотография’));
• $f_Image->as_icon() - вывод изображения в виде иконки.

См. также: создание нескольких вариантов изображения с сохранением исходного файла.

1. Уменьшение изображения

Укажите ширину и высоту для изображение. В том случае, если снимок будет превышать указанные параметры, снимок будет пропорционально уменьшен.

2. Обрезка изображения

Для обрезки необходимо задать 4 параметра: точки начала (лево, верх) X0, Y0 и точки конца (право, низ) X1, Y1

3. Создание картинки-предпросмотра

Как правило, такие изображения используются для отображения анонсов к просмотру объекта (список статей, новостей, аватарка и т. д.). Для создания превью укажите желаемые размеры: ширину и высоту.

Вывод картинки-превью:

$f_имяполя_preview_url

Число с плавающей запятой

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

Например: 2000,52 руб.

Дата и время

В форме редактирования/добавления объекта для этого поля будет выведено 6 полей даты и времени. Возможно использование календаря для выбора даты (при установке соответствующей галочки).

В поле «Формат» можно указать значения:

• event —  при добавлении записи в это поле будет автоматически подставляться текущая дата и время при условии, что поле обязательно для заполнения.
• event_date — в форме добавления/изменения будут показываться только поля даты (без времени), и при добавлении записи в это поле будет автоматически подставляться текущая дата при условии, что поле обязательно для заполнения.
• event_time — в форме добавления/изменения будут показываться только поля времени (без даты) и при добавлении записи в это поле будет автоматически подставляться текущее время при условии, что поле обязательно для заполнения.

Для вывода значения поля в компоненте можно воспользоваться присущими для поля такого типа переменными:

• $f_имяполя_day — число
• $f_имяполя_month — месяц
• $f_имяполя_year — год
• $f_имяполя_hours — час
• $f_имяполя_minutes — минута
• $f_имяполя_seconds — секунда

Соответственно, эти поля пожно вариьровать между собой и использовать только нужные.

Пример: в компоненте нужно вывести дату добавления новости:

Добавлено: <?=$f_date_day."/".$f_date_month."/".$f_date_year?>

На сайте будет выведено: «Добавлено 05/04/2013». При помощи дополнительных функций вы можете обработать эти числа и получить читаемые даты: «Добавлено 5 апреля 2013 года».

Связь с другими объектами

Поле в компонентах выдаёт идентификатор связанного объекта, который можно вывести при помощи функции listQuery. Например, формат поля «Связь с другим объектом» имеет значение «22», это означает, что связанные объекты берутся из компонента с идентификатором 22. Тогда получить объект можно следующим образом:

<?=listQuery("SELECT * FROM Message22 WHERE Message_ID=$f_имя_поля", '$data[Title] // $data[Date]')?>

где «имя_поля» — связь с другим объектом. Привязать объект можно при добавлении или редактировании сообщения в разделе, к которому прикреплён компонент с таким полем.

В поле «Формат» следует указать номер компонента для привязки, если связь осуществляется с компонентами. В случае связи системных таблиц, указывается название системной таблицы (Subdivision, Sub_Class, User, Catalogue...). Примеры правильного оформления поля «Формат» для связи с другими объектами:

1 – номер компонента
2:Name – номер компонента и  заголовка объекта
2:"CONCAT(Message_ID, ': ', Announcement)" – номер заголовка объекта и расширение запроса
Subdivision – имя системной таблицы
User:CONCAT(FirstName, ' ', LastName) – имя системной таблицы и расширение запроса

Расширение запроса используется для получения данных об объекте, например заголовка. Расширяемый запрос имеет вид:

SELECT <ID_Field> AS ItemID, CONCAT( [...] ) AS ItemCaption FROM <Table> WHERE <Constraints>

Как правило, использование данного поля используется редакторами или администраторами сайта, так как поле создаёт ссылку, при нажатии на которую появляется окно с выбором подключаемого раздела, компонента и объекта.

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

1. На сайте необходимо создать систему тикетов. Каждому тикету назначается пользователь-исполнитель.

• В компонент тикета нужно добавить поле «Исполнитель» (User) , тип «Связь с другими объектами».
• В формат поля прописать

  User:"CONCAT(ForumName, '<div style="color: gray;">', Login, ' | ', Email, '</div>')"

  где: User — таблица со списком пользователей; ForumName, Login и Email — поля пользователя в таблице.
• В окне выбора исполнителя отобразится список вида:
  
• В месте вывода исполнителя составить запрос:

  <?= listQuery("SELECT * FROM User WHERE User_ID=$f_User","\$data[ForumName] (\$data[Login] \$data[Email])");?>

2. На сайте есть раздел с мастер-классами и раздел с преподавателями. При добавлении мастер-класса нужно сделать возможность выбора преподавателя. Для этого:

• В компоненте мастер-класса нужно добавить поле «Преподаватель» (Master_ID), тип «Связь с другими объектами».
• В формат поля прописать ID компонента и название поля. Например: 16.
• В месте вывода составить запрос

  <?= listQuery("SELECT * FROM Message16 WHERE Message_ID=$f_Master_ID","\$data[Name] \$data[Surname]");?>

Множественный выбор

Данный тип поля (компонента, раздела, сайта, пользователей) позволяет пользователю выбирать несколько элементов из списка.

Создание поля

В «типе поля» при добавлении\редактировании поля компонента (или поля из системной таблицы) укажите «Множественный выбор».

Поле «Формат» в этом случае обязательно для заполнения. Оно должно содержать как минимум латинское название списка (название таблицы). Так же в поле «Формат» можно задать вид (select или checkbox) элемента, который будет выводиться по умолчанию в формах добавления, изменения и поиска.

По умолчанию используется select с высотой равной трем. Для изменения элемента укажите его через двоеточие после имени таблицы. При использовании select можно также задать высоту этого элемента (количество одновременно отображаемых элементов) опять же через двоеточие после слова «select»

Примеры заполнения поля формат:

Форма добавления, изменения

По умолчанию, как было сказано выше, элемент (select или checkbox) берётся из формата поля. Т.е. Если вы используете форму «по умолчанию», то формат вывода элемента будет взят из формата поля.

В альтернативных формах можно использовать функцию

string nc_multilist_field($field_name, $style = "", $type = "", $classID = "", $caption = false, $selected = false, $disabled = false, $getData = false)

Она возвращает строку с HTML-кодом.

Третьем параметром можно указать тип элемента: select или checkbox, так же для элемента select можно задать высоту. Этот параметр имеет вид аналогичный, как и у формата поля, за исключением того, что здесь не нужно указывать таблицу. По умолчанию так же используется select с высотой 3.

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

nc_multilist_field('countrySelect', '', 'checkbox', $classID, 1)
nc_multilist_field('countrySelect', '', 'select:5', $classID, 1)

Отображение элементов

При использовании компонента с полем «Множественный выбор», в списке отображения объектов и в полном выводе объекта доступна переменная $f_ИмяПоля, которая на самом деле является массивом, содержащим выбранные элементы, так же доступен массив $f_ИмяПоля_id, содержащим id выбранных элементов.

Для примера рассмотрим ситуацию, когда у объекта выбраны элементы из списка «Город» (Region):

1.Москва, 59.Екатеринбург, 110.Магадан.

Поле имеет имя city.

Тогда в массиве $f_city первый элемент ($f_city[0]) это «Москва», второй элемент «Екатеринбург» и третий - «Магадан», а массив $f_city_id имеет следующий вид:

$f_city_id[0] = 1, $f_city_id[1] = 59, $f_city_id[2] = 110

Для вывода этих элементов есть смысл перевести массив в строку. Это можно сделать с помощью функции nc_array_to_string().

Так же для перевода массива в строку можно использовать функцию php join (подробнее см. http://ru2.php.net/join).

Все это справедливо и при использовании поля типа «Множественный выбор» в системных таблицах.

Для отображения списка создайте шаблон вывода вида:

<?php
$templ['prefix']  = '<ui>';
$templ['element'] = '<li>%ELEMENT</li>';
$templ['suffix']  = '</ui>';
?>

поместите его в поле «Системные настройки», а в месте вывода пропишите:

<?= nc_array_to_string($f_pole, $templ)?>

Также можно воспользоваться следующим способом:

<?= nc_array_to_string($f_pole,
array( 'prefix' => 'List:<br>',
'element' => '%I. %ELEMENT',
'divider' => '<br>',
'suffix'  => 'end' )
)?>

Множественная загрузка файлов

Данный тип поля (компонента, раздела, сайта, пользователей) позволяет пользователю добавлять неограниченное количество файлов. При этом, доступна мультизагрузка путём перетаскивания множества файлов на поле загрузки либо выбор множества файлов в окне обзора.

Создание поля

В «типе поля» при добавлении\редактировании поля компонента (или поля из системной таблицы) укажите «Множественная загрузка файлов».

Для изображений доступны дополнительные функции.

См. также: создание нескольких вариантов изображения с сохранением исходного файла.

1. Уменьшение изображения

Укажите ширину и высоту для изображение. В том случае, если снимок будет превышать указанные параметры, снимок будет пропорционально уменьшен.

2. Обрезка изображения

Для обрезки необходимо задать 4 параметра: точки начала (лево, верх) X0, Y0 и точки конца (право, низ) X1, Y1

3. Создание картинки-предпросмотра

Как правило, такие изображения используются для отображения анонсов к просмотру объекта (список статей, новостей, аватарка и т. д.). Для создания превью укажите желаемые размеры: ширину и высоту.

Форма добавления, изменения

Для отображения поля в альтернативных формах нужно использовать метод form объекта f_названиеПоля, возвращающий строку с HTML кодом.

string $f_multifileFieldName->form()

Данная конструкция используется «по умолчанию».

Также объект поля содержит в себе объект настроек этого поля.

string $f_multifileFieldName->settings->settingsName()

Методы могут использоваться в любой последовательности, а также несколько подряд.

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

<?= $f_Img->settings->resize(600, 600)->preview(150, 150)->path('/my_img/')->min(2)->max(5);?>
<?= $f_Img->form();?>

Метод set_description() не является методом настроек и его нужно использовать отдельно:

<? $f_Img->set_description("Имя поля");?>
<?= $f_Img->form();?>

Отображение элементов в списке объектов и в полном выводе

Для отображения поля сначала необходимо задать его шаблон в системных настройках. Для этого необходимо присвоить переменной f_названиеПоля_tpl массив, который может содержать следующие элементы:

В элементе record могут быть следующие макропеременные:

Путь к Preview указан только если была создана уменьшенная копия изображения.

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

$f_Img_tpl = array(
    'prefix' => "<div>",
    'record' => "<div>%i%. %Name%</div><a href='%Path%'><img src='%Preview%' /></a>",
    'divider' => " ",
    'suffix' => "</div>",
    'i' => 1
);

После задания шаблона в списке объектов и в полном отображении объекта можно использовать переменную $f_имяполя для вывода его содержимого.

Так же, в списке объектов и в полном отображении можно использовать следующие методы:

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

# Случайная фотография
<?= $f_Img->get_random_record()?>

# Вывод одной фотографии со своим шаблоном (например, используя в качестве обложки альбома)
# Для этого вывода нужно добавить шаблон отображения
<?= $f_Img->set_template($img_tpl)->get_record(1)?>

Используя функцию nc_load_multifield() можно получить объект поля в любом месте системы.

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

foreach ($f_Img->to_array() as $file) {
    // $file — объект, у которого доступны свойства Name, Size, Path, Preview
    echo basename($file->Path) . " — " . nc_bytes2size($file->Size) . "<br>";
}