Клиентская схема

Клиентская схема модели представления — это схема визуального модуля, с помощью которой реализуется front-end часть приложения. Клиентская схема модели представления является конфигурационным объектом для генерации представления и модели представления генераторами Creatio ViewGenerator и ViewModelGenerator. Типы модулей и их особенности описаны в статье Виды клиентских модулей.

Разработка клиентской схемы 

Способы разработки клиентских схем модели представления:

• Раздел Конфигурация (Configuration). Разработка с помощью раздела Конфигурация описана в статье Схема модели представления.
• Мастер разделов. Разработка раздела с помощью мастера разделов описана в статье Добавить новый раздел.
• Мастер деталей. Разработка деталей с помощью мастера деталей описана в статье Создать новую деталь.

Структурные элементы клиентской схемы:

• Автоматически сгенерированный код — содержит описание схемы, ее зависимостей, локализованных ресурсов и сообщений.
• Стили, используемые для визуализации (присутствуют не во всех типах клиентских схем).
• Исходный код схемы — синтаксически правильный код на языке JavaScript, который является определением модуля.

Маркерные комментарии необходимо использовать в исходном коде схемы для свойств diff, modules, details и businessRules.

Назначение маркерных комментариев — однозначное определение свойств клиентской схемы. При открытии мастера выполняется валидация наличия маркерных комментариев, которые представлены в таблице ниже.

details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/,
modules: /**SCHEMA_MODULES*/{}/**SCHEMA_MODULES*/,
diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/,
businessRules: /**SCHEMA_BUSINESS_RULES*/{}/**SCHEMA_BUSINESS_RULES*/

modules: /**SCHEMA_MODULES*/{}/**SCHEMA_MODULES*/,
diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/

Свойства клиентской схемы 

Исходный код клиентских схем имеет общую структуру, которая представлена ниже.

define("ExampleSchema", [], function() {
    return {
        entitySchemaName: "ExampleEntity",
        mixins: {},
        attributes: {},
        messages: {},
        methods: {},
        rules: {},
        businessRules: /**SCHEMA_BUSINESS_RULES*/{}/**SCHEMA_BUSINESS_RULES*/,
        modules: /**SCHEMA_MODULES*/{}/**SCHEMA_MODULES*/,
        diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/
    };
});

После загрузки модуля выполняется вызов анонимной функции-фабрики, которая возвращает конфигурационный объект схемы. Свойства конфигурационного объекта схемы:

• entitySchemaName — имя схемы объекта, который используется текущей клиентской схемой.
• mixins — конфигурационный объект, который содержит объявление миксинов.
• attributes — конфигурационный объект, который содержит атрибуты схемы.
• messages — конфигурационный объект, который содержит сообщения схемы.
• methods — конфигурационный объект, который содержит методы схемы.
• rules — конфигурационный объект, который содержит бизнес-правила схемы.
• businessRules — конфигурационный объект, который содержит бизнес-правила схемы, созданные или измененные мастером разделов или мастером деталей. Маркерные комментарии /**SCHEMA_BUSINESS_RULES*/ обязательны к использованию для работы мастеров.
• modules — конфигурационный объект, который содержит модули схемы. Маркерные комментарии /**SCHEMA_MODULES*/ обязательны к использованию для работы мастеров.

  На заметку. Для загрузки детали на страницу используется свойство details. Поскольку деталь является модулем, то правильным будет использование свойства modules.

• diff — массив конфигурационных объектов, который содержит описание представления схемы. Маркерные комментарии /**SCHEMA_DIFF*/ обязательны к использованию для работы мастеров.
• properties — конфигурационный объект, который содержит свойства схемы модели представления.
• $-свойства — автоматически сгенерированные свойства для атрибутов схемы модели представления.

Имя схемы (entitySchemaName) 

Для реализации имени схемы объекта необходимо использовать обязательное свойство entitySchemaName. Достаточно указать его в одной из схем иерархии наследования.

