Creative Juices Bo. Co.

Satisfy Your Thirst For Something Refreshing!

CJ File Browser 3.1

CJ File Browser File and Image Manager

Project Description

CJ File Browser is a file management system to allow you to view and modify a server's directory contents through the use of a web browser. It can be implemented as a plug-in with tinyMCE or work separately in standalone mode. With it you will be able to upload any file type (including images) as well as a limited ability to modify directories. Some of the actions you can perform are: upload files, delete files, navigate directories, create directories, delete directories and if the file is a supported web image (GIF, JPG or PNG) you will be able to see a small preview of the image.

CJ File Browser with all interface options turned on
CJ File Browser with all interface options turned on. (Demo does not)

The main interface is completely written using standard HTML and JavaScript. There is no Flash or Shockwave used! The actions the interface needs to perform are handed off to a Handler Engine System using AJAX calls. This allowed us to create a plug-in architecture to allow the use of multiple server technology. If the a Handler Engine Plug-In is not available for your particular language, then you can create your own by following the [blog:guide-to-creating-your-own-cj-file-browser-handler-engine-plug-in]CJ File Browser 3.1 Custom Engine Guide[/blog] on my blog.

Current Available Handler Engine System Plug-Ins

Handler EngineDate ModifiedAuthor
ColdFusion8April 10, 2010Doug Jones

* Since this is the initial release, ColdFusion 8 is the only handler available at this time. I plan on writing a PHP Handler Engine as soon as I have some time.

 

Security

Another great feature of CJ File Browser is its built in security architecture. Introduced in version 3.0, the file browser incorporates a technique to prevent unwanted directory and file access. Located in the root of the main file browser folder, there's a file called security.xml. This has been expanded for version 3.1 and now contains a master list of authorized actions, directories and file types. The Handler Engine System will assume that any call to perform an action from the JavaScript interface is an untrusted call. In order to continue with the action, it validates that it is authorized to do so. Out of the box, the security settings are set to allow any action, directory access from web root and allow any file type. Any settings you pass to it from the tinyMCE or standalone setup script will be trusted an allowed. If you plan on deploying CJ File Browser in an untrusted environment, then it is suggested that you adjust these settings.

Security.xml File Listing

<?xml version="1.0" encoding="UTF-8"?>
<cjFileBrowser version="3.1">
   <actionsAllowed>
      <action>navigateDirectory</action>
      <action>createDirectory</action>
      <action>deleteDirectory</action>
      <action>fileDelete</action>
      <action>fileUpload</action>
      <action>fileSelect</action>
      <action>filePreviews</action>
   </actionsAllowed>
   <directoriesAllowed>
      <directory>/</directory>
   </directoriesAllowed>
   <fileExtsAllowed>
      <fileExt>*</fileExt>
   </fileExtsAllowed>
</cjFileBrowser>

The security settings are broken down into three sections:

<actionsAllowed>

Authorized actions are anything that the user needs to do to. Removing any of the following will prevent those actions from occurring. By default all the actions are present. (Removing items from the security file does not affect the user interface.)

  • navigateDirectory - Any action that reads a directory. By default if this action is present, CJ File Browser will allow users to traverse any of the listed directories and any directories within it. By removing this action, then , will not allow this. (Currently there is no option to allow a user to jump from one directory listing to another, they can only traverse the directory that they initiated in.)
  • createDirectory - Allows users to create directories.
  • deleteDirectory - Allows users to delete directories. (This action is recursive, so it will delete any directory and all of its contents as well)
  • fileDelete - Allows users to delete files.
  • fileUpload - Allows users to upload files.
  • fileSelect - Allows users to select a file. (Only useful in standalone mode)
  • filePreviews - Allows users to use view image thumbnail previews. (Removing this item may help with server load, if thats a problem)

<directoriesAllowed>

The directories allowed are relative paths (from web root) to any directories that you wish the user to use. In normal environments, you will most likely only have one entry. In special cases, say a server with multiple tinyMCE or standalone deployments, you may have additional entries. By default web root "/" is enabled. This entry cannot be blank. As of this writing, I have not tested if using relative paths like "../../myfolder/" work. I would highly suggest making sure all paths are relative from web root!

