imgupload – Design, Configuration, and Installation

imgupload is a tinyMCE plugin which adds file upload to the list of choices available to a tinyMCE editor instance. It was written in compliance with tinyMCE 3.3.5.1 – as I understand them, using www.tinymce.com documentation, reverse engineering, and trial and error.

imgupload will work both with jQuery and without. It automatically detects the presence of jQuery and will work with either the tinyMCE jQuery plugin or using plain, vanilla tinyMCE.

This plugin was developed in the ‘approved manner’: by copying the plugin called example and hacking it up. Much of the code follows example very closely except that is handles installations with and w/o jQuery and does a lot of event handling and form rewriting to create a ‘better user experience’. Aside from that and a bunch of CSS, they are almost identical.

Licensing

Licensed under the Lesser GNU Public License, version 3. See LGPL-3.txt for details.

WARNING: USING THIS CODE IS INHERENTLY DANGEROUS BECAUSE IT ALLOWS USERS TO UPLOAD FILES TO YOUR SERVER. IT HAS NO MEANINGFUL SECURITY. USE AT YOUR OWN RISK.

THIS SOFTWARE IS MADE AVAILABLE WITHOUT WARRANTY. USE AT YOUR OWN RISK.

The following warranty disclaimer and limitation of liability are ‘borrowed’ from the copying provisions from GNU Emacs and EXPLICITLY apply to this code:

Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Menu:

• File Structure
• Function
• Configuration
• Client Code
• Server Code

Secruity Issues

While it is possible to modify this code to make it relatively secure in specific instances, this is not possible for a general distribution. This is because authentication, authorization, and file de-lousing are beyond the scope of this project.

Here are some suggestions which could be implemented in order to reduce the risk of allowing users to upload files. Risk cannot be completely eliminated.

As always, either consult a security expert or become one yourself before trying any of these.

1. limit use of the utility to humans. The issue here is to avoid denial of service attacks by Internet robots, scanners, etc. There are many techniques which have been used to do this – with different levels of effectiveness.
2. implement a system of identifying users – such as user accounts. This also has its problems in safeguarding user id’s, passwords, pass phrases, host keys, etc. Again, there are many known techniques for doing so – again with varying levels of effectiveness and risk.
3. implement a system for securely authenticating users – such as a carefully designed login method and session control
4. secure and segregate uploaded files
5. take steps to make sure all uploaded files are not executable. Some simple steps include removing execute permission from uploaded files or possibly mangling them using some encryption technology so that they cannot be executed as they reside on the server.
6. implement stringent tests of the file content to ensure that the uploaded files contain acceptable content.

In other words: USE AT YOUR OWN RISK. and I’M NOT RESPONSIBLE OR LIABLE FOR ANYTHING THAT HAPPENS.

File Structure

The plugin follows the required tinyMCE plugin structure:

imgupload/ - (root directory for plugin - the name is signficant)
     /dialog.htm - the html for the popup form
     /editor_plugin.js - the javascript which initializes the plugin - compressed
     /editor_plugin_src.js - development version of initialization plugin - source of editor_plugin.js
     /upload-file.php - PHP script which handles server side of file upload
     /Spec.textile - this document in Textile format

/css/ – (directory for plugin css)
     /css/imgupload.css – css for plugin

/img/ – (directory for images used by plugin)
     /img/buttons.png – local copy of the button background sprite
     /img/icon.gif – button icon which activates the plugin – derived from the image icon source
     /img/icon.psd – photoshop source for icon.gif

/js/ – (javascript directory)
     /js/dialog.js – javascript which initializes popup and handles popup events

/langs/ – (language pack directory – add translations here)
     /langs/en.js – plugin initialization language phrases – US English
     /langs/en_dlg.js _ popup language phrases – US English

/Slides/ – directory for presentation slides
     /Slides/tinyMCE-jQuery-plugin.ai – Adobe Illustrator version of slides explaining the plugin design

Function

This plugin allows a user to upload a file to a server from within a tinyMCE editor.

To clarify, tinyMCE is not a single editor, but it is a Javascript application which can create as many editors as desired for a given web page – where each separate editor provides rich text editing of a specific page element – typically a <textarea> element.

All the editors are created when tinyMCE is initialized upon page load.

It is not clear when the plugin is initialized, but it likely happens upon editor creation – for each editor. See the tinyMCE website for detailed information.

Each plugin instance manages a popup window. The popup windows are initialized when the user generates an event by clicking the button bound to the plugin and execute in their own window context. This necessitates passing some parameters to the popup initialization routine from the plugin initialization logic.

Once initialized, this popup is completely event driven.

Configuration

Configuration is takes place in three places:

• in the tinyMCE editor configuration when loading tinyMCE
• in the client code – specifically the event service routine dialog.js
• in the server side code – specifically seriously hacking the model upload server side utility: upload-file.php

tinyMCE Configuration

1. Parameters – imgupload takes no parameters
2. plugins list – add ‘imgupload’ to the list
3. theme_advanced_buttons? : add ‘imgupload’ to the list you want the button icon to appear in

