|
1 // $Id: README.txt,v 1.11.2.6 2009/02/21 00:03:15 ufku Exp $ |
|
2 |
|
3 IMCE is an image/file uploader and browser that supports personal directories and quota. |
|
4 IMCE can easily be integrated into any WYSIWYG editor or any web application that needs a file browser. |
|
5 See INTEGRATION METHODS for more information. |
|
6 |
|
7 ~~~~~~~~~~~FEATURES~~~~~~~~~~~ |
|
8 |
|
9 -Basic file operations: upload, delete |
|
10 - Image(jpg, png, gif) operations: resize, create thumbnails, preview |
|
11 - Support for private downloads. |
|
12 - Configurable limits for user roles: file size per upload, total directory size(quota), file extensions, and image dimensions. |
|
13 - Personal or shared folders for users. |
|
14 - User-friendly interface: directory and file listing, file sorting(by name, size, dimensions, date), selecting, preview, keyboard shortcuts(up, down, insert(or enter), delete). |
|
15 - Built-in support for inline image/file insertion into textareas. |
|
16 New in 6.x: |
|
17 - Improved UI: |
|
18 - Tabbed interface for file operations. |
|
19 - Resizable workspaces. |
|
20 - Ftp-like directory navigation. |
|
21 - Log messages. |
|
22 - Additional keyboard shortcuts: home, end, ctrl+A, R(esize), T(humbnails), U(pload) |
|
23 - Multiple file selection(using ctrl or shift). |
|
24 - Ajax file operations. |
|
25 - Operate on multiple files at a time. |
|
26 - Directory caching. |
|
27 - Themable layout using tpl files. |
|
28 - Improved configuration profiles. |
|
29 - Multiple personal or shared directory assignments for users. |
|
30 - Permissions per directory. |
|
31 - Option to use total user quota together with the directory quota. |
|
32 - Replace method options for existing files. |
|
33 - Multiple thumbnail definitions. |
|
34 - New integration API for wysiwyg editors. |
|
35 |
|
36 |
|
37 ~~~~~~~~~~INSTALLATION~~~~~~~~~~~ |
|
38 |
|
39 1) Copy imce directory to your modules directory |
|
40 2) Enable the module at: /admin/build/modules |
|
41 3) Create configuration profiles and assign them to user roles at: /admin/settings/imce |
|
42 4) Test it at: /user/USER-ID/imce or /imce. |
|
43 5) See INTEGRATION METHODS to make IMCE collaborate with your application if it's not already integrated. |
|
44 Notes: |
|
45 - When you configure IMCE for inline image/file insertion into textareas there should appear an IMCE link under each textarea you specified. |
|
46 - 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 |
|
47 - If you are using CCK, you may want to check the Imce CCK Image module at http://drupal.org/project/imceimage |
|
48 |
|
49 |
|
50 ~~~~~~FREQUENTLY FACED ISSUES~~~~~~ |
|
51 |
|
52 - Inaccessible/invalid directory or subdirectory: |
|
53 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. |
|
54 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". |
|
55 And also if "safe mode restriction" is active in your server, don't expect IMCE to run flawlessly. |
|
56 |
|
57 - Disappearing images after node submission: |
|
58 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. |
|
59 |
|
60 - No browse button in IE/FF/at all: |
|
61 Probably talking about tinyMCE or FCKeditor. See INTEGRATION METHODS to learn to integrate it by yourself. |
|
62 |
|
63 - Upload does not work in Opera |
|
64 Jquery form plugin before version 2.09 has problems with Opera 9.2+. Replace Drupal's misc/jquery.form.js with http://jqueryjs.googlecode.com/svn/trunk/plugins/form/jquery.form.js |
|
65 |
|
66 - 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. |
|
67 |
|
68 ~~~~~~~INTEGRATION METHODS~~~~~~~ |
|
69 |
|
70 Here are the applications whose users are lucky that they don't have to read the details of integration methods. |
|
71 |
|
72 BUEditor: Obviously, the author knows how to integrate IMCE to his application:). Users need nothing to do. |
|
73 |
|
74 FCKeditor: Another module from another blessed author, which makes IMCE integration as simple as a single click. Fckeditor profile->File browser settings->IMCE integration |
|
75 Note: One can also override the settings at advanced settings->custom javascript configuration. |
|
76 Here are the lines that force imce integration (don't force unless you need to): |
|
77 LinkBrowser= true; |
|
78 ImageBrowser= true; |
|
79 FlashBrowser= true; |
|
80 LinkBrowserURL= '/?q=imce&app=FCKEditor|url@txtUrl'; |
|
81 ImageBrowserURL= '/?q=imce&app=FCKEditor|url@txtUrl|width@txtWidth|height@txtHeight'; |
|
82 FlashBrowserURL= '/?q=imce&app=FCKEditor|url@txtUrl'; |
|
83 |
|
84 TinyMCE: See http://drupal.org/node/241753#comment-792305 |
|
85 |
|
86 There may be other applications that integrated IMCE already. If your application is not one of them, please keep reading. |
|
87 |
|
88 |
|
89 Let's create a CASE and embody the IMCE integration on it: |
|
90 - An application named myApp |
|
91 - Has an url field for file url: |
|
92 <input type="text" name="urlField" id="urlField"> |
|
93 - Has a browse button with click event: (This can be a text link or anything that is clickable) |
|
94 <input type="button" value="Browse" onclick="openFileBrowser()"> |
|
95 |
|
96 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. |
|
97 |
|
98 |
|
99 ~~~~~~~~INTEGRATION BY URL~~~~~~~ |
|
100 |
|
101 When IMCE is opened using an url that contains &app=applicationName|fileProperty1@FieldId1|fileProperty2@FieldId2|... |
|
102 the specified fields are filled with the specified properties of the selected file. |
|
103 |
|
104 Avaliable file properties are: url, name, size(formatted), width, height, date(formatted), bytes(integer size in bytes), time(integer date timestamp) |
|
105 |
|
106 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 |
|
107 |
|
108 function openFileBrowser() { |
|
109 window.open('/?q=imce&app=myApp|url@urlField', '', 'width=760,height=560,resizable=1'); |
|
110 } |
|
111 |
|
112 That's all we need. Leave the rest to IMCE. |
|
113 It will automatically create an operation tab named "Send to myApp" that sends the file url to our url field. |
|
114 Clicking the files in preview do the same thing as well. |
|
115 |
|
116 - What if we had another field for another file property e.g, Size: <input type="text" id="file-size"> ? |
|
117 - We should have opened imce using this URL: /?q=imce&app=myApp|url@urlField|size@file-size |
|
118 |
|
119 IMCE 6.x-1.2 brought two other special properties(onload and sendto) allowing more flexibility. |
|
120 - onload: |
|
121 You can point a predefined function to be executed when IMCE loads. |
|
122 When the URL is like ...&app=myApp|onload@myOnloadFunc, IMCE looks for myOnloadFunc in the parent window and executes it with the window parameter referring to IMCE window. |
|
123 function myOnloadFunc (win) {//any method of imce is available through win.imce |
|
124 win.imce.setSendTo('Give it to myApplication baby', myFileHandler);//you should also define myFileHandler |
|
125 } |
|
126 - sendto: |
|
127 You can point a predefined function to which the selected files are sent. |
|
128 When the URL is like ...&app=myApp|sendto@myFileHandler, IMCE calls myFileHandler function of the parent window with file and window parameters. |
|
129 function myFileHandler (file, win) { |
|
130 $('#urlFieldId').val(file.url);//insert file url into the url field |
|
131 win.close();//close IMCE |
|
132 } |
|
133 Usually sendto method is easier to implement, on the other hand onload method is more flexible as you manually add your sento operator and also can do any modification before IMCE shows up. |
|
134 |
|
135 |
|
136 ~~~~~~INTEGRATION BY ONLOAD~~~~~~ |
|
137 |
|
138 A more flexible method that gives a finer control over IMCE. |
|
139 Note: This could be extended to alter the content or the interface of IMCE by using its javascript methods. |
|
140 |
|
141 var imcePopup;// this is our global variable referring to IMCE window. We use it for tracking its open/closed state |
|
142 |
|
143 function openFileBrowser() { |
|
144 |
|
145 // if IMCE is closed or not opened yet. |
|
146 if (typeof imcePopup == 'undefined' || imcePopup.closed) { |
|
147 |
|
148 //open IMCE |
|
149 imcePopup = window.open('/?q=imce', '', 'width=760,height=560,resizable=1'); |
|
150 |
|
151 //we create a function that runs when IMCE loads, by setting the imceOnLoad property of the window |
|
152 //It is automatically called by IMCE with a single parameter(win) referring to IMCE window. |
|
153 //We can access all methods of IMCE using win.imce |
|
154 imcePopup['imceOnLoad'] = function (win) { |
|
155 //we use IMCE's setSendTo method to make a selected file sent to our imceFinish function |
|
156 //setSendTo(title, function) creates an operation tab that has the "title" and runs the "function" on click. |
|
157 win.imce.setSendTo('Give it to myApplication baby', imceFinish); |
|
158 } |
|
159 } |
|
160 |
|
161 //knowing the popup is opened, we bring it into view. |
|
162 imcePopup.focus(); |
|
163 } |
|
164 |
|
165 //Finalizing function that is executed when the user selects a file for our application. |
|
166 //This function is called with two parameters. |
|
167 //file is the file object having the properties: url, name, size, width, height, date, bytes, time |
|
168 //win is the reference to IMCE window. We can access all IMCE methods using win.imce |
|
169 function imceFinish(file, win) { |
|
170 //We set the value of our url field using file.url |
|
171 document.getElementById('urlField').value = file.url |
|
172 //hide the popup. We don't close it in order to save time for later use. |
|
173 win.blur(); |
|
174 } |
|
175 |
|
176 |
|
177 ~~~~~~~ADVANCED INTEGRATION~~~~~~~~~ |
|
178 |
|
179 In case: |
|
180 - Your application wants to go beyond the simple "give me that file property" interaction with IMCE. |
|
181 - Your application wants IMCE to send multiple files to it.(e.g., a gallery application) |
|
182 - Your application wants to gain total control over IMCE. |
|
183 Then you should consider applying advanced integration. |
|
184 |
|
185 The initial step of advanced integration is the same as onload-integration above. |
|
186 |
|
187 We open IMCE and set its imceOnLoad function: |
|
188 |
|
189 imcePopup = window.open('/?q=imce', '', 'width=760,height=560,resizable=1'); |
|
190 imcePopup['imceOnLoad'] = initiateMyApp;//initiateMyApp(win) will run when imce loads |
|
191 |
|
192 Now we define our initiator function in which we do the necessary manipulations to IMCE interface: |
|
193 |
|
194 initiateMyApp = function (win) { |
|
195 var imce = win.imce; |
|
196 ...use imce methods to add/remove/change things... |
|
197 } |
|
198 |
|
199 - Allright, but what do we add/romeve/change in IMCE ? |
|
200 - Depends on our goal. Here are some properties and methods that can help us to achieve it: |
|
201 |
|
202 Hooks |
|
203 imce.hooks.load: an array of functions that run after imce loads. they are called with the window parameter. |
|
204 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. |
|
205 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). |
|
206 imce.hooks.cache: an array of functions that run just before a new directory is loaded. parameters are cached_data and new_directory. |
|
207 |
|
208 Directory related properties |
|
209 imce.tree: stores the directory list where imce.tree['.'] is the root element. |
|
210 |
|
211 Directory related methods |
|
212 imce.dirAdd(directory_name, parent_element, clickable): adds directory_name under parent_element. ex: imce.dirAdd('foo', imce.dir['.'], true) |
|
213 imce.dirSubdirs(directory_name, subdirectories): adds each subdirectory in subdirectories array under directory_name. ex: imce.dirSubdirs('foo', ['bar', 'baz']) |
|
214 |
|
215 File related properties |
|
216 imce.findex: indexed array of files(table rows that contain file properties.) |
|
217 imce.fids: object containing file_id(file name)-file(row) pairs. |
|
218 imce.selected: object containing currently selected file_id(file name)-file(row) pairs. |
|
219 |
|
220 File related methods |
|
221 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) |
|
222 imce.fileRemove(fiile_id): removes the file having the file_id from the list. |
|
223 imce.fileGet(file_id). returns the file object having the file_id. file object contains name, url, size, bytes, width, height, date, timestamp |
|
224 |
|
225 File operations |
|
226 imce.opAdd(op): adds an operation tab to the interface. op contains name, title, content(optional), func(optional onclick function) |
|
227 imce.opEnable(name), imce.opDisable(name): enable/disable operation tabs. |
|
228 |
|
229 Miscellaneous |
|
230 imce.setMessage(msg, type): logs a message of the type(status, warning, error) |
|
231 |
|
232 NOTE: |
|
233 - All URL strings in the examples start with "/" considering the base path is "/". |
|
234 In case your drupal is running on a sub directory e.g, http://localhost/drupal, these URLs should start with "/drupal/". |
|
235 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....') |
|
236 - 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. |