xmanual.htm

aspupload

a file to the list. The other three restrictions are enforced at the time
when XUpload is instructed to start an upload (via the user interface or
<b>Upload</b>
method.) An attempt to upload a set of files not meeting the <b>MaxXXX</b>
restrictions results in an error message being displayed by the control.</blockquote>

<font color="#000099"><B>Populating File List with Default Values</B></font>

<blockquote>XUpload can be configured to populate its file list automatically
upon loading. This is done via tags of the form &lt;PARAM NAME="File<b>N</b>">
where <b>N</b> is a number greater than 0. When XUpload loads it attempts
to retrieve the PARAMs <b>File1</b>, <b>File2</b>, <b>File3</b>, etc. until
a break in the sequence is encountered, and uses the corresponding values
to populate its file list. For example,
<p><b><font face="Courier New,Courier"><font color="#006600"><font size=-1>&lt;PARAM
NAME="File1" VALUE="c:\My Documents\Spreadsheets\Bool1.xls"></font></font></font></b>
<br><b><font face="Courier New,Courier"><font color="#006600"><font size=-1>&lt;PARAM
NAME="File2" VALUE="c:\My Documents\Spreadsheets\Book2.xls"></font></font></font></b>
<br><b><font face="Courier New,Courier"><font color="#006600"><font size=-1>&lt;PARAM
NAME="File3" VALUE="c:\My Documents\Spreadsheets\Summary.xls"></font></font></font></b></blockquote>


<font color="#000099"><B>Handling Basic Authentication and SSL</B></font>

<blockquote>When XUpload attempts to upload to a server protected by Basic
Authentication, it displays a dialog box asking the user for his/her username
and password which are then sent to the server. You can use the <b>Username</b>
and <b>Password</b> properties to specify default credentials that will
be used by XUpload. If these credentials are valid, XUpload will go ahead
with uploading and no login dialog will be displayed. If the credentials
are rejected by the server, XUpload will display the login dialog with
the User Name and Password boxes populated with the values specified by
the <b>Username</b> and <b>Password</b> properties. You may choose to disable
the login dialog by setting the <b>ShowLoginDialog</b> properties to False.
In that case XUpload will proceed with uploading even if the credentials
specified by the Username/Password properties are invalid, so the upload
may fail.
<p>If the server requires a Secure Socket Layer connection (SSL) you must
set the <b>SSL</b> property to True, as follows:
<p><b><font face="Courier New,Courier"><font color="#006600"><font size=-1>&lt;PARAM
NAME="SSL" VALUE="True"></font></font></font></b></blockquote>


<font color="#000099"><B>Preserving Original "Last Modified" Timestamps of
Uploaded Files</B></font>

<blockquote>When browsers upload files to the server they do not send the
"Last Modified" dates together with the files, but XUpload does. The control
adds a custom header, <B>X-Last-Date</B>, to the standard "Content-Disposition"
and "Content-Type" MIME headers used in form-based uploading. AspUpload
1.4+ uses this information to preserve the original dates of uploaded files.
<P>
Being a custom header, <B>X-Last-Date</B> makes a POST performed by XUpload incompatible with RFC-1867
specifications. If you use a server-side upload component
other than AspUpload, you may experience problems uploading files. To disable
the X-Last-Date header, set the property <B>IncludeDateInfo</B>
to False (<I>new in Version 2.1</i>). 
</blockquote>

<font color="#000099"><B>Using Client-Side VBScript</B></font>