You can add as many <directory> nodes as needed, but as of this time the plug-in is only setup to handle one directory per tinyMCE or standalone instance. If you decide to have more than one CJ File Browser implemented on your site, you can provide all the authorized directories here and each instance will use this file to validate your paths.

<fileExtsAllowed>

The file extensions allowed needs to be a comma separated list of allowed file formats, if all file types are allowed, then you must provide "*". This entry cannot be blank. These file type are used for reading as well as uploading, so for example you provide "gif,jpg" those are going to be the only files the browser displays and the only file types the user can upload.

One More Thing to Keep In Mind

The only other thing you really need to know is that security settings also get passed when initiating the file browser (whether from tinyMCE or the standalone script). Those settings will be overridden by what's in this file. Also, the settings will not affect the user interface, this is controlled from the initialization script as well. (i.e. if you remove fileUpload, the file upload button will still be in the interface unless you remove that option from the init script.

How To Use With TinyMCE

Download the files and place the cjFileBrowser folder inside the tinyMCE plug-ins folder. All the settings are passed to the plug-in via the tinyMCE initialization script. Please keep in mind, that your security.xml file will override any of these settings. Once you've installed the plug-in, you are going to need to initialize some variables. This is a typical tinyMCE initializations script.

tinyMCE.init({
    mode : "exact",
    theme : "advanced",
    width: 600,
    plugins : "table,save,contextmenu,paste,noneditable,cjfilebrowser",
    theme_advanced_toolbar_location : "top",
    theme_advanced_toolbar_align : "left",
    theme_advanced_path_location : "bottom",
    theme_advanced_buttons1 : "bold,italic,|,undo,redo,|,link,unlink,anchor,image",
    theme_advanced_buttons2 : "",
    theme_advanced_buttons3 : "",
    plugin_cjfilebrowser_browseUrl : "<RELATIVE_PATH_TO_TINYMCE>plugins/cjfilebrowser/cjfilebrowser.html",
    plugin_cjfilebrowser_actions : "navigateDirectory,createDirectory,deleteDirectory,fileDelete,fileUpload",
    plugin_cjfilebrowser_winWidth : 900,
    plugin_cjfilebrowser_winHeight : 600,
    plugin_cjfilebrowser_assetsUrl: "<RELATIVE_PATH_TO_MY_UPLOAD_FOLDER>", // from web root
    plugin_cjfilebrowser_fileExts: "*",
    plugin_cjfilebrowser_maxSize: 1500,
    plugin_cjfilebrowser_maxWidth: 600,
    plugin_cjfilebrowser_maxHeight: 600,
    plugin_cjfilebrowser_showImgPreview: true,
    plugin_cjfilebrowser_engine: "coldfusion8",
    plugin_cjfilebrowser_handler: "handler.cfc",
    plugin_cjfilebrowser_timeOut: 900, // 15 minutes
    file_browser_callback : "CJFileBrowser_tinyMCE_Callback"
});

The bold-italic items are what's necessary to initialize the plug-in. My tinyMCE.init has a lot more in it than what's listed above, but I wanted to give you a simple example on how to add the plug-in settings. (Be sure to add cjfilebrowser to the list of tinyMCE plug-ins.) Below you will find a more detailed explanation of what each parameter is.

