Integration API for 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.

File property - Field ID method

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)
• id(file id for newly uploaded files, 0 or integer)
• relpath(rawurlencoded path relative to file directory path.)

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

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

imceload - Custom function method

You can point a predefined function to be executed when IMCE loads. When the URL is like &app=myApp|imceload@myOnloadFunc, IMCE looks for myOnloadFunc in the parent window and executes it with the window parameter referring to IMCE window.

sendto - Custom function method

You can point a predefined function to which the selected files are sent. When the URL is like &app=myApp|sendto@myFileHandler, IMCE calls myFileHandler function of the parent window with file and window parameters. Usually sendto method is easier to implement, on the other hand imceload method is more flexible as you manually add your sento operator and also can do any modification before IMCE shows up.

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:

1. file path - URL of the selected file in the file list
2. image width - width of the selected image. (0 if it's not an image)
3. image height - height of the selected image.
4. file size - formatted file size (ex: 35.2 KB, 45 bytes, etc).
5. 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.