define("ClientSchemaName", [], function () {
    return {
        /* Схема объекта (модель). */
        entitySchemaName: "EntityName",
        /* ... */
    };
});

Миксины (mixins) 

Миксин — это класс-примесь, предназначенный для расширения функциональности других классов. В JavaScript нет множественного наследования, а наличие миксинов позволяет расширить функциональность схемы без дублирования логики, часто используемой в методах схемы. В разных клиентских схемах приложения Creatio может использоваться один и тот же набор действий. Чтобы не дублировать код в каждой схеме, необходимо создать миксин. Особенность миксинов в сравнении с другими модулями, подключаемыми в список зависимостей, — способ вызова методов из схемы модуля (к методам миксина можно обращаться напрямую, как к методам схемы). Для реализации миксинов необходимо использовать свойство mixins.

Алгоритм работы с миксинами:

1. Создайте миксин.
2. Присвойте миксину имя.
3. Подключите соответствующее пространство имен.
4. Реализуйте функциональность миксина.
5. Используйте миксин в клиентской схеме.

Создать миксин 

Создание миксина аналогично созданию схемы объекта.

Присвоить миксину имя 

При именовании миксинов в названии схемы необходимо использовать суффикс "-able" (например, Serializable — миксин, который добавляет компонентам способность сериализироваться). Если нет возможности сформулировать имя миксина в описанной выше форме, необходимо в название схемы добавить окончание "Mixin".

Подключить пространство имен 

Для миксина необходимо подключить соответствующее пространство имен (для конфигурации — Terrasoft.configuration.mixins, для ядра — Terrasoft.core.mixins).

Реализовать функциональность миксина 

Миксины не должны зависеть от внутренней реализации схемы, к которой они будут применены. Это должен быть самодостаточный механизм, который принимает набор параметров, выполняет с ними действие и, при необходимости, возвращает результат. Миксины оформляются в виде модулей, которые необходимо подключить в список зависимостей схемы при ее объявлении функцией define().

Структура миксина представлена ниже.

define("ИмяМиксина", [], function() { 
    Ext.define("Terrasoft.configuration.mixins.ИмяМиксина", {
        alternateClassName: "Terrasoft.ИмяМиксина",
        /* Функциональность миксина. */      
    });
    return Ext.create(Terrasoft.ИмяМиксина);
})

Использовать миксин 

Миксин реализует функциональность, необходимую в клиентской схеме. Чтобы получить набор действий миксина, необходимо указать его в свойстве mixins клиентской схемы.

/* ИмяМиксина — модуль, в котором реализован класс миксина. */
define("ИмяКлиентскойСхемы", ["ИмяМодуля"], function () {
    return {
        /* ИмяСхемы — название схемы сущности. */
        entitySchemaName: "ИмяСхемы",
        mixins: {
            /* Подключение миксина. */
            ИмяМиксина: "Terrasoft.ПространствоИмен.ИмяМиксина"
        },
        attributes: {},
        messages: {},
        methods: {},
        rules: {},
        modules: /**SCHEMA_MODULES*/{}/**SCHEMA_MODULES*/,
        diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/
    };
});

После подключения можно пользоваться методами, атрибутами и полями миксина в клиентской схеме так, как будто они являются частью данной клиентской схемы. При этом вызовы методов получаются более краткими, чем при использовании отдельной схемы. Например, getDefaultImageResource — функция миксина. Для вызова функции миксина getDefaultImageResource в пользовательской схеме, к которой подключен миксин, необходимо записать this.getDefaultImageResource();.

Атрибуты (attributes) 

Для реализации атрибутов необходимо использовать свойство attributes.

Сообщения (messages) 

Назначение сообщений — организация обмена данными между модулями. Для реализации сообщений необходимо использовать свойство messages. Используя перечисление Terrasoft.MessageMode, можно задать режим сообщения.

Кроме режимов, также можно задать направление сообщения.

Публикация сообщения 

