ActiveXPowUpload 1.0.1 control documentation

ActiveXPowUpload object properties 

All properties with write access ({set [/get]}) can be seted by 2 methods:
1. Inside <OBJECT>...</OBJECT> tag using following HTML code:
<param name="EnableFilesList" value="false" />

2. or using JavaScript Code like:
ActiveXPowUpload.EnableFilesList=false;

Please keep in mind that if JavaScript not enabled at users browser then second method willn't work. So use first method if there are no reasons to use second.

Properties with read only access can be used only at JavaScript.



Server property

Script property

Port property

SSL property

Agent property

UserName property

UserPassword property

MaxFileCount property

MaxFileSize property

MaxTotalSize property

Filter property

AllowExtensions property

ProhibitExtensions property

EnablePopupMenu property

EnableFilesList property

EnableProgressWindow property

EnableEmbProgressWindow property

EnableMessagesDialog property

EnableErrorsDialog property

InternationalText property

International property

SerialKey property

FileCount property

TotalFileSize property

ItemsAtClipboard property

RedirectURL property

RedirectTarget property

FormItem property

FormItems property

debug property

FileFormItemPattern property

Version property


Server

String Server {set/get}

Server host name or IP address.

Description

Host name or server IP address where to upload files. Don't specify protocol, port or script path here! Use SSL property for SSL support, Port property to set HTTP Port and Script property to set file processing script path.

Examples:

ActiveXPowUpload.Server="localhost";
ActiveXPowUpload.Server="www.somehost.com";
ActiveXPowUpload.Server="127.0.0.1";

Script

String Script {set/get}

Path to a file processing script.

Description

The server script configured to handle uploads and save files at the server. Don't specify full URL here! Concatenation of Server and Script properties should be URL without protocol. You can find ASP, ASP.NET, PHP, PERL, JSP samples of file processing scripts at the FileProcessingScripts\ folder.

Example

ActiveXPowUpload.Script="/scripts/proccessfiles.asp";
ActiveXPowUpload.Script="/savefiles.aspx?getparam=value"; //You can pass GET parameters to the script

Port

Long Port {set/get}

Server HTTP Port .

Description

HTTP port of the web server. 0 means use default port. 80 for plain HTTP, 443 for HTTPS (If SSL property is true). Default value is 0.

Example

ActiveXPowUpload.Port=8080;


SSL

Boolean SSL {set/get}

Determines if secured SSL (HTTPS) connection should be used.

Description

Determines if secured SSL (HTTPS) connection should be used while sending files to server. Web server should be setup to accept SSL connections.

Example

ActiveXPowUpload.SSL=true;


Agent

String Agent {set/get}

User-Agent HTTP header's value

Description

User-Agent HTTP header's value contains information on Browser and OS installed at the user side. This property allows to set any custom value. Default value is that which Internet Explorer sends.

Example

ActiveXPowUpload.Agent="Mozilla/4.0 (compatible; MSIE 6.0)";

UserName

String UserName {set/get}

User name if remote server requires authentication.

Description

If remote server which handles files requires authentication you can set a user name and password. Authentication in this case will work automaticaly. If the name and password are not specifed at these parameters user will see a standard dialog and need to enter credentials. Setting name and password at a webpage is not secure in most cases! Use this feature only if you sure that it is safe! Otherwise leave this property an empty value. If the user passed authentication while opening a web page he don't need to enter credentials second time and this property should be empty.

Default value is an empty string.

Example

ActiveXPowUpload.UserName="gdoe";
ActiveXPowUpload.UserPassword="mypassword";



UserPassword

Strng UserPassword {set/get}

User password if remote server requires authentication .

Description

Default value is an empty string.

See UserName property.



MaxFileCount

Long MaxFileCount {set/get}

Maximum number of files allowed to add to the file list.

Description

Maximum number of files allowed to add to list and upload (folders are not counted). Default value is 0 (unlimited).

Example

ActiveXPowUpload.MaxFileCount=10;



MaxFileSize

Long MaxFileSize {set/get}

Maximum size of a file allowed to add to the file list

Description

Maximum size of file allowed to add to list and upload, in bytes. The maximum allowed value is 2147483648 (2 Gb). Default value is 0 (Unlimited but less than 2 GB)

Example

ActiveXPowUpload.MaxFileSize=10*1024*1024; //10Mb quota



MaxTotalSize

Long MaxTotalSize {set/get}

Maximum total size of files allowed to add to the file list

Description

Maximum total size of a files allowed to add to list and upload, in bytes. The maximum allowed value is 2147483648 (2 Gb). Default value is 0 (Unlimited but less than 2 GB)

