File Manager API reference

Flmngr gives you a powerful API to preload its library, open a file manager/file picker, edit and upload some images, and other features.

This is a new version of Flmngr API available since we released a new NPM package but also available on the other integrations too. Legacy API is still supported and will work, but we recommend migrating to this new API.

Open File Manager

Flmngr.open
( { params } )

Opens file manager dialog to let the user select or manage files.

Setting various isMultiple parameter you can open a dialog for picking different numbers of files or images (or just open a manager without ability to return any file).

You can pass preselected files using parameter list and limit file extensions with acceptExtensions.

Parameters

  • ...common parameters

    :
    { any parameters of Flmngr.load() method }

    All parameters which you can pass to Flmngr.load({params}) method are also available here too. So you can override some values (except apiKey) or pass parameters missing in Flmngr.load() call but required for this method, i. e. urlFiles and urlFileManager.

  • list

    :
    string[] | null

    An URL or a list of URLs which need to be preselected when file manager opens.

    You omit this parameter or pass null need to open file picker with no file selected. But if you wish to let user editing its previous file selection, please specify this parameter.

    Each URL must start with urlFiles in the path (they need to exist in your storage).

    Not applicable when isMultiple is set to null (when the file manager does not expect any file to be picked).

    Default is null (no preselected file) Optional

  • acceptExtensions

    :
    string[] | null

    A list of exceptions to accept when the user picks some files or file. This will also filter all others files and images from the file view.

    For example, you can limit picking only images by setting the value to ["png", "jpg", "jpeg", "webp"] or if you wish to let the user select only PDF files: ["pdf"].

    Not applicable when isMultiple is set to null (when the file manager does not expect any file to be picked).

    Default is null (any file extension is accepted) Optional

  • isMultiple

    :
    boolean | null

    Defined how many files you wish this dialog to return.

    Default is false Optional

    • false

      Opens the file manager to select a single file or image.

    • true

      Opens the file manager to select multiple files or images.

    • null

      Opens the file manager just to manage the file system without the ability to pick anything.

  • isMaximized

    :
    boolean

    Controls an initial file manager dialog state: maximized window or a dialog.

    Default is false (dialog) Optional

  • showMaximizeButton

    :
    boolean

    Show or hide maximize/unmaximize button.

    Default is true Optional

  • showCloseButton

    :
    boolean

    Show or hide close button.

    You can set to to false if wish to disable close dialog (cancel) feature.

    Default is true Optional

  • allowReorder

    :
    boolean

    You can enable or disable reordering picked files when the file manager is opened with isMultiple set to true.

    Flmngr file manager always passes a list of files and images picked by the user into onFinish listener ordered as files were shown in the pick area of the dialog.

    Default is true Optional

  • createImageFormats

    :
    string[]

    A list of image formats IDs to retrieve. You can set here IDs specified in imageFormats, so when onFinish listener is called you automatically receive the URLs of generated previews of selected images.

    For example, you can ask to generate small and medium previews (if didn't change imageFormats parameter) by setting the value to ["preview", "medium"].

    Default is null (get only original images) Optional

  • onFinish

    :
    () => { files: { url: string, formats: { format: string, url: string }[] }[] }

    A callback to receive a file list specified by the user.

    Each file has a URL but also (if required by the createImageFormats parameter) will contain a formats array with a set of required formats, where the format field of each image variant will contain an ID of the requested format.

    Optional Default is null, but you should set a callback if expect some file will be picked by the user.

  • onCancel

    :
    () => {}

    A callback to handle a moment when the user closed the dialog without picking a file.

    Default is null Optional

Edit and upload an image

Flmngr.editAndUpload
( { params } )

Opens ImgPen image editor for specified image and uploads saved image to your server with File Manager backend.

This method combines two other methods from this API: Flmngr.edit({params}) and Flmngr.upload({params}).

Specify an URL or Base64 image data in url parameter and receive a new URL of the uploaded image in onSave() callback after the user saves the image.

Parameters

  • ...common parameters

    :
    { any parameters of Flmngr.load() method }

    All parameters which you can pass to Flmngr.load({params}) method are also available here too. So you can override some values (except apiKey) or pass parameters missing in Flmngr.load() call but required for this method, i. e. urlFiles and urlFileManager.

  • url

    :
    string

    An URL of an image you wish to edit and save.

    You can specify some image from your storage of Flmngr, external URL (outside of Flmngr storage specified in urlFiles), or Base64 image data.

    If you specified an external URL or Base64 image data, you should specify dirUploads directory (if you didn't, defaultUploadDir will be used).

    When using Base64 image please also specify a filename for the default filename. For external images, it will be an URL part between the last / symbol and ? or end of the URL.

    Note: if a domain of the page where the user edits an image is not the same as a domain where the image to edit is located (subdomains are different domains), you must configure CORS header of HTTP server (NGinx/Apache/...) on the server with the image to allow access from the domain from which you load Image Editor. Without doing this Image Editor will show a blank image!

  • dirUploads

    :
    string

    This parameter will set a directory you wish to upload into.

    Is used for external URLs and Base64 images only. Will not be used for images that are located inside Flmngr storage because their directory is already defined so Image Editor will ask to overwrite or rename the image on save.

    The path of this directory is relative to urlFiles (dirFiles option on the server).

    If you set it beforet it will override a value defaultUploadDir by calling Flmngr.load({params}) separately.

    The default is "/" (root directory of your storage) if defaultUploadDir was not set.Optional

  • filename

    :
    string

    If you passed an external URL and the filename was not detected or you passed a Base64 image, you should set this parameter to define a default filename for an image to save.

    Default is "image" (extension is set depending on a file format specified by the user in the save dialog). Optional

  • onSave

    :
    (urlNew: string) => void

    A callback to handle successful finish editing and saving (uploading) of an image. Get the full absolute URL from the urlNew argument of the callback.

    Default is null Optional

  • onCancel

    :
    () => void;

    A callback to handle if the user cancelled editing (and saving) an image and closed the Image Editor dialog.

    As you see there is no onFail callback. This is because all faults while saving an image will lead to showing an error dialog and will return the user to the save image dialog back. So he or she can only cancel whole the editing and go into onCancel or successfully finish with onSave.

    Default is null Optional

Edit an image

Flmngr.edit
( { params } )

Opens ImgPen image editor for specified image lets you manually handle the moment when users presses "Save" button. So you can save it anywhere you want, upload it to a server or not, and also add your custom logic to manage file conflicts.

You can call Flmngr.upload({params}) to upload an image to the Flmngr server if you do not use any custom saving logic, but we recommend you to use Flmngr.editAndUpload({params})instead of a combination of Flmngr.edit() and Flmngr.upload() methods, due to this is easier.

Specify an URL or Base64 image data in url parameter and handle the saving process in onSave() callback when users ask to save the edited image.

Parameters

  • ...common parameters

    :
    { any parameters of Flmngr.load() method }

    All parameters which you can pass to Flmngr.load({params}) method are also available here too. So you can override some values (except apiKey) or pass parameters missing in Flmngr.load() call but required for this method, i. e. urlFiles and urlFileManager.

  • url

    :
    string

    An URL of an image or Base64 image data you with to edit.

    This parameter is fully equivalent to url parameter of Flmngr.editAndUpload({params}) method, so please read its detailed info to understand all your abilities and pitfalls.

  • onSave

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

    A callback to handle when the user presses the "Save" button in the dialog of Image Editor.

    After any checks you wish to do before saving, please call onExport() method (retrieves data of the image as File object) passed as an argument. Then handle the result inside onExported() and onFail().

    If your logic detects some fail (or you fall into onFail() callback), you may want to show some error message. Then just return from this onSave callback so the user will return to the edit image dialog.

    If your code has successfully exported the image and saved it wherever you wanted, close the Image Editor dialog by calling onClose() method (the 2nd argument of this callback).

  • onCancel

    :
    () => void;

    A callback to handle if the user cancelled editing (and saving) an image and closed the Image Editor dialog.

    As you see there is no onFail callback. This is because all faults while saving an image will lead to showing an error dialog and will return the user to Image Editor back. So he or she can only cancel whole the editing and go into onCancel or successfully finish with onSave.

    Default is null Optional

Upload files and images

Flmngr.upload
( { params } )

Uploads single or multiple files to the server without showing any UI elements.

Specify files in filesOrLinks parameter and target folder in dirUploads one. You can switch overwrite/autorename mode using the mode parameter.

It's useful to combine this method with one of Flmngr.selectFiles({params}) or Flmngr.selectUrls({params}) methods to allow users to specify files before uploading.

What's next: you can use your image by returned URL. Optionally if you need to create some image formats (i. e. previews) for uploaded files, call Flmngr.createImageFormats({params}) method then. But if you just need to regenerate already existing previews - do nothing, Flmngr.upload({params}) method automatically does this for all passed imageFormats.

Code samples:

Parameters

  • ...common parameters

    :
    { any parameters of Flmngr.load() method }

    All parameters which you can pass to Flmngr.load({params}) method are also available here too. So you can override some values (except apiKey) or pass parameters missing in Flmngr.load() call but required for this method, i. e. urlFiles and urlFileManager.

  • :
    (File|string)[]

    A list of files or links you wish to upload programmatically, so you can mix Files objects and string URLs in this array and Flmngr will return them in the same order inside onFinish callback.

  • dirUploads

    :
    string

    This parameter will set a directory you wish to upload into.

    The path of this directory is relative to urlFiles (dirFiles option on the server).

    If you set it before, it will override a value defaultUploadDir by calling Flmngr.load({params}) separately.

    The default is "/" (root directory of your storage) if defaultUploadDir was not set.Optional

  • mode

    :
    string

    Switch between file overwriting and automatic renaming on upload using this parameter.

    Default is "OVERWRITE". Optional

    • "OVERWRITE"

      All uploaded files will overwrite existing ones on your server if they exist in the same folder with the same name.

    • "AUTORENAME"

      The file manager will automatically rename newly uploaded files that conflict with existing ones. The name of renamed files will be like "image_1.png".

  • onFinish

    :
    ( files: { url: string, name: string, size: number, timestamp: number, blurHash: string, width: number, height: number, }[] ) => void;

    A callback to handle the successful finish of file uploading. This callback will receive a list of files ordered as you specified in filesOrLinks parameter.

    Each file will have url parameter you can use, but there will be also more additional info especially since this is an image file.

    url is a full absolute URL (based on urlFiles you passed) that you can use everywhere, name is the name of file in the file system, size is the number of bytes files takes on disk, timestamp comes in millisec from Unix epoch, width and height are in pixels, blurHash is a super small preview of an image.

    Default is null Optional

  • onFail

    :
    (error: string) => void;

    A callback to handle any faults while uploading. If the upload finishes with a negative result, this callback is called with an error parameter containing a human-readable description of the problem.

    Default is null Optional

Create resized images

Flmngr.createImageFormats
( { params } )

Creates variants for your images which are already stored in your server storage. This method does not show any UI until you change showProgress parameter.

For example, you just uploaded some image using Flmngr.upload({params}) method and wish to insert a preview linked to the original image. So you already have an original image and need to create a preview for it. The preview will be stored near the original image with the -preview suffix in the file name (Flmngr dialog groups all image formats in the list, so you will not have chaos in files after that).

To do this pass all image formats you have across your app as imageFormats (if you have not already done that in Flmngr.load({params}) method) and require desired formats in createImageFormats parameter.

So you will receive an URL of the newly generated image in onFinish callback.

Parameters

  • ...common parameters

    :
    { any parameters of Flmngr.load() method }

    All parameters which you can pass to Flmngr.load({params}) method are also available here too. So you can override some values (except apiKey) or pass parameters missing in Flmngr.load() call but required for this method, i. e. urlFiles and urlFileManager.

  • urls

    :
    string[]

    A list of URLs of images that already exist in your server storage to create another image formats.

  • createImageFormats

    :
    {[formatId: string]: string}

    A key-pair set with format IDs you passed in imageFormats as keys and a strategy of format creation as values.

    Possible strategies for format creation:

    • "ALWAYS"

      An image variant will be created if does not exists, and will be mandatorily refreshed even if the file already exists.

    • "DO_NOT_UPDATE"

      An image variant will be created only if its file does not exist. If there is already such file, it will be returned in onFinish callback. This way is good if you wish to use cached copy whenever it exists.

    • "IF_EXISTS"

      Image variant will be created only if its file does exist. So this is a way to regenerate a preview if you have changed its original directly via filesystem (there is no need to do this manually after Flmngr.upload({params}) because it does the same automatically).

  • showProgress

    :
    boolean

    Set to true if you wish to have a modal progress bar on the screen while creating formats. For custom handling progress you can use - onProgress handler.

    Default is false. Optional

  • onFinish

    :
    (result: { [url: string]: { [formatId: string]: string } }) => void

    A callback to handle successful image variants creation. The result is an associative array where keys are urls you passed to the method, and values are arrays of format ID - URL pairs (the same format IDs you passed in createImageFormats).

  • onProgress

    :
    (finished: number, failed: number, total: number) => void

    A listener is called every time the progress changes. It gives to you a number of processed URLs, a number of failed ones, and a percentage progress in the total argument. This callback is useful for implementing a custom progress bar in your app.

    Default is null Optional

Load File Manager

Flmngr.load
( { params } )

Loads the libraries of file manager from CDN and optionally preconfigures it with some parameters.

It's recommended to run this method right when the page loads to avoid loading delays. If you will not do it, Flmngr will be loaded on the first call and you will need to pass all parameters of this function to another Flmngr method. This is actual just for integrations based on NPM package, in other configurations do not use this function, just call the desired method as usual.

Manually call Flmngr.load()

Integrations:

Call Flmngr.load() method when the page loads. If you don't do that, please pass the same parameters in the desired method merged with its parameters (the user will wait until Flmngr is loaded in this case).

No need to call Flmngr.load()

Integrations:

All these integrations will preload Flmngr with an API key specified in another place.

*** JS snippet integration loads Flmngr with your API key but does not configure it. So you will need to pass at least urlFiles and urlFileManager to every method you call, for example to Flmngr.open({params}).

Parameters

  • apiKey

    :
    string

    Your Premium API key or FLMNFLMN if you use a free version.

    Do not pass this parameter when you use some integration that automatically loads Flmngr with some API key: any JS snippet based app, CKEditor, TinyMCE, Drupal, Froala.

    This parameter is for NPM package based integrations only: direct use of the NPM package in your app, React, Vue, etc.. In such configurations, you can omit it if passed an API key at least once in some Flmngr method including Flmmngr.load(apiKey) which is recommended to call when the page loads.

    Do not mix different API keys in one application, only the first one will be used.

  • urlFiles

    :
    string

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

    In a multi-user environment, you can dynamically set this parameter depending on the current user logged into your app/CMS (do not forget to also set the directory on the server in the same way).

  • urlFileManager

    :
    string

    URL on your server which will serve all requests from Flmgnr. This is the URL you bound Flmngr backend to. For example: https://example.com/scripts/flmngr.php

  • urlFileManager__CSRF

    :
    ( onSuccess: ( result: { headers?: {[key: string]: string}, params?: {[key: string]: string} } ) => void, onError: () => void ) => void

    A callback to prepare CSRF token if your app requires that.

    This parameter must contain a callback Flmngr will execute before any request to the server.

    This callback should obtain CSRF token from your app and pass it into the onSuccess() listener with POST parameters (params field) or headers (headers field). Flmngr will set such parameters and/or headers when sending the request.

    If there was an error while getting the CSRF token, call the onError() listener. Flmngr won't make any request in this case.

    If your app does not require a CSRF token, just omit this parameter.

    Default is null Optional

  • urlFileManager__user

    :
    string

    urlFileManager__password

    :
    string

    These two parameters can be used to set HTTP Basic Authentication credentials if your server uses such access checking.

    Default is null for both parameters. Optional

  • accessKey

    :
    string

    When you use Amazon S3 or Azure Blob storage support, please specify your access key here. So you do not need to expose whole the configuration when allowing access to cloud storage for your users, you expose only the access key which is linked to the credentials kept in secret. The access key can be changed when you need it.

    Default is null. Optional

  • apiKeyUnsplash

    :
    string

    Please specify the Unsplash API key as a value of this parameter in order to access 30000+ free stock images from the file manager.

    Default is null. Optional

  • isMaximized

    :
    boolean

    Defines whether the file manager dialog should be opened maximized or not.

    Default is false. Optional

  • showMaximizeButton

    :
    boolean

    Defines whether the file manager dialog should show maximize button in the title or not. Set to false if wish to avoid maximizing the dialog by the user.

    Default is true. Optional

  • showCloseButton

    :
    boolean

    Defines whether the file manager dialog should show a close button in the title or not. Set to false if wish to deny closing the dialog without picking some file.

    Default is true. Optional

  • hideFiles

    :
    string[]

    Setting this filter will hide some files in the list. For example, you can filter out all *.bmp files.

    Default is [".htaccess", ".htpasswd", ".gitignore"].Optional

  • hideDirs

    :
    string[]

    Setting this filter will hide some directories in the tree. For example, you can filter out .git folders.

    The default is [".cache", ".tmp", "tmp"].Optional

  • defaultUploadDir

    :
    string

    Defines default upload directory inside your storage. This parameter is not used when the file manager dialog was opened using Flmngr.open({params}) because there is always some selected directory there. But this parameter will be used when you call Flmngr.upload({params}) without dirUploads option.

    The path of this directory is relative to urlFiles (dirFiles option on the server).

    Default is "/" (root directory of your storage).Optional

  • uploadThreads

    :
    number

    When the user uploads bulk files, the Flmngr file manager will upload them simultaneously. This parameter defined a maximum number of simultaneous upload threads

    Default is 5.Optional

  • filesPerPortion

    :
    number

    File manager shows files with automatic pagination executed when users scroll the files list till the end. This parameter defines how many files should contain one such page.

    Default is 100.Optional

  • imageFormats

    :
    { id: string; title: string; suffix: string; maxWidth: number|null; maxHeight: number|null; }[]

    Image formats parameter defined how the Flmngr file manager should deal with different image formats. For example, you can have image.png and image-preview.jpg so the file manager will group them in the file list view if you have a format with the -preview suffix. Deleting an original will also delete its formats, the same is for renaming, moving, etc..

    Flmngr can also automatically create image formats when you need it, for example when the user inserts an image as a preview. To do this you need to define this parameter and call Flmngr.open({params}) with the parameter Flmngr.createImageFormats({params}) - a set of image format IDs you need to get with a picked file.

    In the same way, you can programmatically request image formats for some image and they will be created if did not exist before, see Flmngr.createImageFormats({params}) method for that.

    Another feature is to automatically resize the original image to be smaller than maxWidth and maxHeight of the default image format.

    Optional Default is:

    [
      {
        "id": "preview",
        "title": "Preview",
        "suffix": "-preview",
        "maxWidth": 480,
        "maxHeight": 480
      },
      {
        "id": "medium",
        "title": "Medium",
        "suffix": "-medium",
        "maxWidth": 1024,
        "maxHeight": 1024
      },
      {
        "id": "default",
        "title": "Default",
        "suffix": null,
        "maxWidth": 10000,
        "maxHeight": 10000
      }
    ]

Check Flmngr is loaded

Flmngr.isFlmngrLoaded
(): boolean

Returns true if Flmngr library is fully loaded and you can call the file browser. false is returned when Flmngr is not fully loaded, but some of the utility methods are still ready for use (i. e. this one).

Use this method only if you have an integration listed in the left column of the integrations table. If your integration is listed in the right column, just check window.flmngr variable is set.

When you call Flmngr methods like Flmngr.open({params}), Flmngr.upload({params}), and others, they will wait until Flmngr is fully loaded and then call the requested action automatically. Always check Flmngr for loaded before calling such methods if you wish to execute the methods only when everything is ready.

Check ImgPen is loaded

Flmngr.isImgPenLoaded
(): boolean

Returns true if ImgPen image editor library is fully loaded and you can call Image Editor. false is returned when ImgPen is not fully loaded, but some of the utility methods are still ready for use (i. e. this one).

Use this method only if you have an integration listed in the left column of the integrations table. If your integration is listed in the right column, just check window.imgpen variable is set.

When you call Flmngr methods Flmngr.edit({params}) it will wait until ImgPen is fully loaded and then call the requested action automatically. Always check ImgPen for loaded before calling this method if you wish to open Image Editor only after everything is ready.

Even if the ImgPen image editor is not loaded, you can call the file browser with Flmngr.open({params}) method. If the user will call the image editor from there, the Flmngr file manager will wait until ImgPen is really loaded.

Check Flmngr and ImgPen are loaded

Flmngr.isLoaded
( checkImgPenToo: boolean ): boolean

Returns true if both Flmngr and ImgPen are loaded.

This is a combination of Flmngr.isFlmngrLoaded() and Flmngr.isImgPenLoaded() methods.

Parameters

  • checkImgPenToo

    :
    boolean

    Do you wish to check both Flmngr and ImgPen for loaded or just Flmngr? Set to false if want to omit check for ImgPen is loaded.

    Default is true. Optional

Get supported image extensions

Flmngr.getImageExtensions
(): string[]

Returns a list of supported image extensions. Flmngr will display their previews in the list and give tools for editing some of them (obviously editing of svg is not available and editing of gif will drop all frames from the second if this GIF has animation).

The current list of such extensions is: ['png', 'jpeg', 'jpg', 'webp', 'svg', 'gif', 'bmp'] but may be extended in the future.

Construct unique URL to prevent caching

Flmngr.getNoCacheUrl
( url: string ): string

Adds no-cache parameter to the end of URL with a value of the current timestamp in milliseconds. This is useful when you've edited a file in the image editor and now wish to force your app to refresh it. There is no way to tell the browser to refresh with some URL without refreshing a page, so this method will help you. After you save inserted image you can remove the such parameter from the URL, but this is up to you.

If you pass an URL with the no-cache parameter to some Flmngr method like Flmngr.open({params}) it will automatically internally remove the no-cache parameter from the URL, so you do not need to handle this manually, keep your mind clear when passing such URLs to any method of Flmngr file manager API.

Note that this method will not generate an URL which will force any browser of a user/visitor to request an image every time. It will only force each browser to update the image to this version and then standard caching policies of caching on your website will work.

Parameters

  • url

    :
    string

    URL you wish to retrieve the no-cache version for.

Let user to specify external URLs

Flmngr.selectUrls
( {params} )

Opens a dialog where the user can specify a single URL or multiple URLs for further use by your application.

This method will not open a standard File Manager dialog, it will open just a simple textbox/textarea in a modal dialog for non-checked input.

Then you can pass these URLs into Flmngr.upload({params}) method to relocate these URLs into your server storage.

Parameters

  • ...common parameters

    :
    { any parameters of Flmngr.load() method }

    All parameters which you can pass to Flmngr.load({params}) method are also available here too. So you can override some values (except apiKey) or pass parameters missing in Flmngr.load() call but required for this method, i. e. urlFiles and urlFileManager.

  • isMultiple

    :
    boolean

    Sets a type of dialog which will be opened - with textbox input for one URL only or with textarea input where the user can specify one URL per each line.

    Default is false. Optional

  • onFinish

    :
    (urls: string[])

    Called on the user to confirm the specified URL or URLs and the dialog was closed and returns all user URLs in the same order.

  • onCancel

    :
    ()

    Called on user pressed the cancel button and the dialog was closed.

    Default is null. Optional

Let user to specify local files from his computer

Flmngr.selectFiles
( {params} )

Opens a standard dialog of a browser where the user can specify file or files from his computer for further use by your application.

This method will not open the standard File Manager dialog, it opens just a simple file select dialog of a browser. Do not confuse it with Flmngr.open({params}) method.

Then you can pass these files into Flmngr.upload({params}) method to upload these files into your server storage.

Code samples:

Parameters

  • isMultiple

    :
    boolean

    Specify whether one or more files will be allowed to select.

    Default is false. Optional

  • acceptExtensions

    :
    string[]

    A list of file extensions to allow to select.

    For example, you can pass [".doc", ".docx"] if you wish to allow selecting only Microsoft Word documents. You can also specify allowed image extensions here.

    Note, some legacy versions of browsers (especially their Linux versions) ignore this parameter. So please re-check the file types the user selected after you got them.

    Default is null (all file extensions are allowed). Optional

  • onFinish

    :
    (files: File[])

    This callback will be called after the user successfully selected some files or images. Argument files contain an array of standard File entities of a browser.

    There is no onCancel callback due to browsers do not support it.