VariableDescription
plugin_cjfilebrowser_browseUrlThe relative path to the plug-in.
plugin_cjfilebrowser_actionsThe list of CJ File Browser actions to enable. By removing these actions, it will also remove the option from the file browser interface if applicable. The current list of actions are:
plugin_cjfilebrowser_winWidthThe width of the file browser pop-up window.
plugin_cjfilebrowser_winHeightThe height of the file browser pop-up window.
plugin_cjfilebrowser_assetsUrlThe relative path to your media folder from web root. Example: /assets/images/ (Be sure this is from webroot and not from the page calling the plug-in. Using "../../assets/images/" might not work!)
plugin_cjfilebrowser_fileExtsA comma separated list of file extensions to allow. Example would be "jpg,gif,png,doc,pdf". To allow all file types, use "*"
plugin_cjfilebrowser_maxSizeThe maximum file size in Kilobytes that the user can upload.
plugin_cjfilebrowser_maxWidthThe maximum width in pixels that an image can be. CJ File Browser will scale images to fit this width.
plugin_cjfilebrowser_maxHeightThe maximum height in pixels that an image can be. CJ File Browser will scale images to fit this height.
plugin_cjfilebrowser_showImgPreviewBy default the system will attempt to show image previews for web graphics (GIF, JPG and PNG). Setting this option to FALSE will turn this feature off. This may be useful if deployed on slow server.
plugin_cjfilebrowser_engineThe name of the handler engine. Examples: php5, coldfusion7, coldfusion8, etc. (Different handler engine systems can be obtained from www.cjboco.com)
plugin_cjfilebrowser_handlerThe file name of the handler engine file. Examples: handler.php, handler.cfc, etc (This name will vary depending on the handler plug-in requirement. i.e. whatever someone decides to name their handler file)
plugin_cjfilebrowser_timeOutYou amount of time in seconds that any action will timeout. This is useful for sites that have deployed SeeFusion or similar server technology that restrict page request times. Defaults to 900 (15 minutes).
file_browser_callbackThis is the name of the callback function for the tinyMCE plug-in. You shouldn't need to modify this.

That should be all you need to get CJ File Browser up and working with tinyMCE. If you get any errors, be sure to check the paths to the plug-in. Remember that these variable names are case-sensitive.

Standalone Mode

If you choose to use the browser in standalone mode, then you will need to make a function to handle the file select (If it's active). The initialization parameters are basically the same as the ones used for plug-in mode. The only big difference is that you don't need to provide winWidth and winHeight, since the browser will fill the entire browser window. You will need to create a callback function to handle the file browser selection. CJ File Browser will pass you the relative and absolute path to the file you selected when the button is pressed. Out of the box, it will just show an alert with these variables. This is a typical tinyMCE initializations script with jQuery:

$(document).ready(function() {
   cjFileBrowser.init({
      actions: ["navigateDirectory","createDirectory","deleteDirectory","fileDelete","fileUpload","fileSelect"],
      baseUrl: ["<RELATIVE_PATH_TO_MY_UPLOAD_FOLDER>"],
      fileExts: "gif,png,jpg",
      maxSize: 1500,
      maxWidth: 600,
      maxHeight: 600,
      showImgPreview: false,
      engine: "coldfusion8",
      handler: "handler.cfc",
      timeOut: 900, // 15 minutes
      callBack: function(fileObj) {
         if (typeof fileObj === "object") {
            var str = "CJ File Browser is in standalone mode. You selected:\n\nRelative Path: " + (fileObj.DIRECTORY + fileObj.NAME) + "\n\nAbsolute Path: " + fileObj.FULLPATH;
            alert(str);
         }
      }
   });
});

This example is set up to only allow GIF, JPG and PNG file types. And the show previews is turned off.

Browser Icons

I've provided the original photoshop files for the browser icons. If you would like to create more icons, then all you need to do is use these files. Once you've created the icon, move it to the assets/icons folder. You will need to make sure that the file exension is listed in the stylesheet as well. You can edit the style sheet entries in assets/css/icon.css.

Conclusion

As of right now, the only Handler Engine plug-in available is for ColdFusion 8. I plan on writing some more when I have time, but that shouldn't stop you from giving it a try. I've commented the heck out of the source files, so if you take a look at what I'm doing, you should be able to figure things out. My goal is to provide a PHP engine soon, but that could be awhile. If you do write an engine, be sure to let me know and I'll put it on the site for others.

That's about it. If you have any questions, comments or problems using it, let me know below.

Release Notes

If you downloaded the files before 4/20/2010 @ 4PM PST, then you need to download it again to get the version that fixed the IE8 Ajax Caching Bug. (Thanks wfinley!)