Описание, настройки адреса загрузки и внешнего вида, привязка компонентов

Описание

Компонент flexberry-file предоставляет несколько возможностей:

  • Возможность выбора пользователем какого-либо файла на клиентском устройстве;
  • Возможность загрузки этого файла на сервер;
  • Возможность скачивания ранее загруженного файла с сервера, с последующим сохранением на клиентском устройстве;
  • Для файлов изображений также имеется возможность их предпросмотра;

Общий вид компонента, в случае, если текущая тема оформления “BlueSky”:

Компонент реализован под средства для работы с файлами имеющиеся в распоряжении OData-сервиса (читайте о них в статье “Особенности работы с файлами через OData-сервис”). Далее будем считать, что средства работы с файлами в OData-сервисе уже сконфигурированы, и файловый контроллер доступен по адресу <Адрес узла, на котором развернут OData-сервис>/api/File.

Список свойств

Название свойства Краткое описание
uploadUrl Адрес для загрузки файлов на сервер
maxUploadFileSize Максимальный возможноы размер загружаемого файла
showPreview Флаг, показывающий нужно ли отображать блок предпросмотра
showUploadButton Флаг, показывающий нужно ли отображать отдельную кнопку загрузки файла на сервер
showDownloadButton Флаг, показывающий нужно ли отображать отдельную кнопку скачивания файла с сервера
showModalDialogOnUploadError Флаг, показывающий нужно ли показывать модальнй диалог при ошибке загрузки файла
showModalDialogOnDownloadError Флаг, показывающий нужно ли показывать модальнй диалог при ошибке выгрузки файла
openFileInNewWindowInsteadOfLoading Флаг, показывающий нужно ли откывать файл в новой вкладке браузера после скачивания
previewSettings Настройки отображения модального окна предпросмотра изображений

Настройка адреса для загрузки файлов на сервер

Чтобы компонент flexberry-file мог загружать файлы на сервер, ему нужно, как минимум, знать URL для загрузки, под этот URL в компоненте предусмотрено свойство uploadUrl, в котором должен быть указан адрес файлового контроллера. Свойство uploadUrl можно сконфигурировать двумя способами:

  • Либо прямо в hbs-шаблоне: 
    {{flexberry-file
  uploadUrl="<Адрес узла, на котором развернут OData-сервис>/api/File"
}}
  • Либо в конфигурационном файле приложения config/environment.js (чтобы не указывать его каждый раз, когда используем компонент): 
    {
  ...
  APP: {
    ...
    components: {
      flexberryFile: {
        uploadUrl: '<Адрес узла, на котором развернут OData-сервис>/api/File'
      }
    }
    ...
  }
  ...
}

Файловое свойство в ember-моделях и привязка компонента к нему

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

{
  // URL для скачивания файла.
  "fileUrl":"<Адрес узла, на котором развернут OData-сервис>/api/File?...",

  // URL для скачивания preview (если файл это изображение).
  "previewUrl":"<Адрес узла, на котором развернут OData-сервис>/api/File?...&getPreview=true",

  // Наименование файла.
  "fileName":"image.png",

  // Размер файла в байтах.
  "fileSize": 12345,

  // MIME-тип файла.
  "fileMimeType": "image/png"
}

Т.к. метаописание приходит сериализованным, т.е. строкой, то с точки зрения ember-а оно совершенно ничем не отличается от любого другого строкового свойства типа string, однако в аддоне ember-flexberry-data под него все-таки сделана специальная трансформация file, для того чтобы файловые свойства можно было отличать от остальных (таким образом, например, компонент flexberyy-groupedit понимает, что для работы со свойством такого типа нужно встраивать компонент flexberry-file, а не просто flexberry-textbox). Поэтому в ember-моделях файловые свойства описываются следующим образом:

export default BaseModel.extend({
  myFileProperty: DS.attr('file')
});

Компонент flexberry-file принимает это метаописание в качестве значения свойства value, т.е. если метаописание файла находится в модели в свойстве myFileProperty, то привязка будет выглядеть следующим образом:

