JavaPowUpload 2.2 Tutorials

Home page Contact support

JavaPowUpload tutorials 

1. Data types
2. Include JavaPowUpload applet on a page
3. Configure JavaPowUpload using parameters
4. JavaScript communication
5. Download mode
6. Upload modes, chunked upload mode
7. Upload thumbnails
8. Compress before upload
9. Control JavaPowUpload using server response
10. Internationalization of UI
11. Upload files directly to Amazon S3

1. Data types

   Here is the list of all data types used by JavaPowUpload:
   • String - Simple string data type.
   • Number - Number data type is a common type for simple integer values and floating point numbers.
   • Boolean - Boolean data type. Valid values for this data type are "true", "false".
   • URL - Absolute or relative url to a resource. The absolute url should start with http:// or / , otherwise the url will be relative to the location of the html page where it is placed. This data type is also used to set up the location of the image files, in this case the default parameter value may be empty or "internal". It means that JavaPowUpload uses some build-in resources.
   • Color - Datatype to set up colors for some of the UI elements. It is a standard HTML hexidecimal color value with "#" or "0x" prefixes.

2. Include JavaPowUpload applet on a page

   You can deploy applet on a page with 2 ways:
   
   
   1. Regular applet tag:

      <applet 
      	code="com.elementit.JavaPowUpload.Manager"
      	archive="lib/JavaPowUpload.jar, lib/skinlf.jar,
      	lib/commons-httpclient.jar,	
      	lib/commons-net-ftp.jar,
      	lib/commons-compress.jar"
      	width="600"
      	height="400"
      	name="JavaPowUpload"
      	id="JavaPowUpload"
      	mayscript="true"
      	alt="JavaPowUpload by www.element-it.com">
         
        <!-- Java Plug-In Options -->
        <param name="progressbar" value="true">
        <param name="boxmessage" value="Loading JavaPowUpload Applet ...">
        <!-- JavaPowUpload parameters -->
        <param name="Common.SerialNumber" value="put your serial number here">
        <param name="Common.UploadMode" value="true">
        <param name="Upload.UploadUrl" value="FileProcessingScripts/ASP.NET/CSharp/uploadfiles.aspx">
        <param name="Common.SkinLF.ThemepackURL" value="lib/themepack.zip">
          Your browser does not support applets. Or you have disabled applets in your options.
          To use this applet, please install the newest version of Sun's java.
          You can get it from <a href="http://www.java.com/">java.com</a>
        </applet>
        

      • applet - The Applet tag tells the browser that a Java-Applet should be embedded here. The attributes have all required information for Java to find and run the specified Applet from the given archive.
        
      • name, id - The name and id of the Applet that JavaScript is using to access JavaPowUpload.
        
      • code - The code tag specifies the location and name of the main class, com.elementit.JavaPowUpload.Manager for JavaPowUpload.
        
      • archive - The archives contain the applet and further classes that are required by JavaPowUpload.
        If http upload mode will not be used, following jar file (required only for http upload) can be ommited:
          lib/commons-httpclient.jar
        
        If themes support not needed, lib/skinlf.jar can be ommited.
        
        If FTP, FTPS support not needed, lib/commons-net-ftp.jar can be ommited.
        
        If compression before upload not needed, lib/commons-compress.jar can be ommited.
        
      • width, height - These two attributes specify the dimension (size) of the JavaPowUpload applet.
        
      • mayscript - It toggles whether JavaScript is allowed to call the methods of the JavaPowUpload applet. If this attribute is ommited, JavaScript events and functions will not work.
        
      • param - The <param> tags can be used to configure the JavaPowUPload applet. All supported parameters are described in the parameters section. Names and values must be quoted. Also note that the names and values are case-sensitive.
   2. With help of Deployment Toolkit Script (deployJava.js) . Example:
      

      <script src="Extra/deployJava.js"></script>
      <script>
      	var attributes = 
      	{
      		name : 'JavaPowUpload',
      		id : 'JavaPowUpload',
      		code : 'com.elementit.JavaPowUpload.Manager',
      		archive : 'lib/commons-httpclient.jar, lib/JavaPowUpload.jar',
      		width : 500,
      		height : 350,
      		mayscript : "true",
      		alt : "JavaPowUpload by www.element-it.com"
      	};
      	
      	var parameters = 
      	{
      		"Common.SerialNumber" : "put your serial number here", 
      		"Common.UploadMode" : "true", 
      		"Common.UseLiveConnect" : "true",
      		"Upload.UploadUrl" : "FileProcessingScripts/PHP/uploadfiles.php" 
      	};
      	
      	var version = '1.5.1' ;
      	deployJava.runApplet(attributes, parameters, version); 
      
      </script>

      deployJava.runApplet(attributes, parameters, minimumVersion) - Ensures that an appropriate JRE is installed and then runs an applet.