Example

ActiveXPowUpload.MaxTotalSize=(1024*1024*1024)-1000; //1GB minus 1000 bytes (space for header data) quota.



Filter

String Filter {set/get}

File type filters for the "Browse files" dialog.

Description

File type filters for the "Browse files" dialog in a form of a list of pairs separated by the pipe character '|'. Each pair specifies the verbal description of a filter and the filter itself as a list of semicolon-separated (';') wildcards. Use ProhibitExtensions property to absolutly prohibit some extensions.

Example

ActiveXPowUpload.Filter="Images (.gif;.jpg;.bmp;.png)|*.gif;*.jpg;*bmp;*png|Text files (.txt;.doc)|*.txt;*.doc|All Files|*.*";



AllowExtensions

String AllowExtensions {set/get}

Specifies a comma-separated list of allowed file extensions.

Description

Specifies a comma-separated (',') list of allowed file extensions. Only files having extentions listed in the AllowExtensions list are added to the file list. Extensions comparison is case-insensitive. If AllowExtensions is an empty string, it's counted like every possible file extention presents in this list, so all files are added to the file list. It you want to use an empty extention, do one of the following: put two commas one by one in the list, or put a single comma at the begining of the list, or put a single comma at the end of the list. Use Filter property to show only allowed files at the "Browse files" dialog.

See also ProhibitExtensions.

Example

ActiveXPowUpload.Filter="Images (.gif;.jpg;.bmp;.png)";
ActiveXPowUpload.AllowExtensions="gif,jpg,bmp,png";



ProhibitExtensions

String ProhibitExtensions {set/get}

Specifies a comma-separated list of prohibited file extensions.

Description

Specifies a comma-separated (',') list of prohibited file extensions. Files with such extensions won't be added to the list. Extensions comparison is case-insensitive. An empty string indicates no limitations. It you want to use an empty extention, do one of the following: put two commas one by one in the list, or put a single comma at the begining of the list, or put a single comma at the end of the list. If a file extension is listed both in the AllowExtensions and ProhibitExtensions list, the last wins. I.e. a file with such extension will not added to the file list.

See also AllowExtensions.

Example

ActiveXPowUpload.ProhibitExtensions="exe,com,bat,vbs";



EnablePopupMenu

bool EnablePopupMenu {set/get}

Determines whether a popup menu will be available or not.

Description

Determines whether a popup menu will be available or not. Default value is 'true' (Available).

Example

ActiveXPowUpload.EnablePopupMenu=false;



EnableFilesList

bool EnableFilesList {set/get}

Determines whether files list will be available or not.

Description

Determines whether files list will be available or not. Default value is 'true' (Available). Set to 'false' if you want to hide ActiveX interface but leave area to drop files (drag-n-drop).

Example

ActiveXPowUpload.EnablePopupMenu=false;
ActiveXPowUpload.EnableFilesList=false;



EnableProgressWindow

bool EnableProgressWindow {set/get}

Determines whether progress window will be available or not.

Description

Determines whether progress window will be available or not. Default value is 'true' (Available). Set to 'false' if you want to replace progress window with your custom DHTML+JavaScript interface.

Example

ActiveXPowUpload.EnableProgressWindow=false;



EnableEmbProgressWindow

bool EnableEmbProgressWindow {set/get}

Determines whether embedded progress window will be available or not.

Description

Determines whether embedded progress window will be available or not. Default value is 'true' (Available). Set to 'false' if you want to replace progress window with your custom DHTML+JavaScript interface.

Example

ActiveXPowUpload.EnableEmbProgressWindow=false;



EnableMessagesDialog

bool EnableMessagesDialog {set/get}

Determines whether messages dialogs will be available or not.

Description

Determines whether messages dialogs will be available or not. Default value is 'true' (Available).

Example

ActiveXPowUpload.EnableMessagesDialog=false;



EnableErrorsDialog

bool EnableErrorsDialog {set/get}

Determines whether errors dialogs will be available or not.

Description

Determines whether errors dialogs will be available or not. Default value is 'true' (Available). Set to 'false' if you want to handle and show errors by custom JavaScript code (OnError event) and HTML interface.

Example

ActiveXPowUpload.EnableErrorsDialog=false;



InternationalText

String InternationalText (textconstant: String) {set/get}

Property with parameters. Allows to read and set most captions, messages text if you whould like to localize control.

Description

Property with parameters. Allows to read and set most captions, messages text if you whould like to localize control. You can use any language for localization text. Control supports Unicode strings.

Parameters

textconstant String constant of caption or message. Currently supported constants:

Pop-up menu: List header: Progress dialog: Warnings and errors without parameters Warnings and errors with parameters

