Скриптинг в формах
------------------

Основные требования и некоторые детали задачи описаны в
соответствующей постановке: `«Скриптинг в формах» <http://tdd.lan.arta.kz/docs/additional/statements/3/html/forms63.html>`_

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

Примеры использования скриптинга см. `здесь <http://tdd.lan.arta.kz/docs/synergy/tags/wilkes/sdk-doc/html/extfp-usecases/extfp-usecases.html>`_

**Используемые технологии и библиотеки:**

*   `jQuery`
*   `Underscore` - утилиты
*   `Backbone` - UI компоненты
*   `Marionette` - UI компоненты
*   `jQuery ui` - UI компоненты
*   `math.js` - поддержка математики больших чисел
*   `base64.js` - добавляет методы btoa, atob для браузеров,
    в которых их нет (в частности IE 9, 10)
*   `XregExp.js` - поддержка более сложных регулярных
    выражений

Схемы работы проигрывателя
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. figure:: _static/img/schema_1.png

    Общая схема работы проигрывателя

.. figure:: _static/img/schema_2.png

    Процесс изменения модели

.. figure:: _static/img/schema_3.png

    Процесс изменения значения компонента

.. figure:: _static/img/schema_4.png

    Взаимодействие со средой

Общедоступные объекты
~~~~~~~~~~~~~~~~~~~~~

*   ``AS`` - общее пространство имен
*   ``AS.FORMS`` - формы
*   ``AS.COMPONENTS`` - компоненты, которые могут быть использованы отдельно от проигрывателя форм
*   ``AS.SERVICES`` - сервисы
*   ``AS.LOGGER`` - логгер
*   ``AS.OPTIONS`` - настройки
*   ``AS.DICTIONARIES`` - кэш справочников

Типы событий
~~~~~~~~~~~~

*   ``formShow : 'formShow'`` - отображение формы
    (построение новой формы)

*   ``formDestroy : 'formDestroy'`` - метод `destroy`_ модели проигрывателя

*   ``dataLoad: 'dataLoad'`` - подгрузка данных

*   ``valueChange: 'valueChange'`` - изменение значения
    модели

*   ``markInvalid : 'markInvalid'`` - необходимость отображению подсветить невалидное значение

*   ``tableRowAdd: 'tableRowAdd'`` - добавление ряда в таблице

*   ``tableRowDelete: 'tableRowDelete'`` - удаление ряда в таблице

*   ``dictionaryLoad : 'dictionaryLoad'`` - подгрузка справочника

*   ``tagEdit : 'tagEdit'`` - редактирование тега

*   ``tagDelete : 'tagDelete'`` - удаление тега

*   ``loadComponentAdditionalInfo : 'loadComponentAdditionalInfo'`` -
    подгрузка дополнительной информации компонента (сейчас
    используется для пользовательского компонента)

Особенности реализации
~~~~~~~~~~~~~~~~~~~~~~

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

*   ``model`` - модель текущего компонента;
*   ``view`` - отображение текущего компонента;
*   ``editable`` - режим (просмотр / редактирование);
*   ``model.playerModel`` - модель проигрывателя;
*   ``view.playerView`` - отображение проигрывателя.

Скрипт (добавленный как к компоненту, так и пользовательскому
компоненту) выполняется каждый раз при смене режима
проигрывателя (просмотр - редактирование). При этом *модель*
компонента остается та же, а *отображение* компонента каждый
раз пересоздается. Поэтому при написании скриптов следует
учесть следующее: если добавляются или переписываются методы
модели, либо происходит подписывание на события другой модели,
то рекомендуется использовать следующее:

.. code-block:: js
  :linenos:

  if (!model.inited) {
      //манипулирование моделями
      model.inited = true;
  }

**"Строгий режим" JavaScript:**

Начиная с версии Synergy 3.14, все пользовательские скрипты
выполняются с добавлением директивы `use strict`. Эта директива
означает, что соответствующий ей код будет выполнятся в так
называемом **"строгом режиме"**, поддерживающем стандарт `JavaScript`
`ECMAScript5 <http://www.ecma-international.org/publications/standards/Ecma-262.htm>`_

.. warning:: Если код скрипта содержит конструкции, не соответствующие стандарту ES5, то они не будут выполняться. Это не является ошибкой Synergy.

Проигрыватель
~~~~~~~~~~~~~

Для того, чтобы создать экземпляр проигрывателя, необходимо вызвать
метод ``AS.FORMS.createPlayer()``.

.. code-block:: js

    var player = AS.FORMS.createPlayer();

Методы проигрывателя
""""""""""""""""""""

.. js:function:: showFormByCode(formCode[,version])

    Отображает форму по ее коду, без создания соответствующего экземпляра asfData

    :param string formCode: Код формы.
    :param number version: Версия формы.