В схеме, в которой необходимо осуществить публикацию сообщения, должно быть объявлено сообщение с направлением "Публикация".

messages: {
    /* Имя сообщения. */
    "GetColumnsValues": {
        /* Режим сообщения — адресное. */
        mode: this.Terrasoft.MessageMode.PTP,
        /* Направление сообщения — публикация. */
        direction: this.Terrasoft.MessageDirectionType.PUBLISH
    }
}

Публикация осуществляется вызовом метода publish у экземпляра класса sandbox.

/* Метод получения результата публикации сообщения GetColumnsValues. */
getColumnsValues: function(argument) {
/* Публикация сообщения.
GetColumnsValues — имя сообщения.
argument — аргумент, передаваемый в функцию-обработчик подписчика. Объект, содержащий параметры сообщения.
key — массив тегов для фильтрации сообщений. */
return this.sandbox.publish("GetColumnsValues", argument, ["key"]);
}

Подписка на сообщение 

В схеме-подписчике должно быть объявлено сообщение с направлением "Подписка".

messages: {
    /* Имя сообщения. */
    "GetColumnsValues": {
        /* Режим сообщения — адресное. */
        mode: this.Terrasoft.MessageMode.PTP,
        /* Направление сообщения — подписка. */
        direction: this.Terrasoft.MessageDirectionType.SUBSCRIBE
    }
}

Подписка осуществляется вызовом метода subscribe у экземпляра класса sandbox.

/* GetColumnsValues — имя сообщения.
messageHandler — функция-обработчик сообщения.
context — контекст выполнения функции-обработчика.
key — массив тегов для фильтрации сообщений. */
this.sandbox.subscribe("GetColumnsValues", messageHandler, context, ["key"]);

При адресном режиме метод messageHandler должен возвращать объект, который обрабатывается как результат публикации сообщения. При широковещательном режиме метод messageHandler ничего не возвращает.

methods: {
    messageHandler: function(args) { 
        /* Возвращение объекта, который обрабатывается как результат публикации сообщения. */
        return { }; 
    }
}

methods: {
    messageHandler: function(args) { 
    }
} 

Методы (methods) 

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

Назначение свойства methods:

1. Создавать новые методы.
2. Расширять базовые методы родительских схем.

Бизнес-правила (rules и businessRules) 

Бизнес-правила — это механизмы приложения, которые пользовательскими средствами позволяют настраивать поведение полей на странице или детали. Для реализации бизнес-правил необходимо использовать свойства rules и businessRules. Свойство businessRules используется для бизнес-правил, которые созданы или изменены мастером разделов или мастером деталей.

Назначение бизнес-правил:

• Cкрытие или отображение полей.
• Блокировка или доступность редактирования полей.
• Обязательность или необязательность заполнения полей.
• Фильтрация справочных полей в зависимости от значений в других полях.

Функциональность бизнес-правил реализована в клиентском модуле BusinessRuleModule. Для использования функциональности бизнес-правил необходимо в список зависимостей схемы добавить модуль BusinessRuleModule.

define("CustomPageModule", ["BusinessRuleModule"],
    function(BusinessRuleModule) {
        return {
            /* Реализация клиентского модуля. */
        };
    });

Типы бизнес-правил определены в перечислении RuleType модуля BusinessRuleModule.

Особенности бизнес-правил 

Особенности объявления бизнес-правил:

• Все бизнес-правила описываются в свойстве rules схемы.
• Бизнес-правила применяются к колонкам модели представления, а не к элементам управления.
• Бизнес-правило имеет название.
• Параметры бизнес-правила задаются в конфигурационном объекте.

Особенности бизнес-правил, определенных в свойстве businessRules:

