Class Flmngr

This is Flmngr class you should use to interact with your server to access files: upload, list, modify or delete them. This class contains API both for atomic actions (select file, upload, ...) and for further using main API of Flmngr.

Here are installation docs

See explained examples of usage with CodePen samples:

Hierarchy

  • Flmngr

Index

Constructors

constructor

  • new Flmngr(params: { defaultUploadDir?: string; imageFormats?: FlmngrImageFormat[]; imgPen?: any; uploadThreads?: number; urlFileManager: string; urlFiles: string }): Flmngr
  • Creates new instance of Flmngr client. This action usually made just once to preconfigure Flmngr and do not pass all the options into Flmngr methods. Save returned object and use it as Flmngr API.

    Please see [the samples of initialization](@link /doc/open-file-manager).

    Parameters

    • params: { defaultUploadDir?: string; imageFormats?: FlmngrImageFormat[]; imgPen?: any; uploadThreads?: number; urlFileManager: string; urlFiles: string }
      • Optional defaultUploadDir?: string

        The directory where to place all quick uploads. Relative to the location of URL specified in urlFiles. This directory inside your storage will be used when you call some method without defining a directory where to save files.

      • Optional imageFormats?: FlmngrImageFormat[]

        The list of custom image formats and proportions you need to resize images too.

        For example you plan to request images with generated previews by using the method pickFiles - you need to define preview format here just once. This will also affect for filtering images of these formats inside the file manager browser window.

        For more details please see FlmngrImageFormat class and the sample

      • Optional imgPen?: any

        If you wish to use pass some specific settings into ImgPen image editor, use this field to create and pass whole image editor instance as value like: new ImgPen({ cropRatios: [{w: 4, h: 3}, {w: 3, h: 2}] })

      • Optional uploadThreads?: number

        Maximum thread number for uploading files. Only this number of connections Flmngr will open at once interacting with the backend.

        default

        5

      • urlFileManager: string

        URL on your server which will serve all requests from Flmgnr. This is the URL you bound Flmngr backend to.

      • urlFiles: string

        Prefix to your files directory in URL notation. For example: https://example.com/images/

    Returns Flmngr

Methods

createImageFormats

  • createImageFormats(params: { imageFormats: {}; onFinish: (result: {}) => void; onProgress?: (finished: number, failed: number, total: number) => void; showProgress?: boolean; urls: string[] }): void
  • Asks server to generate another formats of images. For example you need to generate a preview for your image or a set of resized user's avatars in two or more different sizes (this method is very flexible).

    Parameters

    • params: { imageFormats: {}; onFinish: (result: {}) => void; onProgress?: (finished: number, failed: number, total: number) => void; showProgress?: boolean; urls: string[] }
      • imageFormats: {}

        The associative array of formats you need to the mode of how to process this format. The formats must be already defined in imageFormats parameter passed to Flmngr.constructor, here you only list which do you require: they will be applied to each URL you pass as urls.

        Modes can be:

        • "ALWAYS" - resized image will be created or recreated
        • "IF_EXISTS" - only update existing previews
        • "DO_NOT_UPDATE" - only create new images (use already existing as cache)

        Example:

        imageFormats: {
            "preview": "ALWAYS"
        }
        • [key: string]: string
      • onFinish: (result: {}) => void

        Success callback returning you a result in format: source URL to map of formats (image format id to an URL of generated image).

          • (result: {}): void
          • Parameters

            • result: {}
              • [url: string]: {}
                • [formatId: string]: string

            Returns void

      • Optional onProgress?: (finished: number, failed: number, total: number) => void

        Called each time Flmngr has any progress with creating image format.

          • (finished: number, failed: number, total: number): void
          • Parameters

            • finished: number
            • failed: number
            • total: number

            Returns void

      • Optional showProgress?: boolean

        If set to true, the dialog with the progress indicator will be shown until the request is finished.

        default

        false

      • urls: string[]

        The list of URLs stored on your file server which do you need to resize. All of them must start with prefix from urlFiles (passed to Flmngr.constructor) in order to correctly detect their directory (resized images will be places in the same directory).

    Returns void

edit

  • edit(params: { onCancel: () => void; onSave: (onExport: (name: string, ext: string, jpegQuality: number, onExported: (image: File) => void, onFail: () => void) => void, onClose: () => void) => void; url: string }): void
  • Opens ImgPen image editor dialog and allows you to decide what to do with a result.

    Custom image editing CodePen sample is available

    Parameters

    • params: { onCancel: () => void; onSave: (onExport: (name: string, ext: string, jpegQuality: number, onExported: (image: File) => void, onFail: () => void) => void, onClose: () => void) => void; url: string }
      • onCancel: () => void

        Callback fired when user cancels editing an image.

          • (): void
          • Returns void

      • onSave: (onExport: (name: string, ext: string, jpegQuality: number, onExported: (image: File) => void, onFail: () => void) => void, onClose: () => void) => void

        Callback fired when user presses "Save" button.

        param

        call it to export a canvas data into some image format.

        param

        call it to close image editor dialog.

          • (onExport: (name: string, ext: string, jpegQuality: number, onExported: (image: File) => void, onFail: () => void) => void, onClose: () => void): void
          • Parameters

            • onExport: (name: string, ext: string, jpegQuality: number, onExported: (image: File) => void, onFail: () => void) => void
                • (name: string, ext: string, jpegQuality: number, onExported: (image: File) => void, onFail: () => void): void
                • Parameters

                  • name: string
                  • ext: string
                  • jpegQuality: number
                  • onExported: (image: File) => void
                      • (image: File): void
                      • Parameters

                        • image: File

                        Returns void

                  • onFail: () => void
                      • (): void
                      • Returns void

                  Returns void

            • onClose: () => void
                • (): void
                • Returns void

            Returns void

      • url: string

        URL of Base64 string with image data. URL can link into your storage or outside of it.

    Returns void

editImageAndUpload

  • editImageAndUpload(params: { dirUploads?: string; onCancel?: () => void; onFail?: (error: string) => void; onSave?: (urlNew: string) => void; url: string }): void
  • Opens ImgPen image editor and saves a result image on the server after user presses "Save". This is a composite method of edit and upload methods (see them for more detailed parameters explanation).

    Here is CodePen sample of editing and saving an image

    Parameters

    • params: { dirUploads?: string; onCancel?: () => void; onFail?: (error: string) => void; onSave?: (urlNew: string) => void; url: string }
      • Optional dirUploads?: string

        Directory to upload into.

      • Optional onCancel?: () => void

        When user presses "Cancel" in the image editor, this callback is called.

          • (): void
          • Returns void

      • Optional onFail?: (error: string) => void

        Callback fired on upload failed. If this method is not specified, Flmngr will just show this error message.

          • (error: string): void
          • Parameters

            • error: string

            Returns void

      • Optional onSave?: (urlNew: string) => void

        The same as onFinish callback of upload method, but only one URL is passed here (as string instead of an array of strings).

          • (urlNew: string): void
          • Parameters

            • urlNew: string

            Returns void

      • url: string

        URL of an image to edit.

    Returns void

getBackendVersion

  • getBackendVersion(callback: (version: { language?: string; version: string }, detectionError?: string) => void): void
  • Asks a server for a version of backend. This is asynchronous function due to requires to ask server about a version. In case such request was already done (made on Flmngr initialization automatically), callback will be called immediately.

    Parameters

    • callback: (version: { language?: string; version: string }, detectionError?: string) => void
        • (version: { language?: string; version: string }, detectionError?: string): void
        • Parameters

          • version: { language?: string; version: string }
            • Optional language?: string
            • version: string
          • Optional detectionError: string

          Returns void

    Returns void

getImageExtensions

  • getImageExtensions(): string[]
  • Returns string[]

    image extensions currently supported by Flmngr. At this version they are: ['png', 'jpeg', 'jpg', 'webp', 'svg', 'gif', 'bmp'].

getNoCacheUrl

  • getNoCacheUrl(url: string): void
  • Modifies passed URL to be unique.

    A new URL parameter no-cache with current time in millis will be added to it. This is useful especially when you expect user will edit some image, but its URL will not change. In this case there is no other way to force browser reload the image if you show it on the page.

    Anyway this will not break caching image on the user side because even such image will stay on public webpage content, its URL is still constant and can be cached by browsers.

    You can safely pass such URLs into pickFiles method without any reverse action - it understands this format. And will return URLs cleaned from these `no-cache` parameter, so you will decide to add it again or not.

    Parameters

    • url: string

    Returns void