<blockquote>You may customize the appearance and behavior of XUpload on
your Web page using client-side VBScript. The following code disables the
control's popup menu and creates four buttons with the same functionality
as the menu's items:
<br>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=0 COLS=1 WIDTH="85%" BGCOLOR="#FFFFCC" >
<tr>
<td><font size=-1>&lt;SCRIPT LANGUAGE="VBScript"></font>
<br><font size=-1>Sub Select_OnClick</font>
<br><font size=-1>&nbsp; UploadCtl.Select</font>
<br><font size=-1>End Sub</font>
<p><font size=-1>Sub Remove_OnClick</font>
<br><font size=-1>&nbsp; UploadCtl.RemoveHighlighted</font>
<br><font size=-1>End Sub</font>
<p><font size=-1>Sub RemoveAll_OnClick</font>
<br><font size=-1>&nbsp; UploadCtl.RemoveAll</font>
<br><font size=-1>End Sub</font>
<p><font size=-1>Sub Upload_OnClick</font>
<br><font size=-1>&nbsp; UploadCtl.Upload</font>
<br><font size=-1>End Sub</font>
<br><font size=-1>&lt;/SCRIPT></font>
<p><font size=-1>&lt;HTML>&lt;BODY></font>
<p><font size=-1>&lt;OBJECT WIDTH=500 HEIGHT=200</font>
<br><font size=-1>&nbsp;ID="UploadCtl" CLASSID="CLSID:E87F6C8E-16C0-11D3-BEF7-009027438003"
CODEBASE="XUpload.ocx"></font>
<br><font size=-1>&lt;PARAM NAME="EnablePopupMenu" VALUE="False"></font>
<br><font size=-1>&lt;/OBJECT></font>
<br><font size=-1>&lt;P></font>
<br><font size=-1>&lt;INPUT TYPE=BUTTON NAME="SELECT" VALUE="Select"></font>
<br><font size=-1>&lt;INPUT TYPE=BUTTON NAME="REMOVE" VALUE="Remove"></font>
<br><font size=-1>&lt;INPUT TYPE=BUTTON NAME="REMOVEALL" VALUE="Remove
All"></font>
<br><font size=-1>&lt;INPUT TYPE=BUTTON NAME="UPLOAD" VALUE="Upload"></font>
<p><font size=-1>&lt;/BODY>&lt;/HTML></font></td>
</tr>
</table>

<p>Another example of operating XUpload with VBScript can be found in the
sample file <b>Buttons.htm</b>.</blockquote>


<font color="#000099"><B>Uploading Non-File Form Items</B></font>

<blockquote>It is often necessary to upload additional information together
with the files, such as a text description. In browser-based uploading,
this is handled by adding non-file items to the HTML form, for example:
<p><font face="Courier New,Courier"><font size=-1>&lt;FORM METHOD="POST"
ENCTYPE="multipart/form-data" ACTION="UploadScript.asp"></font></font>
<br><font face="Courier New,Courier"><font size=-1>File 1:&lt;INPUT TYPE=FILE
NAME="FILE1"></font></font>
<br><font face="Courier New,Courier"><font size=-1>File 2:&lt;INPUT TYPE=FILE
NAME="FILE2"></font></font>
<br><font face="Courier New,Courier"><font size=-1>Description:&lt;INPUT
TYPE=TEXT NAME="DESCR"></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;INPUT TYPE=SUBMIT
VALUE="Upload!"></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;/FORM></font></font>
<p>XUpload 2.1 is capable of collecting all non-file form items from an
HTML form hosted on the same page and uploading these items along with
files. The property <b>HtmlForm</b> is used to specify the name of the
form, as follows:
<p><b><tt>&lt;OBJECT ID="UploadCtl"</tt></b>
<br><b><tt>...</tt></b>
<br><b><tt>&lt;PARAM NAME="HtmlForm" VALUE="<font color="#CC0000">MyForm</font>"></tt></b>
<br><b><tt>&lt;/OBJECT></tt></b>
<p><b><tt>&lt;FORM NAME="<font color="#CC0000">MyForm</font>"></tt></b>
<br><b><tt>&lt;INPUT TYPE=TEXT NAME="Descr"></tt></b>
<br><i><tt>... other form items</tt></i>
<br><b><tt>&lt;/FORM></tt></b>
<p>The sample file <b>FormItems.htm</b> demonstrates this feature.</blockquote>


<font color="#000099"><B>Collecting Non-File Form Items with VBScript</B></font>

<blockquote>An alternative way of specifying non-file form items is to
call the method <b>AddFormItem( name, value)</b> with VB script. When the
Upload button is clicked, our VB Script must collect data from the form
items on the page and pass them to the XUpload control via the AddFormItem
method, but first it needs to remove all the form items that might have
been passed to the control by previous uploads. This is done by calling
<b>RemoveAllFormItems</b>.
Suppose our page contains the following form items besides the four buttons
mentioned in the VB Script example above:
<p><b><font face="Courier New,Courier"><font size=-1>...</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>Description: &lt;INPUT
TYPE=TEXT NAME=DESCR>&lt;BR></font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>Save in Database?
&lt;INPUT TYPE=CHECKBOX NAME=YESNO>&lt;P></font></font></b>
<p>The Upload_OnClick subroutine now may look like this:
<p><b><font face="Courier New,Courier"><font size=-1>&lt;SCRIPT LANGUAGE="VBScript"></font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>...</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>Sub Upload_OnClick</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;
UploadCtl.RemoveAllFormItems</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;
If YESNO.Checked Then UploadCtl.AddFormItem "YESNO", "on"</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;
UploadCtl.AddFormItem "DESCR", DESCR.Value</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>&nbsp;&nbsp;&nbsp;
UploadCtl.Upload</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>End Sub</font></font></b>
<br><b><font face="Courier New,Courier"><font size=-1>&lt;/SCRIPT></font></font></b>
<p>The sample file <b>Buttons.htm</b> demonstrates this technique.
<p>If ASP is used on the server side, we cannot access the non-file form
items using the Request.Form collection because of the special data format
used in file uploading. AspUpload provides a Form collection of its own:
Upload.Form("DESCR"). For more information on handling non-file form items,
see <a href="http://www.aspupload.com/Manual.htm">AspUpload Manual</a>.</blockquote>


