Добавление полей в список в Wepps Platform

Введение

Данное руководство описывает процесс добавления новых полей в существующие списки (таблицы) платформы Wepps. Поля определяют структуру данных и интерфейс редактирования в административной панели.

Основные концепции

Что такое поля списка

Поля списка — это столбцы таблицы базы данных с метаданными для отображения в административном интерфейсе. Каждое поле содержит:

• Имя поля (Field) — название столбца в таблице БД
• Тип поля (Type) — определяет визуальный компонент ввода (text, textarea, select, checkbox и т.д.)
• Название (Name) — человекочитаемое название для интерфейса
• Обязательность (Required) — флаг обязательности заполнения
• Приоритет (Priority) — порядок отображения в форме (если не указан, платформа сама добавит значение)
• Видимость (IsHidden) — показывать ли поле в админке

Таблица s_ConfigFields

Все поля списков хранятся в системной таблице s_ConfigFields:

Способ 1: Добавление через интерфейс админки

Шаг 1. Откройте таблицу Настройки полей

1. Войдите в административную панель /_wepps/
2. Перейдите в раздел Настройки → Настройки полей (s_ConfigFields)

Шаг 2. Создайте новый элемент

1. Нажмите кнопку "Добавить элемент"
2. Заполните форму:

TableName: Products
Field: Price
Name: Цена товара
Type: text
Required: 1
Priority: 10
IsHidden: 0

Шаг 3. Сохраните изменения

1. Нажмите кнопку "Сохранить"
2. Новое поле появится в форме редактирования указанной таблицы

Пример: Добавление поля "Артикул" для товаров

Параметры:

• TableName: Products
• Field: ArticleCode
• Name: Артикул
• Type: text
• Required: 0
• Priority: 5
• IsHidden: 0

Результат: В форме редактирования товара появится текстовое поле "Артикул".

Способ 2: Загрузка полей из Excel

Этот способ удобен для массового добавления полей или миграции конфигурации между проектами.

Шаг 1. Подготовьте Excel-файл

Создайте Excel-файл (.xlsx) со следующей структурой:

Лист 1 (название листа не важно)

Строка 1 (заголовки — обязательны!):

Примеры данных:

Описание столбцов:

• Список — имя таблицы (например: Products, News, Contacts)
• Наименование — отображаемое название поля в админке
• Alias — техническое имя поля (название столбца в БД)
• Тип — тип поля (см. раздел "Типы полей")
• Группа — группа для визуального разделения (обычно FieldDefault, FieldDopoln1, FieldDopoln2)
• Описание — дополнительное описание поля (необязательно)

Требования к файлу:

• Первая строка — заголовки: Список, Наименование, Alias, Тип, Группа, Описание
• Названия заголовков должны точно совпадать (с учётом регистра!)
• Формат файла: .xlsx (Excel 2007 и выше)
• Кодировка: UTF-8
• Обязательные столбцы: Список, Наименование, Alias, Тип
• Опциональные столбцы: Группа, Описание

📎 Скачать шаблон: add-fields-template.xlsx

Шаг 2. Откройте системное расширение "Загрузки из Excel"

1. Войдите в административную панель /_wepps/
2. Перейдите в раздел Системные расширения → Загрузки из Excel

Шаг 3. Выберите цель загрузки

1. В поле "Цель" выберите: "Списки: установка полей"
2. Нажмите кнопку "Выбрать файл" и загрузите подготовленный Excel-файл

Шаг 4. Выполните загрузку

1. Нажмите кнопку "Далее"
2. Система обработает файл и добавит новые поля в таблицу s_ConfigFields
3. Проверьте результат в разделе Настройки полей

Преимущества загрузки из Excel

✅ Массовое добавление — можно добавить десятки полей за один раз
✅ Удобное редактирование — редактирование в Excel быстрее, чем через веб-форму
✅ История загрузок — все файлы сохраняются в БД (список Загруженные файлы, s_UploadsSource) с возможностью повторного использования
✅ Миграция — легко переносить настройки между проектами
✅ Документирование — файл служит документацией структуры данных

Типы полей

Базовые типы

Типы для связей со списками

Специальные типы

Связь с другими списками

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

TableName: Products
Field: BrandId
Name: Бренд
Type: select::Brands