Warning and error messages with parameters must obey special rules. A message string contains placeholders where parameters are inserted. A placeholder is a number in curly braces. For example, "{1}" is a placeholder for the first parameter. The number inside is the parameter number. The first parameter has number 1, the second - 2, and so on. A parameter placeholder can be placed anywhere in the string. The order of parameters doesn't matter. It's possible to place the second parameter before the first. The same parameter can be placed multiple times in the string. The string must contain the paramenter with the largest number, but it's not necessary to include parameters with lower numbers. E.g. if a message contains two parameters, the string must contain a placeholder for the second parameter, but the first parameter can be omitted.

A percent sign has a special meaning in the string. It starts an ASCII code. Each percent sign must be followed by two characters representing a hexadecimal ASCII code of the character you want to insert. A hexadecimal number consists of 0-9 digits, a-f and A-F letters. Letters are consided case insensitive. To put a percent sign itself place "%25" substring because 0x25 is an ASCII code of the percent sign. This feature is useful when you want to insert, for example, "{1}" substring literally. In the case you simply put it in the string, it is interpreted as a placeholder for the first parameter. It's not what you intend. To output the exact string replace any character with it ASCII code number in order to the substring does not look like a placeholder. For example, you may write "%7B1}", or "{1%7D", or even "%7B%31%7D". Every "%dd" sequence (where d means a digit, or one of the letters a-f, A-F) is replaced by a corresponding character. The 0xdd number must be less than 0x80, because only ASCII characters can be encoded.

Internationalization strings without parameters are treated literally.

Example

window.alert('Default Menu "Add files..." string is ' + ActiveXPowUpload.InternationalText('MENU_ADD_FILE')); ActiveXPowUpload.InternationalText('MENU_ADD_FILE') = "My custom add files...";



International

String International {set/get}

A string of text containing (key, value) pairs of elements used to localize captions, menu items, the progress dialog etc.

Description

This property allows you to get or set all text elements that is possible to change (menu items, captions, messages and so on). The string must be formed according to the following rules:

The string is a sequence of (key, value) pairs separated by a semicolon. The last semicolon is optional. A key and a value are separated by an equal sign ('='). You can't add any space before or after the equal sign unless it is part of the key or the value respectively. See InternationalText property for a list of possible keys. The value may be any string of unicode text, but the '%', '=' and ';' characters must be encoded. They are replaced by ASCII codes: '%' replaced by '%25', '=' replaced by '%3D', ';' replaced by '%3B'. Encoding rules are the same as for items with parameters in InternationalText property. A value may be an empty string. In this case the equal sign is immediately followed by a semicolon (or the end of the string). It's allowed to insert any number of optional new line, space, and tab characters after the semicolon that separates (key, value) pairs. It's done for readability.

For example, the string "abc=123;" sets the key "abc" to the value "123"; the string "abc=100%25" sets the key "abc" to the value "100%"; the string "abc=1+23%3D24%3B10-1%3D9;" sets the key "abc" the value "1+23=24;10-1=9".

It is not necessary to specify all the keys in the string. You may specify only those you want to change. But when you read the property you get a string containing all the keys the component knows about.

If the string you are tring to set is wrong, an error occures and none of the keys will be changed.

Example

ActiveXPowUpload.International = "LIST_HEADER_FILES=Files;LIST_HEADER_SIZE=Size;MENU_ADD_FILE=Add files...;MENU_ADD_FOLDER=Add folder...;MENU_CANCEL=Cancel;MENU_PASTE=Paste;MENU_REMOVE_ALL=Remove all;MENU_REMOVE_SELECTED=Remove selected;MENU_UPLOAD=Upload;";

 

SerialKey

String SerialKey {set/get}

Product Serial Key to make Trial version work as full.

Description

Product Serial Key to make Trial version work as full. After purchasing commercial license you need to set serial key at parameters to remove all limitations of trial version (The trial version sometimes shows a dialog box after upload is started.). Every ActiveXPowUpload instance must be activated independently. You need not make extra actions to hide key at a web page. We understand that the key is visible to any person who can view the page source code. But it is our problem:).

Example

ActiveXPowUpload.SerialKey="111111111";

or

<OBJECT ID="AxUpload" CLASSID="CLSID:FB98CEED-9DE1-4517-B30C-CDA19C6D150B">
<param name="SerialKey" value="11111111111">
</OBJECT>



FileCount

Long FileCount {read only}

Returns number of files in the file list.

Description

Returns number of files in the list. As long as file list may contain folders as well as file the total number of items in the list is usually larger than the value of this property.

See also FileListItemCount property.

