api.utils Работа с файлами

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

Файлы, прикрепленные к атрибутам объекта типа "Текст в формате RTF", определяются по значению атрибута "Изображение из RTF-атрибута" (imgFromRTF).
Превью изображений на текущий момент времени определяются по заполненности атрибута "Оригинал" (original) у файла, прикрепленного к атрибуту типа "Текст в формате RTF".

Получение списка файлов

utils.files(obj)

Получение списка файлов, прикрепленных к объекту и атрибутам объекта типа "Файл" (кроме файлов, прикрепленных в атрибуте типа "Текст RTF").

Параметр метода:
- obj — объект, для которого отображается список файлов.
Возвращает список файлов, прикрепленных к объекту и атрибутам объекта типа "Файл", упорядоченных в хронологическом порядке (по времени добавления). При обращении к последнему элементу коллекции возвращается последний прикрепленный файл.

Не возвращает файлы, связанные с RTF-атрибутами объекта, включая превью изображений.

Пример: Получение списка файлов, прикрепленных к самому объекту, а не к его атрибутам типа "Файл" и "Текст в формате RTF":

def contentFiles = utils.files(obj).findAll{!it.relation};
utils.allFiles(obj)

Получение списка всех файлов, прикрепленных к объекту, атрибутам объекта типа "Файл" и атрибутам объекта типа "Текст в формате RTF".

Параметр метода:
- obj — объект или его uuid, для которого отображается список файлов.
Возвращает список всех файлов, прикрепленных к объекту, атрибутам объекта типа "Файл" и атрибутам объекта типа "Текст в формате RTF", упорядоченных в хронологическом порядке (по времени добавления).

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

Не возвращает превью изображений из текста RTF.
utils.filesFromRtf(obj)

utils.filesFromRtf(obj, inPreview)

Получение списка файлов, связанных с RTF атрибутами объекта.

Параметры метода:
- obj — объект или его uuid, для которого отображается список файлов;
- inPreview:
  - true — возвращает файлы с превью изображений, если они имеются, вместо оригиналов;
  - false или параметр не указан — возвращает только файлы с изображениями в оригинальном размере.
Возвращает список всех файлов, связанных с RTF атрибутами объекта.
utils.filesFromRtf(obj, attrCode)

utils.filesFromRtf(obj, attrCode, inPreview)

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

Параметры метода:
- obj — объект или его uuid, для которого отображается список файлов;
- attrCode — код атрибута типа "Текст в формате RTF";
- inPreview:
  - true — возвращает файлы с превью изображений, если они имеются, вместо оригиналов;
  - false или параметр не указан — возвращает только файлы с изображениями в оригинальном размере.
Возвращает список всех файлов, связанных с определенным RTF атрибутом объекта.

Преобразования

utils.convertFilesToBase64(text, failIfFileNotFound)

Преобразует текст, содержащий ссылки на файлы в тегах img, в список файлов в формате base64.

Размер файла ограничивается в конфигурационном файле dbaccess.properties, параметр ru.naumen.file.base64.limit (Файлы).

Параметры метода:
- text — текст картинками. String;
- failIfFileNotFound. Boolean.
  - true — возникает ошибка при отсутствии файла или при отсутствии соединения с файловым хранилищем;
  - false (по умолчанию) — ошибка не возникает. Параметр необязательный.
Возвращает текст с картинками в виде base64.

Текст возвращается как html страница (т.е. обернутым в теги <html> <body> ...</body> </html>).

Прикрепление файла

utils.attachFile(source, fileName, contentType, description, content)

utils.attachFile(source, attribute, fileName, contentType, description, content)

Прикрепление файла к указанному объекту.

Параметры метода:

source — объект, к которому прикрепляется файл;
attribute — код атрибута, к которому будет прикреплен файл;
fileName — название файла с расширением;
contentType — mime-тип файла;
description — описание файла;
content — содержимое файла;

Возвращает объект файла.

Примеры:

1. Прикрепление файлов к объекту в контент "Список файлов":

Copy