• Генерируются мастерами разделов или деталей.
• При создании нового бизнес-правила мастер генерирует его имя и добавляет его в клиентскую схему модели представления страницы записи.
• При описании сгенерированного бизнес-правила не используются перечисления модуля бизнес-правил BusinessRuleModule.
• Маркерные комментарии /**SCHEMA_BUSINESS_RULES*/ обязательны к использованию для работы мастеров.
• При выполнении имеют более высокий приоритет.
• При отключении бизнес-правила свойству enabled конфигурационного объекта присваивается значение false.
• При удалении бизнес-правила конфигурационный объект остается в клиентской схеме модели представления страницы записи, но свойству removed присваивается значение true.

Редактирование существующего бизнес-правила 

После редактирования мастером созданного вручную бизнес-правила, остается неизменным конфигурационный объект бизнес-правила в свойстве rules модели представления страницы записи. При этом будет создана новая версия конфигурационного объекта бизнес-правила с тем же именем в свойстве businessRules.

При обработке бизнес-правила во время выполнения приложения приоритет отдается бизнес-правилу, определенному в свойстве businessRules. Поэтому последующие изменения этого бизнес-правила в свойстве rules никак не повлияют на систему.

Модули (modules) 

Для реализации модулей необходимо использовать свойство modules, конфигурационный объект которого отвечает за объявление и конфигурирование модулей и деталей, загружаемых на страницу. Маркерные комментарии /**SCHEMA_MODULES*/ обязательны к использованию для работы мастеров.

modules: /**SCHEMA_MODULES*/{
    /* Загрузка модуля.
    Заголовок модуля. Должен быть таким же, как свойство name в массиве diff. */
    "TestModule": { 
        /* Опционально. Идентификатор загружаемого модуля. Если не указан, будет сгенерирован системой. */
        "moduleId": "myModuleId",.
        /* Если параметр не указан, будет использован BaseSchemaModuleV2 для загрузки. */
        "moduleName": "MyTestModule",      
        /* Конфигурационный объект. При загрузке модуля передается как instanceConfig. В нем хранится набор начальных значений параметров для модуля. */
        "config": { 
            "isSchemaConfigInitialized": true,
            "schemaName": "MyTestSchema",
            "useHistoryState": false,
            /* Дополнительные параметры модуля. */
            "parameters": { 
                /* Параметры, передаваемые в схему при ее инициализации. */
                "viewModelConfig": { 
                    masterColumnName: "PrimaryContact"
                }
            }
        }
    },
    
    /* Загрузка детали.
    Имя детали. */
    "Project": {
            /* Название схемы детали. */
            "schemaName": "ProjectDetailV2",
            "filter": {
            /* Колонка схемы объекта раздела. */
            "masterColumn": "Id",
            /* Колонка схемы объекта детали. */
            "detailColumn": "Opportunity"
        }
    }
}/**SCHEMA_MODULES*/

Массив модификаций (diff) 

Для реализации массива модификаций необходимо использовать свойство diff, которое содержит массив конфигурационных объектов. Назначение массива модификаций — построение представления модуля в интерфейсе системы. Каждый элемент массива представляет собой метаданные, на основании которых генерируются различные элементы управления интерфейса. Маркерные комментарии /**SCHEMA_DIFF*/ обязательны к использованию для работы мастеров.

Механизм псевдонимов alias 

При разработке новых версий периодически возникает необходимость переместить элементы страницы в новые зоны. В ситуациях, когда пользователи проводили кастомизацию страницы записи, подобные изменения могут привести к непредсказуемым последствиям. Механизм псевдонимов alias обеспечивает частичную обратную совместимость при изменении пользовательского интерфейса в новых версиях продукта путем взаимодействия с построителем diff — классом json-applier, осуществляющим слияние параметров базовой схемы и клиентских расширяющих схем.

Свойство alias содержит информацию о предыдущем названии элемента. Эта информация учитывается при построении массива модификаций diff, сообщая о необходимости учитывать элементы не только с новым именем, но и с именем, указанным в alias. Фактически, alias представляет собой конфигурационный объект, который связывает новый и старый элементы. При построении массива модификаций diff благодаря конфигурационному объекту alias можно исключить применение некоторых свойств и операций по отношению к элементу, в котором он объявлен. Объект alias может быть добавлен в любой элемент массива модификаций diff.

