.. _file_component:

File
=====

.. contents::
   :depth: 4
   
Компонент для загрузки файлов. Позволяет загружать файлы в контент. Для дочерних ассоциаций поддерживается задание ``type/kind``.

 .. image:: _static/file/file_8.png
       :width: 600
       :align: center

При добавлении нового компонента **Файл** на форме  достаточно указать правильный **Имя свойства/Property Name** (или оставить по умолчанию ``_content``, если подразумевается редактирование основного контента у документа). Все остальные настройки работают "из коробки".

Выбор способа загрузки файлов осуществляется во вкладке :guilabel:`Файл` - поле **Хранилище/Storage** с значениями **URL** или **Base64**.

 .. image:: _static/file/file_9.png
       :width: 600
       :align: center

Настройка отображения названия файла
-------------------------------------

На вкладке :guilabel:`Файл` добавлена возможность настраивать отображение названий файлов в списке -  настройка **Отображаемое имя значения**. Поле принимает javascript-выражение, в котором необходимо присвоить переменной ``disp`` строку, либо Promise.

 .. image:: _static/file/file_4.png
       :width: 400
       :align: center

Помимо стандартных переменных formio, доступных при написании javascript-выражений (data, instance, _ и т.д.) добавлены дополнительные: 

* **originalFileName** - содержит название файла по-умолчанию

* **file** - объект, содержащий различную информацию о файле

* **record** - Promise, полученный путём вызова ``Records.get(file.data.recordRef)``. Если файл не связан ни с каким recordRef, значение record будет равно null.

Примеры использования  настройки **Value display name**:

.. code-block::

	// Пример 1. Статическое название
	disp = 'staticName.txt';

.. code-block::

    	// Пример 2. Название, вычисленное асинхронно
	disp = new Promise(resolve => {
	  // какие-то асинхронные действия
	  // ...
	  resolve('Асинхронное название файла')
	});

.. code-block::

    	// Пример 3. Использование record
	disp = record ? record.load('.disp').then(result => `${result}.pdf`) : originalFileName;

Настройка отображения отдельных элементов компонента
------------------------------------------------------

На вкладку :guilabel:`Отображение` добавлена дополнительная настройка **Элементы отображения**, которая позволяет задавать условия отображения отдельных элементов (например, кнопка удаления файла, upload-зона с кнопкой для добавления нового файла).

Поле принимает javascript-выражение, в котором необходимо присвоить переменной `value` объект с необязательными свойствами **upload, delete**. Если какое-то из свойств не указано, то компонент сам будет решать, отображать элемент или скрывать, в зависимости от ситуации.

.. code-block::

    value = {
        upload: false,
        delete: false
    } 

.. image:: _static/file/file_5.png
       :width: 500
       :align: center

Бэкенд
-------

Для корректной работы контрола в режиме редактирования у значения "контент" должен быть реализован метод ``getAs`` с аргументом ``content-data``, который вернет структуру следующего содержания: 

.. code-block::

    [
        {
            “url“: “ссылка_которая откроется при клике на файл.“
            “name“: “Имя файла“
            “size“: размер_файла_в_байтах
        }
    ]

Синхронизация с виджетом документов
------------------------------------

.. _file_synchro_docs:

Для синхронизации с виджетом документов на форме контрола ``file`` в **Имени свойства** необходимо указать ``docs:documents``:

.. image:: _static/file/file_6.png
       :width: 600
       :align: center

На вкладке **Файл** указать тип(ы), с которыми следует загружать новые файлы (если файл загрузить без типа, то в виджете он не появится):

.. image:: _static/file/file_7.png
       :width: 400
       :align: center