Here is a sample snip from the tinyMCE configuration object:

  . . .

plugins: ’...,imgupload’,
   . . .
   theme_advanced_buttons2: ’...,anchor,image,imgupload,...’;
   . . .

client code – dialog.js

Locate the lines contaning ‘upload-file.php’ and change them to the URL for your specific server side code. There are two places and both are commented

server code

See server configuration below.

Client Side

Plugin Initialization

The plugin is initialized by running ‘editor_plugin.js’ – or ‘editor_plugin_src.js’, which is the development version of ‘editor_plugin.js’.

editor_plugin_src.js is responsible for:

• loading the correct language pack – which, for US English, is imageupload/langs/en.js. (see below)
• creating the plugin – by calling _tinymce.create(). (see below)
• adding the plugin to the PluginManager by calling tinymce.PluginManager.add()

Note on Language Packs

Loading a language pack seems to do two things:

1. determines the language being used by the user and looks it up in /langs/ using the standard two character language identifiers (e.g. en for US English)
2. creates a Javascript object named imgupload which has all the attributes.

If you look at /langs/en.js and /langs/en_dlg.js, you will see that those files actually create objects which are fields of the en object and the names of the language packs are the field names they define.

Creating the plugin

The result of creating the plugin consists of an identifier and a Javascript object.

The identifier is the string ‘tinymce.plugins.ImgUploadPlugin’

The Javascript object contains three functions:

• init(ed, url) – which initializes the editor
  • ed – is the editor we are initializing the plugin for
  • url – is the URL to the plugin root directory. Thus url + ‘dialog.htm’ is the path to the popup window HTML
• createControl(n, cm) – is a NOP in this case. See the code and tinymce doc for information
• getInfo() – returns some information about the plugin

Departures from Vanilla example plugin

tinymce.plugins.ImgUploadPlugin.init() creates a variable called jQuery which it passes to the plugin. This is done by checking to see if window.jQuery is defined or not. If not, the jQuery is set to null, otherwise to window.jQuery. This value is used in creating the closure passed to ed.addCommand(); this function is called every time the plugin popup window is openned.

This is necessary because the popup window runs in a context which does not contain the jQuery object.

Popup

Once everything is set up, all the action happens in the Popup.

The popup consists of three main pieces and some ancillary stuff:

• Main Pieces
  • dialog.htm – which defines the visible popup content and interaction with user
  • js/dialog.js – which initializes the popup – every time invoked – and handles all events while the popup exists.
  • upload-file.php – the server code which makes the thing actually work – on the server. (see below) for details.
• Ancillary Stuff
  • langs/en_dlg.js – popup dialog entries. Only US English is provided. Feel free to translate.
  • css/imgupload.css – controls the styling of the popup. Colors are managed by classes; everything else by id’s
  • img/stuff – a button background image and the button icon

Popup HTML

dialog.htm is a straight forward form with a couple of buttons. The only interesting departure is that the output of the form targets an iframe contained in dialog.htm rather than the user visible output.

This is the AJAX-ish hack which allows us to display an animation during the file upload and to process the upload results in the client rather than on the server. This allows the plugin to be retargeted to other languages.

Popup Javascript

dialog.js does three things:

• loads the appropriate language pack – this defines phrases identified as imgupload_dlg.title and similarly. See the dialog language pack: /langs/en_dlg.js for the implementation.
• creates an Javascript objected called ImgUploadDialog (see below)
• adds the name of this object and a call to it’s initialization method to tinyMCEPopup.

Popup Dialog Object

The popup dialog object ImgUploadDialog contains these attributes:

• Data Attributes:
  • jQuery_obj – set to the value passed in from editor_plugin.js.
  • popup_url – the URL required to get to the root directory of the popup. This is supplied by editor_plugin.js
  • frm_elts – an internal dictionary of popup element objects. This is used to avoid repeated DOM searches.
• Event Handler Methods:
  • init – function which is called each time the popup pops up. This where all initialization happens
  • upload_file_change – triggered by the onchange event for the file input field
  • dest_fname_change – triggered by the onchange event for the destination file name field.
  • upload – function which is fired by the popup form submit event or clicking the Upload / Replace button
  • upload_finished – function which processes the results of the upload. The result of the upload is loaded into the iframe, so this function actually services the onload event for the iframe
  • user_finished – closes the popup when the user is finished reading the display – signaled by clicking the close button.
• Internal Method:
  • test_on_server() – runs the server code in test mode via an AJAX call. Called by dest_fname_change() and upload_file_change(). It manages all the updates to the popup window display prior to the actual upload.

Each event handler is responsible for binding and unbinding events and modifying the popup window as is appropriate.

All of the methods have code which runs with and without jQuery. These two halves do the identical processing – within normal bugginess parameters.

In more detail:

init()

Initializes the frm_elts dictionary. Hides all parts of the form except for upload file selection and Cancel button. Writes a nice message requesting the user to select a file.