<font color="#000099"><B>Handling Events</B></font>

<blockquote>XUpload fires events on every major occasion such as the beginning
and end of an upload, addition and deletion of files, sorting, errors,
etc. With the help of VBScript, your web page can handle some or all of
the events. The following example replaces the default Reply from Server
message by handling the <b>UploadCtl_ServerReply</b> event:
<br>&nbsp;
<br>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=0 COLS=1 WIDTH="74%" BGCOLOR="#FFFFCC" >
<tr>
<td><font face="Courier New,Courier"><font size=-1>&lt;SCRIPT LANGUAGE="VBScript"></font></font>
<br><font face="Courier New,Courier"><font size=-1>Sub UploadCtl_ServerReply(Reply)</font></font>
<br><font face="Courier New,Courier"><font size=-1>MsgBox("The reply form
the server was: " &amp; chr(13) &amp; chr(10) &amp; Reply)</font></font>
<br><font face="Courier New,Courier"><font size=-1>End Sub</font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;/SCRIPT></font></font>
<p><font face="Courier New,Courier"><font size=-1>&lt;HTML></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;BODY></font></font>
<p><font face="Courier New,Courier"><font size=-1>&lt;OBJECT WIDTH=500
HEIGHT=200</font></font>
<br><font face="Courier New,Courier"><font size=-1>&nbsp;ID="UploadCtl"
CLASSID="CLSID:E87F6C8E-16C0-11D3-BEF7-009027438003" CODEBASE="XUpload.ocx"></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;PARAM NAME="ViewServerReply"
VALUE="False"></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;PARAM NAME="Server"
VALUE="localhost"></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;PARAM NAME="Script"
VALUE="/xupload/uploadscript.asp"></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;/OBJECT></font></font>
<p><font face="Courier New,Courier"><font size=-1>&lt;/BODY></font></font>
<br><font face="Courier New,Courier"><font size=-1>&lt;/HTML></font></font></td>
</tr>
</table>

<p>Another example of using XUpload events can be found in the sample file
<b>Progress.htm</b>.
It<b> </b>demonstrates how to build a custom DHTML-based progress bar by
tapping into the <b>UploadCtl_UploadProgress</b> and <b>UploadCtl_WaitingForReply</b>
events.
<p>For the complete list of events supported by XUpload, see <b>Object
Reference</b> below.</blockquote>


<font color="#000099"><B>Using XUpload in VB</B></font>

<blockquote>Run Visual Basic, open or create a project, and go to Projects/Components.
Check the box next to <b>"Persits Software XUpload Control"</b>, then click
OK. The control's icon (blue dotted square) appears on the VB Toolbox.
Use XUpload as you would any VB control. XUpload's properties can be set
using VB's standard Properties panel, or XUpload's custom property sheet.
The latter can be invoked by right-clicking on the control and selecting
"Properties" from the context menu or double-clicking the word<i> (Custom)</i>
in the VB Properties panel.
<p><img SRC="shot2.gif" height=279 width=433></blockquote>

<blockquote><font color="#000000">The property sheet can also be invoked
programmatically by calling the <b>DisplayProperties</b> method.</font></blockquote>


<font color="#000099"><B>Using XUpload as a Server Component</B></font>

<blockquote>XUpload can work as a server component that can be used in
an ASP environment. The following sample ASP code uploads two files from
one server (where it is installed) to another (where file capture script
is installed):
<br>&nbsp;
<table BORDER CELLSPACING=0 COLS=1 WIDTH="53%" BGCOLOR="#FFFFCC" >
<tr>
<td><font face="Courier New,Courier"><font size=-1>&lt;%</font></font>
<br><font face="Courier New,Courier"><font size=-1>Set XUpload = Server.CreateObject("Persits.XUpload")</font></font>
<br><font face="Courier New,Courier"><font size=-1>XUpload.Server = "192.168.1.15"</font></font>
<br><font face="Courier New,Courier"><font size=-1>XUpload.Script = "/xupload/uploadscript.asp"</font></font>
<p><font face="Courier New,Courier"><font size=-1>' Specify files to upload</font></font>
<br><font face="Courier New,Courier"><font size=-1>XUpload.AddFile "d:\somefile.txt"</font></font>
<br><font face="Courier New,Courier"><font size=-1>XUpload.AddFile "d:\about.txt"</font></font>
<p><font face="Courier New,Courier"><font size=-1>' Perform the upload</font></font>
<br><font face="Courier New,Courier"><font size=-1>XUpload.Upload</font></font>
<p><font face="Courier New,Courier"><font size=-1>' Display the reply</font></font>
<br><font face="Courier New,Courier"><font size=-1>Response.Write "Reply
from the Server was: " &amp; XUpload.ServerReply</font></font>
<br><font face="Courier New,Courier"><font size=-1>%></font></font></td>
</tr>
</table>

<p>A more detailed example can be found in the sample file <b>ServerComponent.asp</b>.
<p>NOTE: The XUpload methods <b>Select</b>, <b>Remove</b>, <b>RemoveHighlighted</b>,
and <b>DisplayProperties</b> involve XUpload's GUI and may not be called
when the control is used as a server component. The methods <b>AddFile</b>,
<b>AddFolder</b>,
<b>RemoveAll</b>,
<b>Upload</b>,
<b>AddFormItem,
RemoveAllFormItems</b> and <b>MakeHttpRequest</b> are allowed. For more
information on the <b>MakeHttpRequest</b>, see section <i>Complimentary
Features</i>.</blockquote>


<font color="#000099"><B>Using XUpload to Upload Files Directly from Windows
File Explorer</B></font>

<blockquote>A shell extension is a Win32 application that, among other
things,&nbsp; adds a custom menu item to the context menu displayed by
File Explorer when a user right-clicks on a file or selection of files.
When the user selects this menu item the shell extension (or some other
application) opens up and performs a certain task on the selected file(s).
For example, WinZip and Norton AntiVirus work as shell extensions.
<p>XUpload is also capable of acting as a shell extension which allows
you to select files for uploading directly from Windows File Explorer.
To register XUpload as an active shell extension, execute the following
command from the MS DOS prompt or Start/Run box:
<p><b>c:\path\XUploadShell.exe -RegServer</b>
<p>This command is silent and generates no feedback to the user. Once this
is done, you can fire up File Explorer, select a few files and right-click
on them. The context menu will now look similar to this:
<p><img SRC="imageODJ.JPG" height=336 width=344>
<br>&nbsp;
<p>When you select the <b>"Upload with XUpload"</b> item, a dialog-based
application titled "XUpload Shell Application" comes up which contains
the XUpload control populated with the selected files, and the buttons
"Select", "Remove", "Remove All", "Upload", "Settings" and "Close". This
application is <b>XUploadShell.exe </b>which we have just used to register
the shell extension.
<p>When you click on "Settings", the XUpload property sheet comes up which
allows you to specify your upload settings. When you exit the dialog your
settings are saved in the system registry under the key <b>HKEY_LOCAL_MACHINE\Software\Persits
Software\XUpload\Shell Extension</b> and used the next time you invoke
the extension. To upload the selected files, simply click on the Upload
button or select "Upload" from the XUpload control's popup menu..
<p>To remove the XUpload Shell Extension from your system, execute the
command
<p><b>c:\path\XUploadShell.exe -UnregServer</b>
<p>Unregistering the shell extension does not affect the XUpload control.</blockquote>


<font color="#000099"><B>Complimentary Features</B></font>

<blockquote><font color="#000000">XUpload's <b>MakeHttpRequest</b> method
allows your ASP or VB application to perform arbitrary HTTP requests such
as POST and GET. The method returns the output returned from the server
as a result of the request. The method can optionally save the output in
a file.</font>
<p><font color="#000000">The following code sample performs a POST to a
remote server and returns the result to the user:</font>
<br>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=2 COLS=1 WIDTH="80%" BGCOLOR="#FFFFCC" >
<tr>
<td><font face="Courier New,Courier"><font color="#000000"><font size=-1>&lt;%</font></font></font>
<br><font face="Courier New,Courier"><font color="#000000"><font size=-1>Set
XUpload = Server.CreateObject("Persits.XUpload")</font></font></font>
<br><font face="Courier New,Courier"><font color="#000000"><font size=-1>XUpload.Server
= "www.myserver.com"</font></font></font>
<br><font face="Courier New,Courier"><font color="#000000"><font size=-1>XUpload.Script
= "/mydir/myscript.asp"</font></font></font>