Example

var filesCount = ActiveXPowUpload.FileCount;



FileListItemCount

Long FileListItemCount {read only}

Returns number of items in the file list.

Description

File list may contain folders and files. This property counts both of them.

Example

var itemsCount = ActiveXPowUpload.FileListItemCount;



TotalFileSize

Long TotalFileSize {read only}

Returns total size of files in the list.

Description

Returns total size of files in the list, in bytes.

Example

var totalSize = ActiveXPowUpload.TotalFileSize;



ItemsAtClipboard

Long ItemsAtClipboard {read only}

Returns number of items at the clipboard.

Description

Returns number of items at the clipboard if it contains files and folders or zero otherwise. Number of items is not the same a number of files. If the clipboard contains a folder, it is always one item regardless of the number of files in it.

Example

var totalItems = ActiveXPowUpload.ItemsAtClipboard;


RedirectURL

Long RedirectURL {set/get}

Specifies a URL where to redirect upload results.

Description

If RedirectURL is not an empty string, ActiveXPowUpload redirects the browser to the URL specified as soon as upload completes. ActiveXPowUpload receives all the text upload script sends in response to data upload. The text is url-encoded (see RFC1738). Control sends a POST request contaning a single ACTIVEXPOWUPLOADREPLY field. ACTIVEXPOWUPLOADREPLY field value is a url-encoded text. Content type of the post request is "application/x-www-form-urlencoded" (see application/x-www-form-urlencoded content type).

To display upload results it is enough to put this line in an asp script:

<% Response.Write Request.Form("ACTIVEXPOWUPLOADREPLY") %>

RedirectURL can be a relative url. The url is considered to be relative if it doesn't start with the "http://" or "https://" string. To form a full url, a url of the current page (frame) is taken, the page name is truncated and the relative url is concatenated. For example, if RedirectURL is "dir_1/dir_2/page.asp", the current page has a url "http://servername/dir1/dir2/demo.asp", then a full redirect url is "http://servername/dir1/dir2/dir_1/dir_2/page.asp".

See also RedirectTarget.

Example

ActiveXPowUpload.RedirectURL = "http://www.somedomain.com/path/to/receiver.asp";


RedirectTarget

String RedirectTarget {set/get}

Specifies a target window or frame where to show the upload results.

Description

When RedirectURL is set, the component redirect upload results as soon as upload completes. The resulted page must be shown somewhere. That is exactly the RedirectTarget is for. The possible values are:

The default value is _self.

See also RedirectURL.

FormItem

String FormItem (name: String) {set/get}

Description

Allows to get/set a text form item by name. The name can't be empty. It you try to get an item that does not exist, you get an error. When you set a value to an item that does not exist, a new (name, value) pair is created.

See also AddFormItem, RemoveFormItem, RemoveAllFormItems methods.

Parameters

name text form item name.

Example

ActiveXPowUpload.FormItem("abc") = "123";

var a = ActiveXPowUpload.FormItem("abc");


FormItems

String FormItems {set/get}

Description

A list of all text form items. When you set the property, the internal list of properties is reset. New internal list will contain only items listed in the string. (key, value) pairs are separated by a semicolon. Each pair is encoded as a sequence of key, equal sign, and value. The key and the value must be encoded. Each '=', '%', ';' sign must be replaced by the "%3D", "%25", "%3B" string correspondingly. The format of the string is the same as for the International property.

See also AddFormItem, RemoveFormItem, RemoveAllFormItems methods, FormItem property.

Example

ActiveXPowUpload.FormItems = "a=123;b=sw;";

var a = ActiveXPowUpload.FormItems;


debug

Long debug {set/get}

Description

Debug level. Default value is 0. The greater the value the more debug output the control produces. 0 means no debug messages to produce. Each debug message is an OnLog event. This property should be used to troubleshoot the behavior of the ActiveX control. Messages the control produces are not user friendly. They would be helpfull when you want to get support.

See also OnLog.


FileFormItemPattern

String FileFormItemPattern {set/get}

Description

A template that used to name file form items. "{i0}" and "{i1}" substrings are a placeholder for file number. The first pattern uses zero-based number sequence, in the second pattern file numbers starts from 1. Only the first occurrence of the placeholder is replaced by file number. If the string does not contain the placeholder at all, it's treated like a "{i0}" string is added at the end. For example, "file-{i0}-ext" pattern gets names "file-0-ext", "file-1-ext", "file-2-ext", and so on. The pattern "file{i1}end" gets names "file1end", "file2end", "file3end", and so on.


Version

String Version {get}

Version of the component.

Description

For example, the value may be "1.0.1.0".