.. js:function:: showFormData(formUUID[, version[, dataUUID[, dataVersion]]])

    Отображает форму

    :param string formUUID: Идентификатор формы.
    :param number version: Номер версии формы.
    :param string dataUUID: Идентификатор данных формы.
    :param number dataVersion: Номер версии данных формы.

.. js:function:: saveFormData(callback)

    Сохраняет данные формы

    :param callback: Функция, которая будет вызвана после сохранения данных с параметром asfDataUUID.

.. js:function:: dataLoaded(definition[,data])

    Построение формы согласно definition и заполнение asfData значением параметра data.
    Вспомогательный метод, вызывающийся при выполнении методов :js:func:`showFormData` и :js:func:`showFormByCode`.

    :param string definition: Описание формы в формате JSON.
    :param string data: Данные формы в форме JSON.

.. js:function:: destroy()

    Удаляет экземпляр проигрывателя

Модели и отображения
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Базовая модель
"""""""""""""""

--------------------------------------------------------------------------------

**Поля базовой модели**

.. js:data:: asfProperty

    Определение компонента из описания формы

.. js:data:: playerModel

    Модель проигрывателя

--------------------------------------------------------------------------------

**Методы базовой модели**

.. js:function:: fireChangeEvents()

    Вызов событий изменения значения формы

.. js:function:: isEmpty()

    Пустое ли значение

.. js:function:: doSetValue(newValue)

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

    :param string newValue: Значение компонента

.. js:function:: getErrors()

    Получение ошибок заполнения поля согласно настройкам ``asfProperty``

    :returns: возвращает массив ошибок. Если массив пустой, значит ошибки отсутствуют,
              иначе - его элементы имеют поля:

              * ``errorCode`` - код ошибки;
              * ``id`` - идентификатор компонента.

              Возможные коды ошибок:

              * ``emptyValue``
              * ``wrongValue``
              * ``deletedValue``
              * ``valueTooHigh``
              * ``valueTooSmall``

              Для одного и того же компонента может быть как несколько ошибок, так может и не быть ни одной.

.. js:function:: getLocale()

    Получение локали, настроенной в компоненте

    :returns: *(string)* Локаль пользователя

.. js:function:: getHTMLValue()

    :returns: *(string)* HTML-представлениe текстового значения поля со стилями

.. js:function:: getValue()

    :returns: *(string)* значение компонента

.. js:function:: getTextValue()

    :returns: *(string)* текстовое значение компонента

.. js:function:: getAsfData([blockNumber])

    :param number blockNumber: Номер строки динамической таблицы (если это компонент статической таблицы, то передавать эту переменную не нужно)
    :returns: *(asfData)* Данные компонента

.. js:function:: setAsfData(asfData)

    Вставить значение `asfData`

    :param asfData asfData: Данные компонента в формате JSON.

Базовое отображение
"""""""""""""""""""

**Поля базового отображения**

.. js:data:: model

    Модель. Наследует AS.FORMS.Model

.. js:data:: container

    Контейнер, в котором будет отрисовываться отображение

.. js:data:: input

    Поле ввода для некоторых компонентов:
        * текстовое поле
        * числовое поле
        * многострочный текст

.. js:data:: playerView

    Отображение проигрывателя

--------------------------------------------------------------------------------

**Базовые методы отображения**

.. js:function:: unmarkInvalid()

    Убрать пометку неправильно заполненного поля

.. js:function:: markInvalid()

    Пометить поле как неправильно заполненное

.. js:function:: checkValid()

    Проверить корректность текущего значения (если поле заполнено неверно, то вызовется метод markInvalid)

.. js:function:: setEnabled(enabled)

    Сделать доступным или недоступным для редактирования

    :param boolean enabled: true/false

.. js:function:: setVisible(visible)

    Сделать видимым или невидимым

    :param boolean visible: true/false

.. js:function:: updateValueFromModel()

    Обновить отображение согласно значению модели

.. note:: Если скрывается последний компонент в строке, то вся строка принимает минимальную высоту 18 px.

Модели и отображения, которые не имеют специфичных свойств или переопределения методов
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

+-----------------------+------------------------------+------------------------------+
| Компонент             | Модель                       | Отображение                  |
+=======================+==============================+==============================+
| Свойства документа    | AS.FORMS.DocAttributeModel   | AS.FORMS.DocAttributeView    |
+-----------------------+------------------------------+------------------------------+
| Ссылка на документ    | AS.FORMS.DocLinkModel        | *в режиме редактирования*    |
|                       |                              |                              |
|                       |                              | AS.FORMS.DocLinkTextView     |
|                       |                              |                              |
|                       |                              | *в режиме просмотра*         |
|                       |                              |                              |
|                       |                              | AS.FORMS.DocLinkView         |
+-----------------------+------------------------------+------------------------------+
| Изображение           | AS.FORMS.ImageModel          | AS.FORMS.ImageView           |
+-----------------------+------------------------------+------------------------------+
| Неизменяемый текст    | AS.FORMS.LabelModel          | AS.FORMS.LabelView           |
+-----------------------+------------------------------+------------------------------+
| Текстовое поле        | AS.FORMS.TextBoxModel        |                              |
+-----------------------+------------------------------+------------------------------+
| Многострочное поле    | AS.FORMS.SimpleModel         |                              |
|                       |                              |                              |
| Номер                 |                              |                              |
|                       |                              |                              |
| HTD-редактор          |                              |                              |
|                       |                              |                              |
| Ход выполнения        |                              |                              |
|                       |                              |                              |
| Лист резолюций        |                              |                              |
|                       |                              |                              |
| Лист подписей         |                              |                              |
+-----------------------+------------------------------+------------------------------+

Модели и отображения, которые имеют специфичные свойства или методы
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Проигрыватель
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. js:class:: AS.FORMS.PlayerModel

    Модель проигрывателя

    .. js:data:: models

        Массив моделей страниц

    .. js:function:: getModelWithId(cmpId, tableId, tableBlockIndex)

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

        :param string cmpId: идентификатор компонента
        :param string tableId: идентификатор динамической таблицы
        :param number tableBlockIndex: номер строки динамической таблицы

Свойства:

+-----------------------+----------------------+------------------------------+
| Наименование          | Тип                  | Описание                     |
+=======================+======================+==============================+
| models                | Массив               | Массив моделей страниц       |
|                       | AS.FORMS.TableModel  |                              |
+-----------------------+----------------------+------------------------------+
| errorDataLoad         | boolean              | `true` - если описание формы |
|                       |                      | содержит ошибки              |
+-----------------------+----------------------+------------------------------+
| formId                | string               | Идентификатор формы          |
+-----------------------+----------------------+------------------------------+
| asfDataId             | string               | Идентификатор данных         |
+-----------------------+----------------------+------------------------------+
| nodeId                | string               | Идентификатор ноды данных    |
+-----------------------+----------------------+------------------------------+
| hasChanges            | boolean              | Имеются ли изменения         |
+-----------------------+----------------------+------------------------------+
| formName              | string               | Наименование формы           |
+-----------------------+----------------------+------------------------------+
| formats               | string               | Форматы печати               |
+-----------------------+----------------------+------------------------------+
| defaultPrintFormat    | string               | Формат печати по умолчанию   |
+-----------------------+----------------------+------------------------------+
| hasMobile             | boolean              | Имеется ли мобильное         |
|                       |                      | представление                |
+-----------------------+----------------------+------------------------------+
| hasPrintable          | boolean              | Имеется ли печатное          |
|                       |                      | представление                |
+-----------------------+----------------------+------------------------------+
| formCode              | string               | Код формы                    |
+-----------------------+----------------------+------------------------------+

Методы:

+-----------------------+----------------------+------------------------------+
| Наименование          | Аргумент             | Описание                     |
+=======================+======================+==============================+
| buildModelsDefinition | definition           | Построить форму по описанию  |
+-----------------------+----------------------+------------------------------+
| getModelWithId        | cmpId, tableId,      | Получение модели компонента  |
|                       | tableBlockIndex      | с указанным идентификатором  |
|                       |                      | в указанной таблице и        |
|                       |                      | указанном блоке, если        |
|                       |                      | идентификатор таблицы не     |
|                       |                      | указан, то ищется модель     |
|                       |                      | компонента на странице или в |
|                       |                      | статических таблицах         |
+-----------------------+----------------------+------------------------------+

*   `AS.FORMS.PlayerView` - отображение проигрывателя

Свойства:

+-------------------+--------------------------+------------------------------+
| Наименование      | Тип                      | Описание                     |
+===================+==========================+==============================+
| view              | Массив                   | Массив отображений страниц   |
|                   | AS.FORMS.TableStaticView |                              |
+-------------------+--------------------------+------------------------------+
| editable          | boolean                  | `true` - если описание формы |
|                   |                          | содержит ошибки              |
+-------------------+--------------------------+------------------------------+

Методы:

+-----------------------+----------------------+------------------------------+
| Наименование          | Аргумент             | Описание                     |
+=======================+======================+==============================+
| setEditable           | Boolean editable     | Устанавливает режим          |
|                       |                      | отображения чтение/запись    |
+-----------------------+----------------------+------------------------------+
| getViewWithId         | cmpId, tableId,      | Получение отображения        |
|                       | tableBlockIndex      | компонента с указанным       |
|                       |                      | идентификатором в указанной  |
|                       |                      | таблице и указанном блоке,   |
|                       |                      | если идентификатор таблицы   |
|                       |                      | не указан, то ищется модель  |
|                       |                      | компонента на странице или в |
|                       |                      | статических таблицах         |
+-----------------------+----------------------+------------------------------+
| appendTo              | HTML element         | Отображает проигрыватель в   |
|                       |                      | заданном компоненте          |
+-----------------------+----------------------+------------------------------+
| destroy               |                      |                              |
+-----------------------+----------------------+------------------------------+
