IMCE API | UFKU.com

Integration API for IMCE 6.x

Let's create a CASE and embody the IMCE integration on it:

An application named myApp
Has an url field for file url:
<input type="text" name="urlField" id="urlField">
Has a browse button with click event: (This can be a text link or anything that is clickable)
<input type="button" value="Browse" onclick="openFileBrowser()">

Now let's go through the integration methods and define the openFileBrowser function that opens IMCE and makes it fill our url field on file selection.

1 - Integration by URL

When IMCE is opened using an url that contains

app=applicationName|fileProperty1@FieldId1|fileProperty2@FieldId2|...

the specified fields are filled with the specified properties of the selected file.

Avaliable file properties are:

url
name
size(formatted)
width
height
date(formatted)
bytes(integer size in bytes)
time(integer date timestamp)

In our CASE, we should open IMCE using this URL: /?q=imce&app=myApp|url@urlField which contains our application name and our url field id

function openFileBrowser() {
  window.open('/?q=imce&app=myApp|url@urlField', '', 'width=760,height=560,resizable=1');
}

That's all we need. Leave the rest to IMCE. It will automatically create an operation tab named "Send to myApp" that sends the file url to our url field. Clicking the files in preview do the same thing as well.

- What if we had another field for another file property e.g, Size: <input type="text" id="file-size"> ? - We should have opened imce using this URL: /?q=imce&app=myApp|url@urlField|size@file-size

2 - Integration by onLoad

A more flexible method that gives a finer control over IMCE. Note: This could be extended to alter the content or the interface of IMCE by using its javascript methods.

var imcePopup;// this is our global variable referencing to IMCE window. We use it for tracking its open/closed state

function openFileBrowser() {

  // if IMCE is closed or not opened yet.
  if (typeof imcePopup == 'undefined' || imcePopup.closed) {

    //open IMCE
    imcePopup = window.open('/?q=imce', '', 'width=760,height=560,resizable=1');
    
    //we create a function that runs when IMCE loads, by setting the imceOnLoad property of the window
    //It is automatically called by IMCE with a single parameter(win) referencing to IMCE window.
    //We can access all methods of IMCE using win.imce
    imcePopup['imceOnLoad'] = function (win) {
      //we use IMCE's setSendTo method to make a selected file sent to our imceFinish function
      //setSendTo(title, function) creates an operation tab that has the "title" and runs the "function" on click.
      win.imce.setSendTo('Give it to myApplication baby', imceFinish);
    }
  }

  //knowing the popup is opened, we bring it into view.
  imcePopup.focus();
}

//Finalizing function that is executed when the user selects a file for our application.
//This function is called with two parameters.
//file is the file object having the properties: url, name, size, width, height, date, bytes, time
//win is the reference to IMCE window. We can access all IMCE methods using win.imce
function imceFinish(file, win) {
  //We set the value of our url field using file.url
  document.getElementById('urlField').value = file.url
  //hide the popup. We don't close it in order to save time for later use.
  win.blur();
}

Integration API for IMCE 5.x

IMCE introduces two javascript hooks for custom usage. One of them is hookImceFinish function and the other is global hookImceUrl variable. In order to use these hooks one must open IMCE browser by specifying a proper window name with window.open method. That window name plus hook names will be the custom function and the custom URL.

Here is a sample code for opening IMCE with window.open:

window.open('imce/browse', 'windowName', 'width=640, height=480');

For this instance of imce there should be a previously declared function named as windowNameImceFinish and optionally a variable named as windowNameImceUrl. If the function exists, IMCE will call it when the user clicks "add" link. windowNameImceUrl will be used for highlighting if it matches any url in the file list.

hookImceFinish

This function is called with five parameters:

file path - URL of the selected file in the file list
image width - width of the selected image. (0 if it's not an image)
image height - height of the selected image.
file size - formatted file size (ex: 35.2 KB, 45 bytes, etc).
IMCE window - reference to the currently active IMCE window. it can be used for closing the pop-up.

so, one can implement a function like this:

function windowNameImceFinish(path, w, h, s, imceWin) {
  imceWin.close();
  alert('selected file path='+ path +', width='+ w +', height='+ h +', filesize='+s);
}

hookImceUrl

This optional global variable is used for highlighting of the matching url in the file list. In other words, if it's value matches any of the paths in the list, that file is highlighted.

One may change the value of this variable just before opening the IMCE pop-up.

windowNameImceUrl = '/files/images/img.gif';

You can have a look at plain textarea demo in demo page to see the API in action.

Project IMCE