/*Параметры*/
def obj = ...                         //объект, к которому прикрепляется файл
def fileName = 'file1.txt'            //имя файла (с расширением)
def contentType = 'text/plain'        //тип содержимого файла (mime-тип)
def description = 'Описание'          //описание файла
def data = 'some string'.getBytes()   //содержимое файла в виде массива байт

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, fileName, contentType, description, data)

2. Прикрепление файлов к атрибуту объекта:

Copy

/*Параметры*/
def obj = ...                         //объект, к которому прикрепляется файл
def attribute = 'files'               //код атрибута, к которому прикрепляется файл
def fileName = 'file1.txt'            //имя файла (с расширением)
def contentType = 'text/plain'        //тип содержимого файла (mime-тип)
def description = 'Описание'          //описание файла
def data = 'some string'.getBytes()   //содержимое файла в виде массива байт

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, attribute, fileName, contentType, description, data)

utils.attachFile(source, object)

utils.attachFile(source, attribute, object)

Прикрепление файла к указанному объекту или атрибуту объекта. Метод используется только в скриптах пользовательских действий по событию при обращении к файлу через параметры пользовательского действия по событию.
- Скрипты на пользовательские события (кнопка-скрипт)
- Настройка параметров пользовательского действия
Параметры метода:
- source — объект, к которому прикрепляем файл;
- attribute — код атрибута, к которому будет прикреплен файл;
- object — объект типа Файл, который нужно прикрепить к объекту
Возвращает объект файла.

Примеры:

1. Прикрепление файлов из параметров пользовательских событий к объекту в контент "Список файлов":
Copy
```
/*Параметры*/
def obj = ...         //объект, к которому прикрепляется файл
def file = ...        //файл, выбранный как значение параметра типа "Файл" пользовательского события

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, file)

/*Пример*/
def obj = ...
params.files?.each { file -> utils.attachFile(obj, file) } // прикрепление к объекту
```
2. Прикрепление файлов к атрибуту объекта из параметров пользовательских событий:
Copy
```
/*Параметры*/
def obj = ...                 //объект, к которому прикрепляется файл
def attribute = 'files'       //код атрибута, к которому прикрепляется файл
def file = ...                //файл, выбранный как значение параметра типа "Файл" пользовательского события

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, attribute, file)

/*Пример*/
def obj = ...
params.files?.each { file ->  utils.attachFile(obj, 'files', file) }
```

Получение содержимого файла

utils.readFileContent(file)

Получение содержимого файла (содержимое файла считывается как массив байтов).

Параметр метода:
- file — файл.
Файл не должен быть слишком большим, поскольку его содержимое загружается в оперативную память, что может негативно сказаться на производительности системы.

Рекомендации по использованию методов для прикрепления и скачивания файла в одном скрипте:
- Корректное использование.
  
  Для прикрепления файла следует использовать следующие методы:
  - utils.edit — для прикрепления файла (постоянного, временного) к атрибуту;
  - utils.attachFile(source, object) или utils.attachFile(source, attribute, object) — для прикрепления файла к указанному объекту или атрибуту объекта только в скриптах пользовательских действий по событию при обращении к файлу через параметры пользовательского действия по событию.
  В других случаях (отличных от вышеописанных) рекомендуется сначала получение содержимого файла методом utils.readFileContent, затем прикрепление этого файла методом utils.attachFile.
- Не рекомендуется: сначала прикрепление файла методом utils.attachFile, затем получение содержимого этого файла методом utils.readFileContent.
  
  После прикрепления файла его содержимое уже доступно в скрипте и повторное получение содержимого этого файла не требуется.
Особенности:
- В скрипте условия на вход в начальный статус "Зарегистрирован" (registered) содержимое файла получить нельзя, если file — это файл принадлежащий объекту, который находится в процессе создания.
Пример:
Copy
```
def file = fileList[0] // объект типа "Файл"
try
  {
  byte[] data = utils.readFileContent(file)
  }
catch(e)
  {
  logger.error "Ошибка при чтении содержимого файла из файлового хранилища"
  }
```

Получение источника данных

utils.getFileDataSource(file)

Получение источника данных (DataSource) для указанного файла.

Параметр метода:
- file — файл.