69
Рис. №20 ER-модель сущности “Контактное лицо”.
70
Рис. №21 ER-модель сущности “Проект”.
2.3.3. Структурная схема пакета (дерево вызова программных
модулей)
Таблица №15
Описание функций модулей.
№
п/п
Наименование модуля
Функции модуля
1.
details_company
Модуль создает сущность “Компания”, со
всем необходимым для работы
функционалом.
2.
details_contact
Модуль создает сущность “Контактное
лицо” со всем необходимым для работы
функционалом.
3.
details_project
Модуль создает сущность “Проект” со
всем необходимым для работы
функционалом.
71
2.3.4. Описание программных модулей
Рис. №22 Диаграмма наследований сущностей “Компания”, “Контактное
лицо”, “Проект”.
Каждый модуль в ИС отвечает за свою конкретную область действия. Так
как каждый из разработанных модулей необходим для хранения данных в
системе, они объявляют соответствующие сущности в системе.
Сущности в Drupal 8 — это объекты, описывающие какую-либо
единицу(ы) данных. Сущности могут быть как конфигурационные (14, 15) - в
таком случае они хранятся в специальных YAML (13) файлах, а также контент-
сущности (14) - в таком случае, значения таких сущностей хранятся в
подключенной базе данных.
Для реализации проекта все три модуля описывают свои собственные
сущности: details_company - компания, details_contact - контактное лицо,
details_project - проект.
Описание своей собственной контент-сущности состоит из множества
частей, часть данных мы можем наследовать от ядра
28
Drupal 8, тем самым,
сокращая собственный код и необходимость описывать то, что уже написано.
Так, мы можем активно использовать подход к разработке DRY (35) снижая
итоговый код и необходимое время на его написание.
Точкой старта для любой сущности - это специально созданный файл в
каком-либо модуле по пути src/Entity. Данный файл должен являться объектом,
который расширяет один из базовых объектов сущностей: ConfigEntityBase или
ContentEntityBase, для конфиг-сущностей и контент-сущностей соответственно.
28
Основной, стандартный функционал.
72
Также в Drupal имеются другие абстрактные объекты, от которых можно
наследоваться для создания сущностей и даже делать свои. В нашем случае все
три сущности наследуются от абстрактного класса RevisionableContentEntityBase,
который, в свою очередь, наследуется от ContentEntityBase и далее по цепочке.
Благодаря наследованию от RevisionableContentEntityBase все созданные для ИС
сущности являются ревизионными — хранят историю изменения всех значений
сущности, с возможность откатить или просмотреть значения на любой момент
времени.
Содержание объекта сущности с его описанием также можно разделить
на две части:
1. Аннотация (37, 39) — мета-описание сущности посредством комментария
в данной сущности.
2. Методы и свойства объекта — используются для более точного описания
поведения сущности и прочих структурных особенностей.
Так как структура всех сущностей отличается их особенностями, возьмем
для примера сущность details_contact, которая добавляет сущность “Контактное
лицо” и рассмотрим её.
Первым делом у сущности описывается её аннотация. В приложение №4
представлен листинг аннотации для данной сущности. Аннотации описываются
при помощи специальных конструкций начинающихся с @AnnotationName и
содержащие в себе значения.
Для различных типов сущностей необходимы указывать различные
аннотации. Они во много схожи и наследуются от тех же самых аннотаций, но с
небольшими различиями под специфику типа сущности. Так как все три модуля
ИС объявляют контент сущности, то описывается аннотация
@ContentEntityType.
В данной аннотации, можно выделить следующие значения, которые
влияют на то, как будет работать сущность и различные её моменты особенности:
● id - идентификатор сущности. Машинное имя, которое в дальнейшем
будет использоваться при работе с программной частью ИС. Оно может
отличаться от названия объекта сущности.
73
● label - метка сущности для людей. Как правило, данную метку
оборачивают в дополнительную аннотацию @Translation, чтобы она была
переводимой. Данное значение отображается на страницах содержимого,
где его используют.
● label_collection - метка для описания множественного смысла сущности. В
нашем случае это “Контактные лица”.
● handlers - массив с описанием хендлеров
29
сущности в котором
описывается как определенные части сущности должны быть обработаны,
ссылаясь на другие объекты, в которых эта вся логика описана.
○ view_builder - объект, отвечающий за то, как данные сущности
должны рендериться
30
. На данный момент в созданных сущностях
для ИС нет потребности в особенном рендеринге и используется
стандартный из ядра.
○ list_builder - объект, отвечающий за составление списка
добавленных сущностей на сайт для административного
интерфейса. В нем мы подключаем свой собственный объект
описывающий данную логику, которая выводит список
добавленных сущностей в виде таблицы.
Рис. №23 Результат работы list_builder сущности для сущности details_contact.
○ views_data - объект, описывающий интеграцию с модулем из ядра -
views, который позволяет при помощи UI
31
создавать различные выборки
данных, фильтрации по ним, создавать для них различные блоки и страницы и
много чего ещё. Все созданные сущности наследуют стандартный
EntityViewsData, который настраивает интеграцию автоматически на основе
29
Обработчик.
30
Rendering - визуализация.
31
User Interface - пользовательский интерфейс.
74
описания таблицы и прочих данных в аннотации, так как нам не требуется как-то
по-особенному обрабатывать данные.
○ form - массив, содержащий в себе данные о формах для работы с
сущностями. Примеры данных форм приведены в приложениях №1, 2, 3.
■ add - объект описывающий форму добавления новой сущности и
поведения на разных этапах жизни формы, её обработку, валидацию и т.д. Для
примера в приложение №5 представлен листинг объекта, отвечающий за
обработку форм добавления и редактирование сущностей “Контактное лицо”. В
нем описано дополнительное поведение, в добавление к основному, о том, что
будет происходить с формой после успешного “сохранения” данных,
отправленных формой и само сохранение сущности. В представленном примере
после успешной отправки данных, добавляются системные сообщения для
пользователя об успешном сохранении уже существующего материала и
изменений внесенных при помощи формы, либо о создании нового материала.
После чего указывает системе что необходимо перенаправить пользователя на
страницу с материалом.
■ edit - объект, описывающий форму редактирования уже существующей
сущности и поведения на разных этапах жизни форму, её обработку, валидацию
и т.д. Для сущностей описанных в модуле не используется особенная логика для
форм, кроме той, что описана в add пункте, так как для них используются
аналогичные объекты.
■ delete - объект, описывающий форму удаления материала. Для модулей
написанных для ИС используется стандартный объект для данного поведения
ContentEntityDeleteForm.
○ route_provider - массив с содержащий список классов, где ключом
является группирующая строка, которая будет использоваться для регистрации
роутов для данной сущности.
■ html - объект, описывающий роуты для административного интерфейса
сущности. В качестве значения для всех кастомных сущностей указан штатный
AdminHtmlRouteProvider, который регистрирует роуты для страниц добавления,
редактирования и удаления сущностей.
75
● base_table - название таблицы в базе данных, которая будет
использоваться как базовое название для всех производных таблиц. В самой
таблице будут храниться только базовые данные в виде идентификатора
сущности, идентификатор ревизии, если применимо, язык сущности и её UUID.
Это основная таблица входа и сбора информации о сущности определенного
типа. Их структура описана в разделе 2.3.2 и для сущности “Контактное” лицо, в
рисунке 19 продемонстрирована ER-модель данной таблицы и связи с
остальными.
● data_table - название таблицы для хранения информации из базовых
полей сущности (её свойств). Структура данных таблицы описана в разделе 2.3.2
и продемонстрирована на ER-моделях.
● revision_table - название таблицы для хранения информации о ревизиях
сущности. Так как сущности описанные в модулях имеют ревизионность это
значение необходимо. Название таблицы используется для создания
производных таблицы для хранения ревизий других значений сущности.
Структура данных таблиц описана в разделе 2.3.2.
● revision_data_table - аналогично как и data_table, с тем отличием, что
данные хранимые в этой табилце, принадлежат не актуальной версии сущности,
а её предыдущим ревизиям.
● show_revision_ui - булевое значение определяющее, будут ли добавлены
в интерфейс управления сущностями (формы) поля для управления
ревизионностью. По умолчанию данное значение отключено, в таком случае
управлять ревизиями необходимо программно. У наших модулей данное
значение включено, чтобы управление ревизиями происходило через UI при
необходимости.
Рис. №24 Интерфейс для управления ревизиями.
76
● translatable - булевое значение, является ли сущность переводимой и
должна иметь поддержку многоязычности. Для всех сущностей данная опция
включена, чтобы, при необходимости найма иностранных сотрудников, была
возможность данные перевести на другие языки.
● admin_permission - название права доступа, которое необходимо для
доступа к настройкам сущности (ее общих настроек, а не конкретных ее единиц).
● entity_keys - массив с соответствиями ключей сущности с ее
свойствами. По умолчанию все сущности имеют определенные ключи, но
авторы собственных сущностей имеют возможность создавать свои собственные
базовые поля сущности и не следовать стандартным значениям. В данном
массиве нужно указать соответствия, какой собственный ключ ответственен за
те же данные что и внутренний для API. Данный ключи будут использовать
различными конструкторами и прочим кодом ядра и сторонних модулей. Как
правило данный массив содержит:
○ id - связь с тем, какой идентификатор сущности;
○ revision - связь с тем, какой идентификатор ревизии сущности;
○ langcode - для мультиязычных сущностей хранит язык, которому
принадлежит сущность;
○ label - метка сущности;
○ uuid - UUID.
● revision_metadata_keys - массив, содержащий соответствия ключей
для ревизионности с теми, что используются в сущности. У всех сущностей
заданы следующие соответствия:
○ revision_created - дата создания ревизии;
○ revision_log_message - сообщение, запись с комментарием о
создаваемой ревизии.
● links - массив содержащий различные значения-шаблоны для URL,
генерируемых сущностью или сторонними решениями. Значения в данном
массиве поддерживают динамическую подстановку по названию сущности.
Например, для сущности “Контактное лицо”, от модуля details_contact, можно
использовать “{details_contact}” для динамической подстановки определенной
единицы сущности. По умолчанию ожидаются следующие значения:
77
○ add-form - путь до формы добавления новой сущности.
○ canonical - путь определенной единицы сущности с её значениями,
иными словами, путь страницы определенной сущности.
○ edit-form - путь до формы редактирования определенной единицы
сущности.
○ delete-form - путь до формы удаления определенной единицы
сущности.
○ collection - путь до страницы, содержащей список всех сущностей
добавленных на проекте. Этот путь вызывает хендлер list_builder, описанный
ранее.
● field_ui_base_route - название роута, который ведет на основную
страницу с настройками сущности для администратора.
Данные аннотации могут содержать дополнительные данные, но
используются только описанные.
После того как аннотация объявлена, можно заниматься описанием
структурной части сущности при помощи методов, свойств и прилегающего API
системы.
Как правило, для сущностей структурное описание сводится описанию
базовых полей (свойств) сущности и методов для получения их значений и
установки новых. Также, данные объекты могут описывать все процессы жизни
сущности, влезаю в абсолютно каждый этап жизни и переопределяя его на
собственный или дорабатывая стандартный. Как правило, для большинства
сущностей хватает базового функционала от наследуемых абстрактных объектов,
но все же, корректировки вносятся. Так, например, для описываемых в
дипломной работе модулей, доработан метод preCreate(), который вызывается в
момент инициализации объекта сущности для создания новой сущности.
Благодаря этому методу, мы можем указать значения по умолчанию. Данный
пример продемонстрирован в приложении №6, где устанавливается значение для
свойства uid (идентификатор пользователя, являющегося автором сущности) по
умолчанию, равным uid текущего пользователя, из под которого загружена
страница. Так, пользователю не нужно указывать своё авторство явно, оно будет
задано автоматически.
78
Для сущности “Контактное лицо”, также переопределен стандартный
метод label(), который возвращает метку (название) конкретной сущности. Как
правило, у большинства сущностей есть специальное поле для заголовка, но в
случае с “Контактным лицом” у него не может быть заголовка в обычном
понимании. “Заголовком” контактного лица является его ФИО, которое
разделено на три совершенно самостоятельных значения. Благодаря
переопределению метода, отвечающий за получение заголовка, вместо
стандартного возвращения значения поля, содержащего заголовок, пытается
сформироваться заголовок на основе фамилии, имени и отчества. При этом, оно
отработает успешно при любом количестве данных. Пример реализации
приведен в приложении №7.
Очень большую важность для сущностей выполняет метод
baseFieldDefinitions(), отвечающий за описание базовых полей сущности, или её
свойств. Это аналогичные обычным полям поля, с единственным отличием, что
они применяются ко всем сущностям данного типа и их невозможно удалить из
интерфейса не изменив их описание в данном методе. Значения данных полей
хранятся в таблице указанной в data_table, таким образом, значения будут
находиться в столбцах данной таблицы. Обычные же поля, имеют свои
собственные таблицы под свои значения.
Для сущностей написанных модулей добавлены специальные базовые
поля для каждой сущности, описанные в таблицах ниже. В таблицах типы
представлены во внутренних типах полей Drupal, а не тех типах, которые
хранятся в БД.
Таблица №16
Базовые поля сущности details_company.
Название поля
Метка поля
Тип поля
Доп. информация
Заголовок
title
string
Заголовок или название компании.
Является обязательным полем.
Дата создания
created
created
Поле хранящее timestamp даты
создания материала. Является
обязательным полем.
Дата
изменения
changed
changed
Поле хранящее timestamp даты
последнего изменения материала.