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

Основные требования и некоторые детали задачи описаны в
соответствующей постановке: `«Скриптинг в формах» <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

        ``[AS.FORMS.TableModel]``: Массив моделей страниц

    .. js:data:: errorDataLoad

        ``boolean``: true - если описание формы содержит ошибки

    .. js:data:: formId

        ``string``: Идентификатор формы

    .. js:data:: asfDataId

        ``string``: Идентификатор данных по форме

    .. js:data:: nodeId

        ``string``: Идентификатор ноды данных

    .. js:data:: hasChanges

        ``boolean``: Наличие изменений

    .. js:data:: formName

        ``string``: Наименование формы

    .. js:data:: formCode

        ``string``: Код формы

    .. js:data:: formats

        ``string``: Форматы печати

    .. js:data:: defaultPrintFormat

        ``string``: Формат печати по-умолчанию

    .. js:data:: hasMobile

        ``boolean``: Наличие мобильного представления

    .. js:data:: hasPrintable

        ``boolean``: Наличие печатного представления

    .. js:function:: buildModelsDefinition()

        Построить форму по описанию

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

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

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


.. js:class:: AS.FORMS.PlayerView

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

    .. js:data:: view

        ``[AS.FORMS.TableStaticView]``: Массив отображений страниц

    .. js:data:: editable

        ``boolean``: Находится в режиме редактирования

    .. js:function:: setEditable(editable)

        Устанавливает режим отображения просмотр/редактирование

        :param boolean editable: Режим отображения - редактирование

    .. js:funtion:: getViewWithId(cmpId, tableId, tableBlockIndex)

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

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

    .. js:function:: appendTo(element)

        Отображает проигрыватель в заданном компоненте

        :param HTML element: Элемент страницы в котором отобразится проигрыватель

    .. js:function:: destroy()

        Удаляет элемент из DOM

«Страница» и «Таблица»
^^^^^^^^^^^^^^^^^^^^^^

.. js:class:: AS.FORMS.TableModel

    Модель компонентов «Страница» и «Таблица»

    .. js:function:: createRow()

        Добавляет блок таблицы

    .. js:function:: removeRow(blockNumber)

        Удаляет блок таблицы

        :param number blockNumber: номер блока

    .. js:function:: getTextValue()

        Возвращает форматированное значение свертки

        :returns: значение свертки

    .. js:function:: isHaveHeader()

        Наличие заголовка

    .. js:function:: isPage()

        Является страницей

    .. js:function:: isStatic()

        Является статической таблицей

    .. js:function:: isParagraph()

        Свертка включена

.. js:class:: AS.FORMS.TableStaticView

    Отображение статической таблицы

    .. js:function:: getRowsCount()

        Возвращает количество рядов таблицы

    .. js:function:: setColumnVisible(columnNumber, visible)

        Делает столбец таблицы видимым / невидимым

        :param number columnNumber: номер столбца
        :param boolean visible: видимый

    .. js:function:: getInvisibleColumns()

        Возвращает список невидимых столбцов

    .. js:function:: getViewWithId(cmpId[, tableId[, tableBlockIndex]])

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

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

.. js:class:: AS.FORMS.TableDynamicView

    Отображение динамической таблицы

    .. js:function:: setEnabled(enabled)

        Разрешить пользователю добавлять и удалять блоки,
        при этом программная возможность остается

        :param boolean enabled: разрешить добавлять и удалять блоки

    .. js:function:: setColumnVisible(column, visible)

        Сделать столбец таблицы видимым

        :param number column: номер столбца таблицы
        :param boolean visible: является видимым

    .. js:function:: getViewWithId(cmpId[, tableId[, tableBlockIndex]])

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

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

    .. js:function:: mergeCell(row, column, rows, cols)

        Объединить ячейки в блоке

        :param number row: номер ряда таблицы
        :param number column: номер столбца таблицы
        :param number rows: количество рядов для объединения
        :param number cols: количество столбцов для объединения

    .. js:function:: splitCell(row, column)

        Разъединить ячейки

        :param number row: номер ряда таблицы
        :param number column: номер столбца таблицы

.. js:class:: AS.FORMS.TableParagraphView

    Отображение динамической таблицы в свертке