При этом в выпадающем списке будут отображаться элементы из таблицы Brands.

Варианты связей:

• select::TableName — одиночный выбор из списка
• select_multi::TableName — множественный выбор
• remote::TableName — одиночный выбор через AJAX (для больших списков)
• remote_multi::TableName — множественный выбор через AJAX
• dbtable::TableName — аналог select
• dbtable_multi::TableName — аналог select_multi

Практические примеры

Пример 1: Добавление полей для товаров

Задача: Добавить поля "Вес", "Страна производства" и "Гарантия" для товаров.

Excel-файл:

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

Пример 2: Добавление скрытых служебных полей

Задача: Добавить служебное поле для хранения данных из внешней системы.

TableName: Products
Field: ExternalId
Name: ID во внешней системе
Type: text
Required: 0
Priority: 999
IsHidden: 1

Результат: Поле будет храниться в БД, но не отображаться в админке.

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

Задача: Добавить обязательное поле "Цена" для товаров.

TableName: Products
Field: Price
Name: Цена (руб.)
Type: digit
Required: 1
Priority: 5
IsHidden: 0
FGroup: FieldDefault

Результат: При сохранении товара без указания цены будет выведена ошибка.

Пример 4: Добавление мини-таблицы характеристик

Задача: Добавить поле для хранения характеристик товара в виде таблицы.

TableName: Products
Field: Specifications
Name: Характеристики
Type: minitable::Параметр,Значение,Единица
Required: 0
Priority: 50
IsHidden: 0
FGroup: FieldDefault

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

Важные замечания

⚠️ Автоматическое создание столбцов:

Платформа автоматически создаёт столбцы в таблице БД при добавлении поля в s_ConfigFields:

• Если столбец не существует → он будет создан с типом, соответствующим указанному в поле Type
• Если столбец уже существует → его тип будет обновлён (если отличается)

💡 Соответствие типов поля и столбца БД:

⚠️ Перед добавлением полей:

1. Проверьте уникальность — не должно быть дублирующихся записей (TableName + Field)
2. Соблюдайте приоритеты — поля с меньшим Priority отображаются выше
3. Выбирайте правильный тип — от типа зависит структура столбца в БД

⚠️ При загрузке из Excel:

1. Проверьте формат файла — только .xlsx
2. Не используйте объединённые ячейки — каждая ячейка должна быть отдельной
3. Проверьте заголовки — названия столбцов должны точно совпадать
4. Создайте резервную копию — перед массовой загрузкой сделайте бэкап БД

⚠️ При миграциях между проектами:

При переносе таблиц и полей между проектами (например, через SQL-дампы или Excel) необходимо обеспечить синхронизацию:

1. Структура таблиц в БД должна соответствовать записям в s_Config
2. Столбцы таблиц должны соответствовать записям в s_ConfigFields
3. Порядок миграции:
   • Сначала создайте таблицы (или добавьте записи в s_Config)
   • Затем добавьте поля (записи в s_ConfigFields)
   • Платформа автоматически создаст/обновит структуру БД

💡 Рекомендация: При миграции используйте загрузку полей через Excel — это обеспечит автоматическое создание столбцов с правильными типами данных.

Проверка результата

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

1. Перейдите в список, для которого добавляли поля
2. Откройте любой элемент на редактирование
3. Убедитесь, что новые поля отображаются в форме
4. Проверьте сохранение данных

Удаление полей

Для удаления поля из списка:

1. Перейдите в Настройки → Настройки полей (s_ConfigFields)
2. Найдите нужное поле
3. Удалите запись

⚠️ Внимание: Удаление записи из s_ConfigFields автоматически удалит столбец из таблицы БД! Все данные в этом столбце будут безвозвратно потеряны. Перед удалением убедитесь, что:

• Данные в этом поле больше не нужны
• Создана резервная копия БД (если данные могут понадобиться)

Заключение

Два способа добавления полей позволяют выбрать оптимальный подход в зависимости от задачи:

• Интерфейс админки — для быстрого добавления 1-2 полей
• Загрузка из Excel — для массового добавления и миграции конфигурации

Правильная настройка полей обеспечивает удобный интерфейс редактирования и корректное хранение данных в платформе Wepps.