Sets up upload_file_change() to run when the upload file is defined

upload_file_change()

Copies the upload file name to the destination file field and runs test_on_server()

If the selected file is legal, then the destination file name and the Upload / Replace button are made visible. A message is written either saying the file can be uploaded or a warning that uploading now will replace it.

Focus is transferred to the destination file field.

dest_fname_change() is set to respond to a change in destination file name

upload() is set to respond to clicking the Upload / Replace button or a submit of the form.

If the selected file is not legal, then dest_fname_change() and upload() are blocked from firing, a warning message is written, and focus goes to the upload_file field

dest_fname_change()

Runs test_on_server().

This results in exactly the same final condition as detailed in upload_file_change() at the end of the previous paragraph.

upload()

Removes the upload_file and destination_file fields from the form.

Removes event handlers for the form and upload_file and destination file fields.

Writes an ‘Uploading…’ message.

Removes and disables the Upload/Replace and Cancel buttons

Sets upload_finished() to run when the iframe receives the output of file-upload.php

Submits the form to file-upload.php on the server.

{background:red}. FIXME: need to add a timeout to this thing so it will detect a hung server process

upload_finished()

Unwires all event handlers.

Sets up user_finished() to run when the Close button is clicked (same button as is used to run upload(), but with different skin).

Copies contents of iframe to message area of popup

user_finished()

Closes the popup window.

test_on_server()

This does the bulk of the work. It sends a Synchronous AJAX request to run upload-file.php and processes the result.

If the result is a success, then it sets up the form to either modify the destination file name, do the upload, or cancel out.

If the result is a failure, then it writes a message and disables upload and modification of the destination file name.

Server Code

The server code supplied is the single file: upload-file.php.

It operates in two mode – specified by the imgupload_command POST variable:

In addition to imgupload_command, upload-file.php requires two more POST variables defined: imgupload_upload_file and imgupload_dest_fname.

• imgupload_upload_file – defines the file which will be uploaded. It be either a POST or a FILES variable, depending on mode.
• imgupload_dest_fname – is the name the uploaded file will have on the server

There are two significant variables which determine where the file will be dropped and what files may be uploaded. These are $dest_dir and $legal_exts.

Here is a more detailed description:

• Upload Mode
  • imgupload_upload_file – key into $_FILES array for the uploaded file
  • imgupload_dest_fname – name of destination file taken from the $_POST array
  • $dest_dir – string – set inside the server side code – absolute path to destination directory for uploads.
  • $legal_exts – string – set inside the server side code – containing a comma separated list of file extents which are allowed to be uploaded OR NULL – in which case all file types are allowed. It is assumed that the file extents actually mean something. A file extent is a file suffix which is attached to the filename using a period (.). Thus, don’t put the periods in the list. For example: ‘jpg,gif,png’
• Test Mode
  • imgupload_upload_file – key into $_POST array specifying the file name. This can be an entire path, but only the basename is used. This used to determine the correct file extension for the destination file
  • imgupload_dest_fname – key into $_POST array specifying the destination file name. The extension may or may not be present. If absent, then it is derived from the upload file name.
  • $legal_exts – see above
  • $dest_dir – see above

Configuration

Configuration requires hacking the upload utility. Read the comments in the supplied sample command: upload-file.php.

Three things need to be done:

First, the two parameters listed at the top of the script must be specicalized for your application.

Second, you SHOULD add some sort of security. The supplied command is insecure. Aside from the rudimentary test of the file name extension, anything can be loaded into the file reception directory. This is a very, very bad idea.

Finally, the server code needs to be someplace where the plugin can find it. As written, it expects to find the upload utility in the same directory the plugin lives in -

Variables which need to be set:

• $dest_dir – is the absolute path to the file upload directory on the server. NOTE: uploading to subdirectories of dest_dir is NOT supported at this time.
• $legal_exts – is a regular expression created by the plugin which defines file types which may be uploaded. This is derived from the imgupload_legal_exts tinyMCE option string. See above

Upload Command

Uploads the file specified in $_FILES[‘upload_file’].

After doing various tests and resolving the upload file name, this returns HTML which is dumped into the form target iframe. This is directly human readable and needs no translation.

I decided to not use a JSON or XML response because (at least my current version of) Firefox (and other browsers) balk when receiving data of type application/json or application/xml and ask what to do. It seems simpler, faster, and generally better to pass the result directly to the user than to ask them what do do with the data and then reformat the result and ask them what to do.

Test Command

After performing pretty much the same tests and file name resolution, this returns a JSON structure. Naturally this is designed to be an AJAX call and is used to control the user experience – warning when the file may be overwritten, etc – prior to doing the upload.

The returned JSON object has the following keys:

• result – either ‘success’ or ‘failure’
• result_code – key into imgupload_dlg object
• explanation – untranslated text or codes expanding on failure
• upload_file – client name of uploaded file – not translated
• dest_fname – server name of uploaded file – not translated