Работа с tables.json
Создание новой сущности начинается с models/system/tables.json или отдельных json файлов в models/system/tables. Частично это уже описано в статье “Профайл класса и клиентского объекта”.
Практика показывает, что с декомпозированный tables.json не всегда удобно работать, поэтому выносить описание классов в отдельный файл имеет смысл, если это несколько классов имеющих общее назначение. Точно не стоит создавать отдельный файл под каждый отдельный класс, это очень не удобно.
Реализованные в ядре классы описаны в tablesCore.json или вынесены в отдельные файлы в models/system/tables (например, order.json содержит все что связано с заказами).
Сам tables.json содержит начальное (неполное), описание класса и его полей. Остальные настройки самого класса проставляются автоматически и доступны для редактирования через интерфейс системы. Таким образом, вам необходимо задать самые базовые настройки и короткое описать только тех полей, которые вам нужны. Помимо описанных вами полей система автоматически добавит несколько системных полей, которые однако могут быть использованы в пользовательской логике, например поле created.
Автоматически добавляемые поля
Здесь мы немного повторяемся со статьей “Автоматически создаваемые поля”.
created. Тип datetime. Автоматически проставляется при создании любой записи.
created_by_user_id. Автоматически проставляется ID пользователя, создавшего запись.
created_by_user. Виртуальное поле, по умолчанию не видимое, а значит и не участвующее в запросах. Поле подтягивает lastname из таблицы пользователей. При необходимости вы можете его сделать видимым и пользоваться.
updated. Тип datetime. Автоматически проставляется при изменении любой записи.
last_edited_by_user_id. Автоматически проставляется ID пользователя, изменяющего запись.
last_edited_by_user. Виртуальное поле, по умолчанию не видимое, а значит и не участвующее в запросах. Поле подтягивает lastname из таблицы пользователей. При необходимости вы можете его сделать видимым и пользоваться.
deleted. Тип datetime. Автоматически проставляется при удалении записи.
deleted_by_user_id. Автоматически проставляется ID пользователя, удаляющего запись.
deleted_by_user. Виртуальное поле, по умолчанию не видимое, а значит и не участвующее в запросах. Поле подтягивает lastname из таблицы пользователей. При необходимости вы можете его сделать видимым и пользоваться.
Иерархические поля.
Система может определить, что таблица ссылается сама на себя и следовательно является иерархической. Для таких таблиц будут автоматически созданы следующие поля: node_deep, parents_count, children_count. См. описания базовых концепций ядра.
Заполнение tables.json
Заполняйте, только самое базовое, что необходимо. Подробнее см. ниже.
Каждый класс, это json объект со следующей структурой:
Ключ объекта в файле, это имя класса.
Оно должно удовлетворять требованиям наименований таблиц в СУБД (в данной версии это MariaDB). Так как класс в ядре это и таблица в базе и класс в javascript (см. базовые концепции), то именно по этому имени разработчик сможет вызывать базовые методы (и переопределять их или писать свои если потребуется). При этом в js (а точнее в ts), класс будет конечно называться с Большой буквы, согласно требованиям JS.
Этот ключ должен полностью совпадать с полем name в объекте, в поле “profile” (example.profile.name должно быть “example”, а user.profile.name должно быть “user”).
Поле profile
Это объект, содержащий настройки самого класса (а не его полей). Здесь в принципе могут быть любые поля из описания в статье “Поля профайла самого класса”, но обычно описаны только 3-5 полей.
name. Уже упомянутый выше (должен совпадать с ключом всего JSON объекта класса).
name_ru. Не обязан быть на русском языке, не смотря на наименование поля. Это user friendly наименование класса. Именно оно будет отображено в клиентских компонентах таблиц и форм. Именно оно будет подставляться в генерируемые сообщения при манипуляциях с данными этого класса (см. ending).
ending. Используется в русском языке для добавления склонения при формировании сообщений при манипуляциях с данными.
Например, для сущности женского рода, “Локация”, нельзя написать “Локация изменен” (при изменении записи в таблице или форме), а нужно написать “Локация изменена”. Для этого мы пишем букву “а” в поле ending и система начинает формировать сообщения правильно.
server_parent_table и server_parent_key. См. описание в основной статье.
Поле structure
Это объект объектов, где каждый объект это поле (колонка) класса.
type и length
Требует обязательного описания типа поля и его длины (для некоторых типов), в формате СУБД (MariaDB).
Наиболее распространенные:
type:“bigint”, length"20". Часто используется для поля “id”. Вы можете много где в существующем коде встретить, что он используется, в том числе, и для таблиц типа справочников, это связано с тем, что мы не уделяли этому особого внимания. Лучше используйте те типы полей, которые соответствуют ожидаемому объему данных. Обратите внимание, что если вы указали id в справочнике статусов как tinyint, а в другой таблице у вас есть поле связи status_id (ссылающиеся на таблицу статус), то status_id должен иметь тот же тип. Для удобства предоставляю здесь таблицу диапазонов числовых типов MariaDB (по версии Copilot):
| Тип данных | Размер (байт) | Диапазон SIGNED | Диапазон UNSIGNED |
|---|---|---|---|
| TINYINT | 1 | -128 до 127 | 0 до 255 |
| SMALLINT | 2 | -32,768 до 32,767 | 0 до 65,535 |
| MEDIUMINT | 3 | -8,388,608 до 8,388,607 | 0 до 16,777,215 |
| INT / INTEGER | 4 | -2,147,483,648 до 2,147,483,647 | 0 до 4,294,967,295 |
| BIGINT | 8 | -9,223,372,036,854,775,808 до 9,223,372,036,854,775,807 | 0 до 18,446,744,073,709,551,615 |
Не используйте tinyint в сочетании with length=1 как числовое поле, так как оно используется как булевое (чекбокс). Length для числовых полей определяет кол-во видимых символов и влияет на форматирование вывода в некоторых случаях (например, при использовании ZEROFILL). type:“tinyint”, length"1". Используется как булевое значение (чекбокс). Распознается системой именно как булевое, а не числовое. Из этого следует что система делает приведение типов, а также ставит по умолчанию правильный тип редактора. type:“varchar”, length"255". Используется для коротких текстов. Length может быть указан и другой, он указывает сколько максимально может храниться символов в поле. Для кодировки utf8mb4 (до 4 байт на символ) максимум — VARCHAR(16383). Подбирайте length в соответствии с данными которые собираетесь хранить, так как у MariaDB есть ограничение на максимальный размер одной строки (65535 байт (для utf8mb4 один символ может занимать до 4 байт)), то есть если у вас много полей varchar вы можете достигнуть этого ограничения. Для полей с большим объемом, лучше используйте TEXT, но по нему не строится индекс и работает медленнее. type:“text”. length указывать не нужно. Если нужны другие размерности, то вы можете использовать их, например longtext. type:“DECIMAL(15,2)”. Могут быть и другие цифры. length указывать не нужно. Используется для дробных чисел, например для суммы денег/баллов или процентов (DECIMAL(5,2)). type:“datetime”. length указывать не нужно. Используется для хранения даты и время. В базе дата и время хранятся в стандартном для MariaDB формате (YYYY-DD-MM HH:mm:ss), однако ядро автоматически занимается форматированием, так что метод get будет возвращать в user friendly формате (DD.MM.YYYY HH:mm:ss). Передавать значения в методы (add/modify и пользовательские) нужно в том же user friendly формате (DD.MM.YYYY HH:mm:ss). type:“date” и type:“time”. По аналогии с datetime, только соответствующий формат.
Пишите маленькими буквами, кроме DECIMAL.
Для поля “id” обычно также указаны следующие параметры: “notNull”: true, “autoInc”: true, “primary_key”: true, но в текущей версии ядра их можно не указывать, они будут подставлены автоматически. Поле “id” вообще можно не указывать - будет создано автоматически.
name
Это user friendly наименование поля. Именно так будет подписано поле в клиентских компонентах формах, фреймах и таблицах.
Если не указать, то в качестве name будет имя самого поля.
is_virtual, from_table, keyword, return_column, join_table, concat
См. описание полей профайла.
hint
Также можно часто встретить. Позволяет определить подсказку для поля. См. описание полей профайла.
Прочие поля
Можно и другие поля профайла описать в tables.json, но большая часть настроек делается уже в интерфейсе или оставляется по умолчанию.
См. описание полей профайла.
Синхронизация из tables.json
Когда нужный вам класс прописан в tables.json (или любом другом подходящем для этого файле (models/system/tables/*.json), его необходимо синхронизировать.
В процессе синхронизации ядро создает или дополняет (если уже был создан) таблицу в базе данных, заполняет или дополняет профайл самого класса и профайлы его полей.
Настройки класса указанные в tables.json перезапишут существующие в профайле, но только те, которые явно прописаны.
В процессе синхронизации полный профайл класса, полей класса, а также его клиентских объектов и их полей, будет сохранен в соответствующий одноименный (с классом) json файл в DB/migration.
Для некоторых системных классов (например “menu”), а также всех справочников вида “ds_<имя_справочника>”, также будет сохранены данные (непосредственно записи из этих таблиц).
На основе этих файлов другой разработчик сможет получить последние обновления структуры базы и настроек профайлов. См. “Механизм миграции базы между разработчиками”.
Чтобы запустить синхронизацию, необходимо зайти в интерфейс, в меню System -> Classes.
Далее, если класс еще не создан, создать запись в таблице (кнопка “Создать” над таблицей), заполнить только одно поле “name”. Значение должно соответствовать ключу создаваемого вами класса в tables.json.
После создания записи или если она уже была создана ранее, вызываем контекстное меню правой клавишей по этой строке и выбираем пункт “Синхронизировать с tables.json”