3. Configure JavaPowUpload using parameters

   Parameters can be specified using 3 ways:

   1. Using <param> tag of the <applet> tag.

      Example:
      <param name="Common.UploadMode" value="true">
      
      If you sue delpoyJava.js script to place applet on a page, the you should specify JavaPowUpload parameters at parameters javascript array.

   2. Using external xml file, specified with the Common.PropertiesFile parameter in <applet> tag.
      
      Example of properties.xml file:

      	<?xml version="1.0" encoding="UTF-8"?>
          <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
          <properties>
          <entry key="Common.UploadMode">true</entry>
          <entry key="Common.BackgroundColor">#FFFFFF</entry>
          <entry key="Common.UseLiveConnect">true</entry>
          </properties>
      

   3. Using JavaScript setParam method.

      Example:

      JavaPowUpload.setParam("Upload.UploadUrl","http://localhost/JavaPowUpload/uploadfiles.php");
      The parameters specified using setParam method have the highest priority, specified using <param> tag of the <applet> tag have the lowest priority.
      Note: not all the parameters can be specified using the setParam method.

4. JavaScript communication

   Here are several steps to start using the JavaPowUpload events and methods:
   • You should set mayscript attribute of the <applet> tag.
   • Set JavaPowUpload Common.UseLiveConnect parameter to true (false by default) .
   • Set JavaPowUpload Common.JavaScriptEventsPrefix parameter to a necessary value ("JavaPowUpload_" by default).

   To use the JavaPowUpload events, you should declare appropriate JavaScript functions. The function name format is Common.JavaScriptEventsPrefix+eventName. List of all available JavaPowUpload events is available in the events section.

   Example:

   function JavaPowUpload_onDownloadStart()
   {
    alert("Starting download process");
   }

   To use JavaPowUpload methods, you should init JavaPowUpload object.

   Example:
   //init JavaPowUpload JavaScript object
var JavaPowUpload;
JavaPowUpload = document.getElementById("JavaPowUpload");
//where "javaPowUpload" is id attribute of <applet> tag>
//Now we can use javaPowUpload methods, for example show browse dialog
JavaPowUpload.clickBrowse();

5. Download mode

   JavaPowUpload can be used to download files from FTP/HTTP server. Here are the steps to configure the download mode:
   • To enable download mode, set the value of the Common.UploadMode parameter to false (by default) .
   • Specify the files for downloading. There are 2 ways:
     1. Xml file with file structure for download, specified by the Download.DataURL parameter.
        Example:
        <?xml version="1.0" encoding="UTF-8"?>
<download>
<folder name="Folder">
<folder name="SubFolder">
<file name="image.jpeg" id="1" length="1240">
<url>SampleFiles/image.jpeg</url>
<thumbnailUrl>SampleFiles/thumbnail_image.jpeg</thumbnailUrl>
</file>
<file name="SimpleArchive.zip" id="2" length="488">
<url>SampleFiles/archive.zip</url>
</file>
</folder>
<file name="UncompressArchive.zip" id="3" length="488" uncompress="true" delete="true">
<url>SampleFiles/archive.zip</url>
</file>
</folder>
</download>
        
        As you can see in this example, there is the root element download.
        You can add folders via the folder element. The attribute name specifies the name of the folder,
        which will be created on the client side. Folders can have nested subfolders.
        Downloadable items are specified by the file element, which also has an attribute name for specifying the filename on the client side.
        Files can have the following attributes:
        length - file size.
        id - custom identifier.
        uncompress - determines whether JavaPowUpload should uncompress zip archive after downloading.
        delete - determines whether JavaPowUpload should delete zip archive after unpacking.
        

        url - Files cannot have any children elements like file or folder, but they do have a source address.
        The source URL of the file to download is specified via an url element.
        The url element specifies an absolute URL to the file, but might also be relative to the codebase
        URL. The codebase URL is the URL where the applet is loaded from.
        If, for example, the JavaPowUpload component is installed to
        http://www.example.com/downloads/JavaPowUpload.jar
        the codebase URL is
        http://www.example.com/downloads/
        
        thumbnailUrl - If you would like to display images preview in thumbnails view when JavaPowUpload work download mode,
        you can specify also thumbnailUrl element for file element. JavaPowUPload will download this file from server and display it in thumbnails view for that file.

     2. Specify file structure for download via parameters.
        Example:
        <param name="Folder_0" value="Test folder">