Связь между представлением и моделью 

Назначение свойства bindTo — указание связи между атрибутом модели представления и свойством объекта представления.

Объявляется в свойстве values конфигурационных объектов массива diff.

Ниже представлен пример использования свойства bindTo.

diff: [
    {
        "operation": "insert",
        "parentName": "CombinedModeActionButtonsCardLeftContainer",
        "propertyName": "items",
        "name": "MainContactButton",
        /* Свойства, передаваемые в конструктор компонента. */
        "values": {
            /* Тип добавляемого элемента — кнопка. */
            "itemType": Terrasoft.ViewItemType.BUTTON,
            /* Привязка заголовка кнопки к локализуемой строке схемы. */
            "caption": {bindTo: "Resources.Strings.OpenPrimaryContactButtonCaption"},
            /* Привязка метода-обработчика нажатия кнопки. */
            "click": {bindTo: "onOpenPrimaryContactClick"},
            /* Стиль отображения кнопки. */
            "style": Terrasoft.controls.ButtonEnums.style.GREEN,
            /* Привязка свойства доступности кнопки. */
            "enabled": {bindTo: "ButtonEnabled"}
        }
    }
]

Вкладки — объекты, которые в свойстве propertyName содержат значение tabs.

Для заголовков вкладок реализован альтернативный способ использования свойства bindTo.

...
{
    "operation": "insert",
    "name": "GeneralInfoTab",
    "parentName": "Tabs",
    /* Указывает на то, что данный объект является вкладкой. */
    "propertyName": "tabs",
    "index": 0,
    "values": {
        /* $ заменяет использование bindTo: {...}. */
        "caption": "$Resources.Strings.GeneralInfoTabCaption",
        "items": []
    }
},
...

Правила объявления свойства diff 

• Корректное использование конвертеров.

  Конвертер — это функция, которая выполняется в окружении viewModel и, получая значения свойства viewModel, должна вернуть результат соответствующего типа. Для корректной работы мастеров значение свойства diff должно быть представлено в формате JSON. Поэтому значением конвертера должно быть имя метода модели представления, а не inline-функция.

  methods: {
      someFunction: function(val) {
          /* ... */
      }
  },
  
  diff: /**SCHEMA_DIFF*/[
    {
        /* ... */
        "bindConfig": {
            "converter": "someFunction"
        }
        /* ...*/
    }
  ]/**SCHEMA_DIFF*/
  

  diff: /**SCHEMA_DIFF*/[
      {
          /* ... */
          "bindConfig": {
              "converter": function(val) {
              /* ... */
              }
          }
      }
  ]/**SCHEMA_DIFF*/
  

  methods: {
      someFunction: function(val) {
          /* ... */
      }
  },
  
  diff: /**SCHEMA_DIFF*/[
    {
        /* ... */
        "values": {
            "generator": "someFunction"
        }
        /* ... */
    }
  ]/**SCHEMA_DIFF*/
  

  diff: /**SCHEMA_DIFF*/[
      {
          /* ... */
          "values": {
              "generator": function(val) {
                  /* ... */
              }
          }
      }
  ]/**SCHEMA_DIFF*/
  