{{flexberry-file
  relatedModel=model
  value=model.myFileProperty
}}

Свойство relatedModel так же необходимо указывать, оно должно ссылаться на модель, в которой содержится файловое свойство, чтобы при сохранении модели компонент flexberry-file смог сначала загрузить на сервер выбранный пользователем файл (если такой имеется).

Настройки внешнего вида

Компонент flexberry-file содержит несколько настроек позволяющих настраивать его внешний вид:

  • showUploadButton - флаг, показывающий нужно ли отображать отдельную кнопку загрузки файла на сервер или нет (по умолчанию имеет значение false т.к. загрузка файла происходит при сохранении модели из свойства relatedModel и потребности в отдельной кнопке - нет).

    Внешний вид с включенной кнопкой загрузки:

  • showDownloadButton - флаг, показывающий нужно ли отображать отдельную кнопку скачивания файла с сервера или нет (по умолчанию имеет значение true).

    Внешний вид с выключенной кнопкой скачивания:

  • readonly - флаг, показывающий находится ли компонент в режиме только для чтения (по умолчанию имеет значение false). В этом режиме скрыты кнопки выбора файла, удаления файла, загрузки файла на сервер, и нет возможности изменить или удалить файл, есть только возможность его скачать.

    Внешний вид в режиме только для чтения:

  • showPreview - флаг, показывающий нужно ли отображать блок предпросмотра (по умолчанию имеет значение false, настройка актуальна для файлов изображений, в случае с файлами других типов блок предпросмотра будет пустым).

    Внешний вид с включенным блоком предпросмотра:

    Если нажать блок предпросмтора, то будет открыт модальный диалог, в котором выбранный фал изображения будет отображен в своих реальных размерах без сжатия:

    За открытие диалога отвечает action flexberryFileViewImageAction, который уже реализован в базовом контроллере форм редактирования, но если зачем-то захочется его переопределить, или выполнять какие-то другие действия по нажатию на блок предпросмотра, можно задать свой action через свойство компонента viewImageAction:

     {{flexberry-file
   ...
   showPreview=true
   viewImageAction="flexberryFileViewImageAction"
 }}

  • previewSettings - настройки отображения модального окна предпросмотра изображений (по умолчанию {}, настраивает отображение модального окна предпросомтра загруженных файлов).

    /**
  Settings for preview modal dialog.

  @property previewSettings
  @type Object
*/
previewSettings: {
  detachable: true,
  context: 'body',
},

    {{flexberry-file
  ...
  showPreview=true
  viewImageAction="flexberryFileViewImageAction"
  previewSettings=previewSettings
}}

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

Работа с файлами в формате base64

Компонент flexberry-file имеет возможность работы с файлами в формате base64.

Для этого необходимо задать компоненту несколько параметров:

  {{flexberry-file
    ...
    base64Value=base64String
    base64FileName="test"
    base64FileExtension="jpg"
  }}

base64Value - параметр, в котором должна содержаться строка в формате base64. При изменении значения base64Value и успешной обработки в файловом контроле, переменной присваивается значение null. Это связано со спецификой файлового контрола и необходимо для ситуаций, когда пользователь захочет прикрепить/заменить файл, выбранный из файловой системы после использования base64Value.

base64FileName и base64FileExtension атрибуты для имени создаваемого и загружаемого на сервер файла. Имя будет выглядеть, как :

`{base64FileName}.{base64FileExtension}`

Для отображения модального окна ошибок, при обработке base64 файлов, необходимо присвоить параметру showModalDialogOnUploadError значение true.

Настройки внешнего вида в мобильном представлении

Компонент flexberry-file имеет специальное представление для мобильных устройств.

В этом представлении компонент, в котором пользователем еще не выбран файл, выглядит как кнопка с надписью “Добавить файл” (эту надпись можно кастомизировать задав её через свойство addButtonText компонента):

Когда пользователь выбрал какой-либо файл, компонент выглядит уже как кнопка с выпадающим меню и пунктами для замены файла, его загрузки, скачивания, и в случае, если файл является изображением, его увеличения: