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 composite UI actions like pickFiles or browse.

When installing ImgPen as SDK, please use the modern (recommended) way to import Flmngr class (in JavaScript or TypeScript):

import {Flmngr} from "flmngr";

or legacy one:

let flmngrLib = require("flmngr");

If you use cloud version of Flmngr inside some WYSIWYG HTML editor, you already have Flmngr instance created and stored inside CKEDITOR.instances['id'].flmngr or TinyMCE.editors['id'].flmngr variable.

The shortest example of Flmngr file manager used together with ImgPen image editor:

import {Flmngr} from "flmngr";
import {ImgPen} from "imgpen";

let flmngr = new Flmngr({
    urlApp: 'https://example.com/flmngr',
    urlFiles: 'https://example.com/images/',
    defaultUploadDir: '/uploads/',
    imgPen: new ImgPen({
         urlBase: 'https://example.com/imgpen'
    })
});
flmngr.browse({
   isMultiple: false,
   acceptExtensions: ["png", "jpeg", "jpg", "svg", "webp", "bmp", "gif"],
   onFinish: (urls) {
       // "urls" variable here has a list of files selected
       // In this sample we just print it to console.
       console.log(urls);
   }
})

Hierarchy

  • Flmngr

Index

Constructors

constructor

  • new Flmngr(params: { defaultUploadDir: string; imageFormats?: FlmngrImageFormat[]; imgPen?: any; uploadThreads: number; urlApp: 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.

    Example:

    import {flmngrLib} from "flmngr";
    import {imgPenLib} from "imgpen";
    
    let flmngr = flmngrLib.create({
        urlApp: 'https://example.com/flmngr',
        urlFiles: 'https://example.com/images/',
        defaultUploadDir: '/uploads/',
        imgPen: new ImgPen({
            urlBase: 'https://example.com/imgpen/',
            cropRatios: [{w: 4, h: 3}, {w: 3, h: 2}]
        })
    });

    Parameters

    • params: { defaultUploadDir: string; imageFormats?: FlmngrImageFormat[]; imgPen?: any; uploadThreads: number; urlApp: string; urlFiles: string }
      • 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.

      • Optional imgPen?: any

        If you wish to use image editor together with Flmngr file manager, please pass [created ImgPen instance] as a parameter. If you set this parameter you can open the image editor from the file browser window and also call editImageAndUpload method of Flmngr.

      • uploadThreads: number

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

        default

        5

      • urlApp: 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

browse

  • browse(params: { acceptExtensions?: string[]; isMultiple: boolean; onCancel: () => void; onFinish: (urls: string[]) => void; selectedFiles?: string[] }): void
  • Opens files browser fullscreen dialog and offers user to select some file from the storage. When user selects it and presses "OK" (or cancels), the dialog is being closed.

    Parameters

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

        The set of extensions valid for selecting. Each value of an array must have this format:

        • no dot prefix
        • case insensitive
        • 'jpeg' and 'jpg' are different extensions

        All the files which have another extension will be filtered from the view.

        Use this option when you need to ask user about the exact file. Examples are below.

        Ask for an archive:

        acceptExtensions: ["zip"]

        or ask for image file of format recommended for web:

        acceptExtensions: ["png", "jpeg", "jpg", "svg", "webp"]

        or ask for any supported type of image:

        acceptExtensions: ["png", "jpeg", "jpg", "svg", "webp", "bmp", "gif"]

        By the way, you can get this list by calling getImageExtensions method.

        default

        null (any extension)

      • isMultiple: boolean

        Do you expect user will select a single file (limit with selecting one file) or there could be any number of files?

      • onCancel: () => void

        Called when user presses "Cancel" button.

          • (): void
          • Returns void

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

        Success callback with a list of URLs selected by user and already prefixed with urlFiles you passed to Flmngr.constructor.

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

            • urls: string[]

            Returns void

      • Optional selectedFiles?: string[]

        Files to select when file browser dialog is opened. By default file browser just will open its root folder without selecting any files.

        You can pass any URLs here without a worry, but only URLs, which start with [urlFiles], will be detected as files inside your storage and selected. All the other (external) URLs will be just ignored.

        Setting this option is useful when you already have a file selected in some field, so user will start from its directory (and will see in the file browser window which file or files are exactly selected).

    Returns void

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

editImage

  • editImage(params: { forcePng?: boolean; onCancel?: () => void; onSave: (file: File, onFinish: (doClose: boolean) => void) => void; url: string }): void
  • Calls ImgPen image editor. User will edit image and optionally save it. This method will not upload a result image to the server - it will only return data (please use editImageAndUpload method if you need to upload an image back).

    This is the full equivalent of calling method editImage on ImgPen object instance (pass it to Flmngr.constructor to use this feature).

    Parameters

    • params: { forcePng?: boolean; onCancel?: () => void; onSave: (file: File, onFinish: (doClose: boolean) => void) => void; url: string }
      • Optional forcePng?: boolean

        In case this option is disabled, ImgPen will return a result image in the input format (do not change JPEG to PNG). Otherwise, it will always convert it to PNG. This is recommended to keep this option set to true to avoid losing transparency which could be created by user when he edits an image.

        default:

        true

      • Optional onCancel?: () => void

        Called when user presses "Cancel" button and editor is closing.

          • (): void
          • Returns void

      • onSave: (file: File, onFinish: (doClose: boolean) => void) => void

        Callback fired when user presses "Save" inside the image editor. file contains BLOB with an image data. You can use it manually to do something, like uploading to the server (use upload method) or passing to your own application.

        When this callback is called, the progress indicator will be shown on the screen and block UI of the image editor. You do not need to use your own indicator, but after you save an image (even when you have some error) you need to call onFinish function to unblock UI (pass doClose parameter to allow or disallow closing image editor).

          • (file: File, onFinish: (doClose: boolean) => void): void
          • Parameters

            • file: File
            • onFinish: (doClose: boolean) => void
                • (doClose: boolean): void
                • Parameters

                  • doClose: boolean

                  Returns void

            Returns void

      • url: string

        URL of an image to edit. This can be the file from your own storage or an external image (with correctly configured CORS on the external server).

    Returns void

editImageAndUpload

  • editImageAndUpload(params: { dirUploads?: string; forcePng?: boolean; 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 if user presses "Save". This is a composite method of editImage and upload methods (see them for more detailed parameters explanation).

    Parameters

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

        Directory to upload into.

      • Optional forcePng?: boolean

        Force PNG or not when saving an image.

      • 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'].

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 very flexible function which is used to select, reselect and reorder files and images you need to ask user for. Despite [browse] method this one will not just ask for a file, but work in terms of files you already have selected. Use this method always when you work with lists.

    It can be used to ask files for your image gallery, but also you can pass the list of existing images in a gallery: pickFiles will return a new list of images maybe reordered and extended by end user.

    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.

      • 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.

      • Optional isMultiple?: boolean

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

        default:

        true

      • list: string[]

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

      • 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).

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

            • files: FlmngrFileWithFormats[]

            Returns void

    Returns void

selectFiles

  • selectFiles(params: { acceptExtensions?: string[]; isMultiple: boolean; onFinish: (files: File[]) => void }): void
  • Opens standard browser dialog to select a files. This method is used by composite methods like browse or pickFiles, but you also can use it separately.

    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. This method is used by composite methods like browse or pickFiles, but you also can use it separately.

    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[]) => void }): void
  • Uploads files or links (a list of URLs) to a specified directory on the server. If no directory is selected, the default upload directory (defaultUploadDir parameter passed to Flmngr.constructor) will be used.

    Parameters

    • params: { dirUploads?: string; filesOrLinks: (File | string)[]; onFail: (error: string) => void; onFinish: (urls: 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[]) => 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.

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

            • urls: string[]

            Returns void

    Returns void

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