[Summary view] [Print] [Text view]

   1  // $Id: README.txt,v 1.12.2.5 2010/11/08 04:37:36 ufku Exp $
   2  
   3  IMCE
   4  http://drupal.org/project/imce
   5  ====================================
   6  
   7  DESCRIPTION
   8  -----------
   9  IMCE is an image/file uploader and browser that supports personal directories and quota.
  10  IMCE can easily be integrated into any WYSIWYG editor or any web application that needs a file browser.
  11  See INTEGRATION METHODS for more information.
  12  
  13  FEATURES
  14  -----------
  15  - Basic file operations: upload, delete
  16  - Image(jpg, png, gif) operations: resize, create thumbnails, preview
  17  - Support for private file system
  18  - Configurable limits for user roles: file size per upload, directory quota, file extensions, and image dimensions
  19  - Personal or shared folders for users
  20  - Permissions per directory
  21  - Ftp-like directory navigation
  22  - File sorting by name, size, dimensions, date
  23  - Tabbed interface for file operations
  24  - Keyboard shortcuts(up, down, insert(or enter), delete, home, end, ctrl+A, R(esize), T(humbnails), U(pload)).
  25  - Built-in support for inline image/file insertion into textareas
  26  - Multiple file selection(using ctrl or shift)
  27  - Ajax file operations
  28  - Themable layout using tpl files
  29  
  30  INSTALLATION
  31  -----------
  32  1) Copy imce directory to your modules directory
  33  2) Enable the module at: /admin/build/modules
  34  3) Create configuration profiles and assign them to user roles at /admin/settings/imce
  35  4) Test it at /imce.
  36  5) See imce-content.tpl.php for some configuration options such as inline previewing.
  37  6) See INTEGRATION METHODS to make IMCE collaborate with your application if it's not already integrated.
  38  Notes:
  39   - When you configure IMCE for inline image/file insertion into textareas there should appear an IMCE link under each textarea you specified.
  40   - If you are uploading files containing unicode characters, it is strongly recommended to use the transliteration module that sanitizes filenames by converting characters from unicode to us-ascii. http://drupal.org/project/transliteration
  41   - If you are using CCK, you may want to check the File field sources module at http://drupal.org/project/filefield_sources
  42  
  43  
  44  FREQUENTLY FACED ISSUES
  45  -----------
  46  - Inaccessible/invalid directory or subdirectory:
  47  In some server configurations, manually(ftp or directly) created directories may not be writable by PHP(by IMCE). In this case, you have to set the chmod permissions of the directory to 0777 in order to make it writable by anyone. 
  48  You should also make sure that in each configuration profile all of the defined directories are located under drupal's file system path which is usually "files".
  49  And also if "safe mode restriction" is active in your server, don't expect IMCE to run flawlessly.
  50  
  51  - Disappearing images after node submission:
  52  Having nothing to do with IMCE, it appeared many times in issue queues. This is an input filtering issue that can be resolved by adding <img> tag into the default input format. Using Full HTML is another solution. See admin/settings/filters.
  53  
  54  - Upload does not work in Opera
  55  Jquery form plugin before version 2.09 has problems with Opera 9.2+. Replace Drupal's misc/jquery.form.js with the one at http://jquery.malsup.com/form/#download
  56  
  57  - IMCE may have problem working with Google Analytics and Secure pages modules. Just make sure to add *imce* path to the exceptions list of these modules.
  58  
  59  
  60  INTEGRATION METHODS
  61  -----------
  62  
  63  Here are the applications that already integrated IMCE.
  64  
  65  WYSIWYG:
  66  Install http://drupal.org/project/imce_wysiwyg bridge module and enable IMCE as a plug-in in WYSIWYG settings
  67  
  68  BUEditor:
  69  IMCE is integrated in image and link dialogs.
  70  
  71  (F)CKeditor(without WYSIWYG): 
  72  (F)ckeditor profile->File browser settings->IMCE integration
  73  
  74  If your application is not one of the above, please keep reading in order to learn how to integrate IMCE.
  75  
  76  Let's create a CASE and embody the IMCE integration on it:
  77  - An application named myApp
  78  - Has an url field for file url:
  79    <input type="text" name="urlField" id="urlField">
  80  - Has a browse button with click event(inline or set by jQuery): (This can be a text link or anything that is clickable)
  81    <input type="button" value="Browse" onclick="openFileBrowser()">
  82    
  83  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.
  84  
  85  
  86  INTEGRATION BY URL
  87  -----------
  88  When IMCE is opened using an url that contains &app=applicationName|fileProperty1@FieldId1|fileProperty2@FieldId2|...
  89  the specified fields are filled with the specified properties of the selected file.
  90  
  91  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.)
  92  
  93  In our CASE, we should open IMCE using this URL: /imce?app=myApp|url@urlField which contains our application name and our url field id
  94  
  95  function openFileBrowser() {
  96    window.open('/imce?app=myApp|url@urlField', '', 'width=760,height=560,resizable=1');
  97  }
  98  
  99  That's all we need. Leave the rest to IMCE.
 100  It will automatically create an operation tab named "Send to myApp" that sends the file url to our url field.
 101  Clicking the files in preview do the same thing as well.
 102  
 103  - What if we had another field for another file property e.g, Size: <input type="text" id="file-size"> ?
 104  - We should have opened imce using this URL: /imce?app=myApp|url@urlField|size@file-size
 105  
 106  
 107  - USING imceload:
 108  You can point a predefined function to be executed when IMCE loads.
 109  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.
 110  function myOnloadFunc (win) {//any method of imce is available through win.imce
 111    win.imce.setSendTo('Give it to myApplication baby', myFileHandler);//you should also define myFileHandler
 112  }
 113  
 114  - USING sendto:
 115  You can point a predefined function to which the selected files are sent.
 116  When the URL is like "app=myApp|sendto@myFileHandler", IMCE calls "myFileHandler" function of the parent window with file and window parameters.
 117  function myFileHandler (file, win) {
 118    $('#urlFieldId').val(file.url);//insert file url into the url field
 119    win.close();//close IMCE
 120  }
 121  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.
 122  
 123  
 124  ADVANCED INTEGRATION
 125  -----------
 126  In case:
 127  - Your application wants to go beyond the simple "give me that file property" interaction with IMCE.
 128  - Your application wants IMCE to send multiple files to it.(e.g., a gallery application)
 129  - Your application wants to gain total control over IMCE.
 130  Then you should consider applying advanced integration.
 131  
 132  The initial step of advanced integration is the same as imceload-integration above.
 133  
 134  We open IMCE and set its onload function:
 135  
 136  window.open('/imce?app=myApp|imceload@initiateMyApp', '', 'width=760,height=560,resizable=1'); //initiateMyApp(win) will run when imce loads
 137  
 138  Now we define our initiator function in which we do the necessary manipulations to IMCE interface:
 139  
 140  initiateMyApp = function (win) {
 141    var imce = win.imce;
 142    ...use imce methods to add/remove/change things...
 143  }
 144  
 145  - Allright, but what do we add/romeve/change in IMCE ?
 146  - Depends on our goal. Here are some properties and methods that can help us to achieve it:
 147  
 148  Hooks
 149  imce.hooks.load: an array of functions that run after imce loads. they are called with the window parameter.
 150  imce.hooks.list: an array of functions that run while processing the file list. each row of the file list is sent to these functions.
 151  imce.hooks.navigate: an array of functions that run after a directory is loaded. parameters sent are data(from ajax or cache), old_directory, cached(boolean that states the data is from the cache or not).
 152  imce.hooks.cache: an array of functions that run just before a new directory is loaded. parameters are cached_data and new_directory.
 153  
 154  Directory related properties
 155  imce.tree: stores the directory list where imce.tree['.'] is the root element.
 156  
 157  Directory related methods
 158  imce.dirAdd(directory_name, parent_element, clickable): adds directory_name under parent_element. ex: imce.dirAdd('foo', imce.dir['.'], true)
 159  imce.dirSubdirs(directory_name, subdirectories): adds each subdirectory in subdirectories array under directory_name. ex: imce.dirSubdirs('foo', ['bar', 'baz'])
 160  
 161  File related properties
 162  imce.findex: indexed array of files(table rows that contain file properties.)
 163  imce.fids: object containing file_id(file name)-file(row) pairs.
 164  imce.selected: object containing currently selected file_id(file name)-file(row) pairs.
 165  
 166  File related methods
 167  imce.fileAdd(file): adds the file object to the list. file object has the properties; name, size(bytes), width, height, date(timestamp), fsize(formatted), fdate(formatted)
 168  imce.fileRemove(fiile_id): removes the file having the file_id from the list.
 169  imce.fileGet(file_id). returns the file object having the file_id. file object contains name, url, size, bytes, width, height, date, time, id(file id for newly uploaded files, 0 or integer), relpath(rawurlencoded path relative to file directory path.)
 170  
 171  File operations
 172  imce.opAdd(op): adds an operation tab to the interface. op contains name, title, content(optional), func(optional onclick function)
 173  imce.opEnable(name), imce.opDisable(name): enable/disable operation tabs.
 174  
 175  Miscellaneous
 176  imce.setMessage(msg, type): logs a message of the type(status, warning, error)
 177  
 178  NOTES:
 179  - All URL strings in the examples start with "/" considering the base path is "/".
 180  In case your drupal is running on a sub directory e.g, http://localhost/drupal, these URLs should start with "/drupal/".
 181  There is a safer solution that does not require manual URL fixing: If the Drupal javascript object is avaliable in your page you can use Drupal.settings.basePath at the beginning of URLs (Drupal.settings.basePath+'?q=imce....'). Note that, this won't work with multilingual paths with language prefixes.
 182  - file and directory ids(names) used in imce.js are url encoded forms of original names. They are decoded using imce.decode and displayed in the lists.