• Родительский элемент.

  Родительский элемент (контейнер) — это DOM-элемент, в который модуль отрисует свое представление. Для корректной работы мастерам необходимо, чтобы родительский контейнер содержал только один дочерний элемент.

  <div id="OpportunityPageV2Container" class="schema-wrap one-el" data-item-marker="OpportunityPageV2Container">
      <div id="CardContentWrapper" class="card-content-container page-with-left-el" data-item-marker="EntityLoaded"></div>
  </div>
  

  <div id="OpportunityPageV2Container" class="schema-wrap one-el" data-item-marker="OpportunityPageV2Container">
      <div id="CardContentWrapper" class="card-content-container page-with-left-el" data-item-marker="EntityLoaded"></div>
      <div id="DuplicateContainer" class="DuplicateContainer"></div>
  </div>
  

  При добавлении, изменении, перемещении элемента (операции insert, merge, move) в свойстве diff необходимо указать свойство parentName — имя родительского элемента.

  {
    "operation": "insert",
    "name": "SomeName",
    "propertyName": "items",
    "parentName": "SomeContainer",
    "values": {}
  }
  

  {
    "operation": "insert",
    "name": "SomeName",
    "propertyName": "items",
    "values": {}
  }
  

  Если отсутствует свойство parentName, то при открытии мастера отобразится ошибка о невозможности настройки страницы мастером.

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

  Если в качестве родительского элемента в свойстве parentName указать имя несуществующего элемента-контейнера, то возникнет ошибка "Схема не может иметь более одного корневого объекта" ("Schema cannot have more than one root object"), поскольку добавляемый элемент будет помещен в корневой контейнер.

• Уникальность имен.

  Каждый элемент в массиве diff должен иметь уникальное имя.

  {
    "operation": "insert",
    "name": "SomeName",
    "values": { }
  },
  {
    "operation": "insert",
    "name": "SomeSecondName",
    "values": { }
  }
  

  {
    "operation": "insert",
    "name": "SomeName",
    "values": { }
  },
  {
    "operation": "insert",
    "name": "SomeName",
    "values": { }
  }
  

• Размещение элементов представления.

  Чтобы иметь возможность настраивать и изменять элементы представления, они должны находиться на сетке разметки. В Creatio каждый ряд сетки разметки имеет 24 ячейки (столбца). Для размещения на сетке используется свойство layout.

  Cвойства элемента сетки:

  • column — индекс левого столбца.
  • row — индекс верхней строки.
  • colSpan — количество занимаемых столбцов.
  • rowSpan — количество занимаемых строк.
  Пример размещения элементов

  {
    "operation": "insert",
    "parentName": "ParentContainerName",
    "propertyName": "items",
    "name": "ItemName",
    "values": {
        /* Размещение элемента. */
       "layout": {
          /* Начать с нулевого столбца. */
          "column": 0,
          /* Разместиться в пятой строке сетки. */
          "row": 5,
          /* Занять 12 столбцов в ширину. */
          "colSpan": 12,
          /* Занять один ряд в высоту. */
          "rowSpan": 1
       },
       "contentType": Terrasoft.ContentType.ENUM
    }
  }
  

• Количество операций.

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

Свойства (properties) 

Для реализации свойств необходимо использовать свойство properties, которое содержит JavaScript-объект.

Пример использования свойства properties в схеме SectionTabsSchema пакета NUI представлен ниже.

define("SectionTabsSchema", [],
    function() {
        return {
            ...
            /* Объявление свойства properties. */
            properties: {
                /* Свойство parameters. Массив. */
                parameters: [],
                /* Свойство modulesContainer. Объект. */
                modulesContainer: {}
            },
            methods: {
                ...
                /* Метод инициализации. Всегда выполняется первым. */
                init: function(callback, scope) {
                    ...
                    /* Вызов метода, в котором используются свойства модели представления. */
                    this.initContainers();
                    ...
                },
                ...
                /* Метод, в котором используются свойства. */
                initContainers: function() {
                    /* Использование свойства modulesContainer. */
                    this.modulesContainer.items = [];
                    ...
                    /* Использование свойства parameters. */
                    this.Terrasoft.each(this.parameters, function(config) {
                        config = this.applyConfigs(config);
                        var moduleConfig = this.getModuleContainerConfig(config);
                        var initConfig = this.getInitConfig();
                        var container = viewGenerator.generatePartial(moduleConfig, initConfig)[0];
                        this.modulesContainer.items.push(container);
                    }, this);
                },
                ...
            },
        ...
        }
    });