<param name="File_0" value="image.jpeg">
<param name="File_0.url" value=SampleFiles/image.jpeg">
<param name="File_0.thumbnailUrl" value=SampleFiles/thumbnail_image.jpeg">
<param name="File_0.parent" value="Folder_0">
<param name="File_0.length" value="1240">
<param name="File_1" value="SampleArchive">
<param name="File_1.url" value="SampleFiles/archive.zip">
<param name="File_1.parent" value="Folder_0">
<param name="File_1.length" value="488">
<param name="File_1.uncompress" value="true">
<param name="File_1.delete" value="false”>
        
        Format of names: <FILE || FOLDER>_<INDEX>.<ATTRIBUTE> .
        Attributes for files and folders are the same as in xml file, except following:
        file and folder names should be specified directly in value attribute of corresponding <param> tag,
        parent attribute should be specified for all nested files or folders, otherwise they will be added to the root of tree.

6. Upload modes, chunked upload mode.

   To enable upload mode, set the value of the Common.UploadMode parameter to true (false by default) .
   Set the value of the Upload.UploadUrl parameter:
   
   If you would like to upload files to the FTP server, set the value of the Upload.UploadUrl parameter as absolute FTP url to destination directory on FTP server. The url should have the following format:
   ftp://username:password@domainname.com/destination/folder/
   You can omit a username and a password, in this case JavaPowUpload firstly will try to login as an anonymous user and if no success, it will ask for credential to a user. If a user has entered valid credentials, JavaPowUpload will store them on user's computer and will not ask for them next time when a user will upload files to the same url.
   
   If you would like to upload files to the HTTP server, set a value of the Upload.UploadUrl parameter to point to the server side script which will handle file uploads. The Url may be an absolute or relative to the current web page path (where the applet is placed). Actually JavaPowUpload will use codebase attribute of the <applet> tag as a base path for the relative url. If this attribute is not set in the <applet> tag, its value is set as a base path of the current web page.
   
   By default, JavaPowUpload uploads files by the classic (RFC 1867) method. Here are several disadvantages of this method:
   • Web server should be configured to handle large file uploads. Some of web hostings do not allow to change those settings.
   • If the connection has been lost for some reason, upload process should be restarted from start.
   The main advantage of the classic method is the usage of the standard upload algorithm, which allows you to use regular scripts to save uploaded files on server side.
   JavaPowUpload provides an alternate upload method - chunked upload mode. When this mode is enabled, JavaPowUpload will send files to a server by small chunks.
   Here are several advantages of this method:
   
   • You do not need to configure the web server for large file uploads, because the file is uploaded by small chunks.
   • Ability to resume upload process from that point on which it has been interrupted.
   You should also use a special file processing script on server side to save uploaded chunks in one file. To enable this method, set the value of the Upload.HttpUpload.ChunkedUpload.Enabled parameter to true.
   You can configure the chunk size with the Upload.HttpUpload.ChunkedUpload.ChunkSize parameter. By default, the value of this paraneter is set to -1, in this case JavaPowUpload will automatically select the best value for the chunk size during the upload process. To limit maximum value for the chunk size, when it is controlled by JavaPowUpload, you can use the Upload.HttpUpload.ChunkedUpload.ChunkSize parameter. The value of this parameter should be less than the upload file size limitation on server side. For example, by default, php limit of the upload file size is 2 Mb.
   

7. Upload thumbnails

   JavaPowUpload can generate image thumbails on the client side and upload them to a server. Supported image formats are JPEG, PNG, GIF. Here are the steps to configure the thumbnails upload feature:
   • First of all, to enable this feature, you should set the value of the Upload.Thumbnails.Upload parameter to true.
   • If you would like to send original images, set the value of the Upload.Thumbnails.UploadOriginalFileparameter to true.
   • Set the values of the Upload.Thumbnails.Width and Upload.Thumbnails.Height parameters. These parameters determine the destination dimensions of the resized image. To set thumbnail's height (width) in percentage from orginal image height (width), set the value as a number from 0.0 to 1.0. For example, to generate a thumbnail with the half-size width, set the value of the Upload.Thumbnails.Width parameter to 0.5.
   • You can change the thumbnail format by setting the value of the Upload.Thumbnails.Format parameter. JavaPowUpload supports the following image formats for the thumbnail generation: JPG (by default) , PNG, BMP.
   • If you would like to include metadata from original image file into thumbnail, set the value of the Upload.Thumbnails.IncludeOriginalImageMetadata parameter to true.