pickFiles

  • pickFiles(params: { acceptExtensions?: string[]; allowReorder?: boolean; dirUploads?: string; imageFormats: string[]; isMultiple?: boolean; list?: string[]; onCancel: () => void; onFinish: (files: FlmngrFileWithFormats[]) => void }): void
  • This is the base method to show file manager dialog and let user to select file or files.

    Parameters

    • params: { acceptExtensions?: string[]; allowReorder?: boolean; dirUploads?: string; imageFormats: string[]; isMultiple?: boolean; list?: string[]; onCancel: () => void; onFinish: (files: FlmngrFileWithFormats[]) => void }
      • Optional acceptExtensions?: string[]

        The list of extensions to accept. By default all file extensions are accepted.

      • Optional allowReorder?: boolean

        You can block files reordering by setting this option to false.

        default

        true

      • Optional dirUploads?: string

        The directory for file uploads. If you do not specify anything defaultUploadsDir passed previosly to Flmngr.constructor will be used here.

      • imageFormats: string[]

        The required list of IDs of image formats already defined as imageFormats parameter of Flmngr.constructor.

        default:

        []

      • Optional isMultiple?: boolean

        The flag indicating do we operate a list or a single file.

        default:

        true

      • Optional list?: string[]

        The list of URLs you already have and want user to extend or modify

        default:

        []

      • onCancel: () => void

        Called if user cancelled picking files.

          • (): void
          • Returns void

      • onFinish: (files: FlmngrFileWithFormats[]) => void

        Callback called on success with the list of specified files. files is an array of selected files with additional required formats (inside formats field of each file structure).

    Returns void

selectFiles

  • selectFiles(params: { acceptExtensions?: string[]; isMultiple: boolean; onFinish: (files: File[]) => void }): void
  • Opens standard browser dialog to select a files (not Flmngr dialog of pickFiles method).

    Parameters

    • params: { acceptExtensions?: string[]; isMultiple: boolean; onFinish: (files: File[]) => void }
      • Optional acceptExtensions?: string[]

        The flag shows files of which extension can user specify. Note. Not all browsers support this option, some legacy ones can ignore it or use not too accurate.

      • isMultiple: boolean

        The flag shows can user specify many files or just one. Note. Not all browsers support this flag, some legacy ones can ignore it.

      • onFinish: (files: File[]) => void

        The callback fired when user selected some files.

          • (files: File[]): void
          • Parameters

            • files: File[]

            Returns void

    Returns void

selectUrls

  • selectUrls(params: { isMultiple: boolean; onCancel: () => void; onFinish: (urls: string[]) => void }): void
  • Opens the dialog where user can specify some URL or list of URLs.

    Parameters

    • params: { isMultiple: boolean; onCancel: () => void; onFinish: (urls: string[]) => void }
      • isMultiple: boolean

        The flag shows can user specify many files or just one.

      • onCancel: () => void

        Called when user presses "Cancel" button.

          • (): void
          • Returns void

      • onFinish: (urls: string[]) => void

        The callback fired when user specified a list of URLs and pressed "OK".

          • (urls: string[]): void
          • Parameters

            • urls: string[]

            Returns void

    Returns void

upload

  • upload(params: { dirUploads?: string; filesOrLinks: (File | string)[]; onFail: (error: string) => void; onFinish: (urls: string[], paths: string[]) => void }): void
  • Uploads files or links (a list of URLs) to a specified directory on the server. If there is no directory selected, the default upload directory (defaultUploadDir parameter passed to Flmngr.constructor) will be used.

    See explained CodePen sample of uploading files

    Parameters

    • params: { dirUploads?: string; filesOrLinks: (File | string)[]; onFail: (error: string) => void; onFinish: (urls: string[], paths: string[]) => void }
      • Optional dirUploads?: string

        The directory to upload files into. If not specified, the default upload directory will be used. Relative to the root of the file storage.

      • filesOrLinks: (File | string)[]

        The list of files or links to upload. You can pass file objects of your own application, ask user for files with the method selectFiles or specify external URLs.

      • onFail: (error: string) => void

        Callback returning you an error occurred on upload. Getting this error means all partially uploaded files were already removed from the server and there is no any garbage neither in the upload directory nor in the temporary one (Flmngr implements transactional uploads model).

          • (error: string): void
          • Parameters

            • error: string

            Returns void

      • onFinish: (urls: string[], paths: string[]) => void

        Success callback is called when all files were uploaded. urls arrays contain a list of URLs fully formed with using prefix from urlFiles parameter you passed to Flmngr.constructor. Alternatively you can use raw paths argument to obtain paths relative to urlFiles (before merging with it).

          • (urls: string[], paths: string[]): void
          • Parameters

            • urls: string[]
            • paths: string[]

            Returns void

    Returns void

    a list of URLs of uploaded files in callback, or error message in callback.