dhtmlXVault Guide and Samples

Main features

  • Multibrowser/Multiplatform support (Windows, Linux, MacOS)
  • Progress bar indicator while uploading
  • Full control with JavaScript
  • ASP.NET support
  • JSP support
  • Perl support

  • And new:
  • PHP support (with progress bar)new
  • Ability to control the number of uploaded filesnew
  • Ability to check file types (extensions)new
  • Callback events for better integration with DhtmlXSuitenew
  • Add custom form fieldsnew
  • Localization for text Labelsnew
  • Theme Sky Bluenew
  • Supported browsers

  • IE 5.x and above
  • Mozilla 1.4 and above
  • Firefox 0.9 and above
  • Safari 4
  • Google Chrome
  • Opera 10
  • Contact information

    Please post your comments and questions to info@dhtmlx.com

    Working with dhtmlXVault

    You can see the example code in our /samples folder. Simply copy those files to the root folder of your web server (together with /codebase folder) and run them.

    Initialize object on page

    <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); vault.create("vaultDiv"); </script> As you may see, it is pretty easy to initialize the Vault on your page.
    You only pass your div identifier (it should be created before the call) in "create()" method, and that will build the control for you.

    Server Handlers description

  • Upload handler - it is the main upload handler. It should parse the request (multipart-form data) and store file on server.
    Also, it is gathering progress information and stores it in Application or Session context, so the next handler can read it.
  • GetInfo handler - this handler aimed to return progress information (as percent uploaded).
    It receives "sessionId" parameter as a unique File Transfer identifier, so concurrent uploading is possible.
  • GetId handler - this handler is called once per upload, to get a unique File Transfer Id.
    This value is used later to read the upload progress information.
  • Control the number of uploaded files

    Use setFilesLimit(count) method.
    The code below will set files limit to 1, so user will be able to upload one and only one file. When he chooses one file, the "Add" button is disabled. <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); vault.setFilesLimit(1); vault.create("vaultDiv"); </script> If you want to set it to unlimited, use the 0 (zero) count value - vault.setFilesLimit(0).

    Check file types

    Use onAddFile event handler to check file extension.
    <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); vault.onAddFile = function(fileName) { var ext = this.getFileExtension(fileName); if (ext != "txt" && ext != "doc") { alert("You may upload only text documents (txt, doc). Please retry."); return false; } else return true; }; vault.create("vaultDiv"); </script> If the handler function returns false, this file is not added to the list and will not be uploaded.

    On upload complete

    Use onUploadComplete event handler to update your DhtmlX controls or check the upload status.
    <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); vault.onUploadComplete = function(files) { var s=""; for (var i=0; i<files.length; i++) { var file = files[i]; s += ("id:" + file.id + ",name:" + file.name + ",uploaded:" + file.uploaded + ",error:" + file.error)+"\n"; } alert(s); }; vault.create("vaultDiv"); </script> The handler is called with files array as an argument. It contains file objects with the following properties: file = { id: "1", name: "file.name", uploaded: true/false, error: true/false }; uploaded is true if the file was successfully uploaded. If error happened during upload, error property will be true and the upload will stop.

    On every file

    Use onFileUploaded event handler to react on every particular file uploaded.
    The handler is called with file object as an argument. <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); vault.onFileUploaded = function(file) { alert("id:" + file.id + ",name:" + file.name + ",uploaded:" + file.uploaded + ",error:" + file.error); }; vault.create("vaultDiv"); </script>

    Add custom form fields

    Use setFormField(fieldName,value) method to add your own fields to the form.
    You can call this method only after the create() method, when the object is instantiated on the page.
    You may call this method with value null to remove corresponding field from the form. <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); vault.create("vaultDiv"); vault.setFormField("customerId", "PS104"); vault.setFormField("country", "UK"); vault.setFormField("groupId", null); // will remove this field from the form </script>

    Localize text labels

    Use vault.strings collection to replace english labels with your localized equivalents.
    <div id="vaultDiv"></div> <script> vault=new dhtmlXVaultObject(); vault.setImagePath("codebase/imgs/"); vault.setServerHandlers("UploadHandler.php", "GetInfoHandler.php", "GetIdHandler.php"); // Translate to German vault.strings.remove = "Entfernen"; // Remove vault.strings.done = "Fertig"; // Done vault.strings.error = "Fehler"; // Error vault.strings.btnAdd = "Add file"; vault.strings.btnUpload = "Upload"; vault.strings.btnClean = "Clean"; vault.strings.errors["TooBig"] = "File is too big ({0} bytes).\nMax allowed size is {1}."; vault.strings.errors["PostSize"] = "Undefined server error. Possible issues:\n"+ "- Unicode file name incorrectly processed by the server;\n"+ "- File size is bigger than server's post-request limit ({0})."; vault.create("vaultDiv"); </script> You may replace the following labels: vault.strings = { remove: "Remove", done: "Done", error: "Error", btnAdd: "Add file", btnUpload: "Upload", btnClean: "Clean" }; vault.strings.errors = { "TooBig": "File is too big ({0} bytes).\nMax allowed size is {1}.", "PostSize": "Undefined server error. Possible issues:\n"+ "- Unicode file name incorrectly processed by the server;\n"+ "- File size is bigger than server's post-request limit ({0})." };

    Running dhtmlXVault on different Servers

    ASP.Net

    To run this sample, create a new virtual directory in your IIS, call it "vault" and point to our "/handlers/aspx/" folder.
    Copy over /codebase folder to the same location.
    Check that it uses ASP.Net version 2.0 framework (use "Properties" menu, then the "ASP.Net" tab).
    You can specify upload folder in the "UploadHandler.ashx", by default it is: FileProcessor fp = new FileProcessor(@"c:\upload\"); Check that this folder has write (or Full) permissions.

    JSP/Java

    To run this sample, copy our "/handlers/jsp" folder to your Tomcat webapp root.
    Copy over /codebase folder to the same location.
    You can specify upload folder in the "UploadHandler.jsp", by default it is: String uploadFolder = "c:\\upload\\"; Check that this folder has write (or Full) permissions.
    We use in this sample Apache's "commons-fileupload" library extended with our own "ProgressMonitorFileItemFactory". Those libraries reside on "WEB-INF\lib" and should go to your application's WEB-INF folder respectively.

    PHP

    To run this sample, copy our "/handlers/php" folder to your Apache htdocs.
    Copy over /codebase folder to the same location.
    You can specify upload folder in the "UploadHandler.php", by default it is: $target_path = 'c:\\upload\\'; Check that this folder has write (or Full) permissions.

    To see the progress bar, PHP version 5.2.x is required and PECL "uploadprogress" module be installed: http://pecl.php.net/package/uploadprogress.
    If you have some problems with this module on Windows (it's rather difficult to find a working dll on their site), you may use the dll located in /handlers/php_PECL_windows_dll. Do not forget to define the following property in your php.ini: uploadprogress.file.filename_template = "C:\php\temp\upload_prog_%s.txt". This file will store a temporary uploading info for "uploadprogress", and should be write enabled by your apache user.
    If you cannot use this extension, you may use Vault with simple uploading indicator from /handlers/php_simple, or Perl CGI scripts instead.

    You may also need to modify your "php.ini" file with the following settings: upload_tmp_dir = "c:\\upload\\uploadtemp" upload_max_filesize = 500M post_max_size = 508M max_execution_time = 900 max_input_time = 900 We check the "upload_max_filesize" property (in GetInfoHandler.php script), and provide an error message back to the user, with id "TooBig". The upload is cancelled. You may customize/translate message text.
    If the file uploaded is bigger than "post_max_size", then we cannot detect this case exactly, because php does not pass such a big request to our script at all. We only get a common error message and pass it to the user with id "PostSize". You may translate it as well.

    Perl

    To run this sample, copy our "/handlers/perl" folder to your Apache htdocs/cgi-bin folder.
    Copy over /codebase folder to htdocs root folder.
    Do not forget to modify the top line in each perl file, set your own path to perl executable: #!D:/Perl/bin/perl.exe -w "upload_settings.inc" file contains path information for temporary and upload folders. You may modify them on your need. Check that those folders have write (or Full) permissions.

    Version/Edition: v1.6/Professional/Standard
    Required js file:dhtmlXVault.js