8. Compress before upload

   JavaPowUpload can compress files into archive before upload. It may greatly decrease network traffic and upload time for some file types. Supported compression formats are ZIP, JAR, TAR, TAR-GZIP, TAR-BZIP2. Here are the steps to configure the compression before upload feature:
   • First of all, please make sure that url to the commons-compress.jar file included into archive attribute of your <applet> tag. Read Include JavaPowUpload applet on a page section of this tutorial .
   • To enable compression feature, you should set the value of the Upload.Compress.Enabled parameter to true.
   • You can choose needed format for compression, by changing the value of the Upload.Compress.Format parameter. Supported compression formats are ZIP, JAR, TAR, TAR-GZIP, TAR-BZIP2.
   • If you need to split archive in several parts, you can configure maximum count of files for each part by changing the value of the Upload.Compress.MaxFilesInArchive parameter.
   • It is possible to include only files of particular types into archive and ignore other types. Please take a look at Upload.Compress.IncludeFileTypes and Upload.Compress.IgnoreFileTypes parameters.
   Please note: if chunked (http) upload mode enabled, each file chunk will be compressed before upload and it should be properly uncompressed on server side. It allow to save time (taken by compression of whole file before upload) and space on user hard drive (taken by temp archive file).
   

9. Control JavaPowUpload using server response.

   Starting from version 2.0.5, JavaPowUpload supports the execution of some commands received from a server in an http response.
   To use this feature, you should write a special xml structure at any place of the response. JavaPowUpload will search for <JavaPowUpload> and </JavaPowUpload> tags in the server response and, if they are found, will try execute a command between these 2 tags.
   Below is the valid xml structure with all commands that are supported in the current version:

   <JavaPowUpload>
   //display message with caption "Warning" message from tag
   <message>Uploaded</message>
   //set value of parameter
   <param name="clearButtonVisible">false</param>
   //display message with specified caption and message
   <function name="showAlert" param1="warning" param2="error message"/>
   //cancell upload
   <callfunction name="cancelUpload"/>
   </JavaPowUpload>
   

   Here is the description of all available tags (commands):
   • <function name="functionName" param1="value1" param2="value2"/>
     or
     <callfunction name="functionName" param1="value1" param2="value2"/> - call function with the name specified in the name attribute and 2 parameters (if they are set) from param1 and param2 attributes.
     Available functions to call:
     • showAlert is with 2 parameters. The first parameter will be used as a caption for the modal window, the second parameter - as message text.
     • cancelUpload is without any parameter. The parameter cancels the upload operation.
   • <message>Your text here</message> - It shows a modal window with the "Warning" caption and a message from the tag contents.
   • <param name="parameterName">parameterValue</param> - It sets the value of a parameter with the specified name.
   • <error message="Custom error message "/> - Display error message and mark uploaded file(s) with error status.
   • <response>Some response message</response> - JavaPowUpload will use specified text as response string. It will be passed to _onServerResponse(status, response) java script event handler.
     

10. Internationalization of UI.

    Starting from version 2.0.5, JavaPowUpload provides the feature to detect a user's language automatically and load a necessary file with the translation. This feature can be enabled/disabled using the Common.Language.AutoDetect parameter (false by deafult). If the parameter is set to true, JavaPowUpload will try to detect the user's language using the following JavaScript statement: (navigator.language) ? navigator.language : navigator.userLanguage. When the language is detected, the 2-letter language code will replace <LANGUAGE_CODE> placeholder in the Common.InternationalFile parameter. If the value of Common.InternationalFile parameter does not contain <LANGUAGE_CODE> placeholder, the language detection will not be performed. If the value of the Common.Language.AutoDetect parameter is set to false and the value of the Common.InternationalFile parameter contains <LANGUAGE_CODE> placeholder, the language detection will not be performed and the Common.InternationalFile parameter will be ignored.
    The JavaPowUpload distribution package contains a lot of translation files in the Extra/Languages/ subfolder.
    If you would like to set the translation manually, you should set the value of the Common.Language.AutoDetect parameter to false and remove the <LANGUAGE_CODE> placeholder from the Common.InternationalFile parameter.
    Changing the value of the Common.InternationalFile parameter at runtime using the setParam method will result the reload of the translation file from the new location and the reinitialization of JavaPowUpload.

11. Upload files directly to amazon S3

    Starting from version 2.1 JavaPowUpload allow upload files directly to Amazon S3 servers.
    To upload files to your own Amazon S3 bucket you need to generate required parameters. Please use amazons3generator.html page from distribtiuon package to generate needed parameters. Open amazons3generator.html page in a browser and follow instructions. Your secret key will not be transferred by wire. All calculations done on your computer using JavaScript.
    When done, open uploadtoamazons3.html page in editor , find <applet tag and put into it parameters (replace existing) generated on amazons3generator.html page.