Document and Attachment Upload

One common task you will perform with mail messages or documents is uploading attachments or a document directly. To make this functionality easier for you, the WSS Forms Renderer includes the ability to upload a document as a freedoc or attachment on an item. You therefore do not have to buy or create an upload component to upload files using a browser to your Exchange Server.

The first type of upload we will look at is document upload. This type of upload places the document directly in the folder as a standalone document and not as an attachment to an item. Using this method, you can quickly have users upload their documents to a document repository application or some other type of document-centric application. When the user clicks on the document in a user interface such as Microsoft Outlook or OWA, the document will open directly. Also, if the document uploaded is a Microsoft Office document, Exchange will promote all the Office document properties, such as author, number of words, last saved time, and edit time to fields in the database. This means that you can sort , group , and filter as well as add these Office document properties to your views.

The only caveat about property promotion is that it is only property promotion. Exchange does not demote the properties back into the document if you change those properties using ADO or WebDAV. The only way to get new values into your Office document properties is to use the object model or user interface of the Office application that created the document. When you place the document in Exchange again, those new values will be promoted.

You implement document upload by setting the encoding type of your HTML FORM element to be multipart/form-data and by placing a HTML INPUT element on your form that specifies the FILE type for that INPUT element. When you use the FILE type, the browser will automatically display a browse button so a user can browse his local drive for the file path rather than having to manually type the file path into the input box. Be sure to name your FILE INPUT element DOCUMENTBODY . This tells the WSS Forms Renderer that the file being uploaded should be placed into Exchange as a standalone document.

An example will make this clearer. The Training application uses the document upload capabilities of WSS Forms in two places. First, instructors can tape a class in Audio Video Interleave (AVI), Windows Media, or Quicktime format and upload that recording as an on-demand version of the class for students that could not attend a class. This means that any student can view this on-demand version from any computer at any time. To place the on-demand version into Exchange and associate the file with the course, the Training application uses the WSS Forms document upload capabilities. Figure 20-6 shows the user interface for uploading an on-demand version of a course.

Figure 20-6: Uploading an on-demand version of a course using the WSS Form document upload

A more interesting example is uploading course materials for a course. If instructors want to make the course materials available, they can use the file share that the application creates. However, the more common way to upload course materials is by using a Web browser. Again, the application uses the document upload capabilities of WSS Forms. As Figure 20-7 shows, the course materials portion also uses the new WSS view control to display the list of course materials in the folder. You'll see how to create views using this control later in the chapter.

Figure 20-7: Uploading course materials in the Training application

Here is some of the code from the course materials page in the Training application:

 <form enctype="multipart/form-data" id="theForm1" name="theform1"       method="post" class="form" actionspec="./">     <B>Use the following text box to enter a path to a new course material         to upload:     </B><BR><BR>     <input type=file value="Add new course material" class=field            id=doc name="DOCUMENTBODY" size=70>     <BR><BR>     <input type="submit" id="submitfilepathbutton" value="Submit"            onclick="VBScript:ValidateUpload">&nbsp;&nbsp;     <input type="button" id="cancel" value="Close"            onclick="javascript:window.close();"> </form> <script language="VBScript">     Sub ValidateUpload()         'Make sure that there is something in the path!         If document.all.doc.value = "" Then             MsgBox "You must enter a valid path in the text box!"             window.event.returnValue = false         End If     End Sub </script> 

In the code, you can see an HTML form that has its enctype set to multipart /form-data . Also, the form contains an INPUT element on the file type with the name equal to DOCUMENTBODY to specify that the file should be uploaded as a standalone document. That's all you need to do to get started with document upload using WSS Forms. Note, however, that your form must reside in Exchange and the document must be uploaded to Exchange. You cannot use this technique for forms that run outside of Exchange folders, nor can you upload documents that upload into non-Exchange sources such as the file system.

Also note that a form cannot have multiple DOCUMENTBODY inputs. Also, if you mix and match document upload with attachment upload in the same form, the attachment will be ignored and the document upload will win.

Attachment Upload Support

WSS Forms supports placing multiple documents into a single item. As part of its attachment support, WSS Forms provides three key services: the ability to upload attachments, the ability to delete attachments, and the ability to render an attachment well (described shortly) that allows your application to list and select attachments.

Uploading Attachments

Attachment upload is similar to document upload in that you set your form encoding to multipart/form-data and you use the FILE input type. The main difference is that instead of naming your FILE input type DOCUMENTBODY , you name it ATTACHMENT . Unlike document upload, attachment upload supports multiple FILE inputs in a single form. All files will be attached to the same item in Exchange. To distinguish between multiple attachments, Exchange adds the name of the original file to the item and creates a unique URL for each attachment. For example, if you upload an attachment from c:\my documents \mydocument.doc, the name of the attachment will be mydocument.doc. The URL to the attachment might then be something like http://server/public/documents/item.eml/1_multipart_xF8FF_2_mydocument.doc .

The following code shows an example of adding attachment upload to your form:

 <form method="POST" enctype="multipart/form-data" class="form"       name="theform" actionspec="%dataurl%?cmd=contents">     <Input type="file" name="ATTACHMENT" size="20" class="field"            form="theform"> </form> 

Attachment Wells

Now that we've uploaded an attachment to an item, we need a way to display not only that attachment but any attachments in the item. You don't have to write code to do this because WSS Forms includes the ability to display an attachment well. An attachment well is just an interface that allows the user to work with the attachment collection for the item. It is optional for your applications. The attachment well can list the attachments in both read-only and editable form, provide hyperlinks to the attachments so the user can open them, and provide an interface so the user can select attachments for deletion. The interface is also customizable.

You add an attachment well to your form by simply creating a DIV element and naming the CLASS of that DIV attachmentWell . When WSS Forms renders that DIV , it generates an HTML 3.2 table containing the attachments on the form. This HTML table can contain different elements in its cells , depending on the formatting options you select for the attachment well. Table 20-6 lists the attachment well attributes you can specify.

Table 20-6: Attachment Well Attributes

Attribute	Description
Cols	Specifies how many attachments to list in a single row before starting a new row. The default value is 1.
Spacing	Specifies the spacing between attachments. This attribute directly corresponds to the CellSpacing attribute of your HTML table. The default value is 15.
IncludeDelete	If this attribute is set to 1, the renderer will insert a check box into the cell to allow the user to select the attachment for deletion. The default value is 0, which means that deletion is not enabled by default.
Icon	If this is set to small , the renderer will insert an IMG tag into the cell for the small icon for the file type. The renderer uses the icon images included with OWA. If you set this property to large , the renderer will insert an IMG tag to a large icon for the specified file. If you specify anything besides these two values, the renderer will assume that you are specifying the URL to a custom icon for the attachment. This URL can be absolute or relative. By default, no image is displayed in the attachment well.
IncludeLink	If this is set to 1 , a hyperlink to the attachment will be added for the user to open the attachment. A value of means that no hyperlink is added. The default value is 1 .
AttachStyle	Specifies the HTML style element for the TD element for the table row. For example, a value of color :blue turns into the HTML style="color:blue".
AttachClass	Sets the Cascading Style Sheet (CSS) class for the TD element for the table row. For example, a value of mycustomclass turns into the HTML class="mycustomclass".
Target	Specifies the HTML target for the attachment link. For example, you can specify _blank to open in a new window or _self to open in the same window.

The following are examples of markups that use the attributes specified in the table. Figure 20-8 shows an HTML page with an attachment well in action.

Figure 20-8: A rendered attachment well for an item in Exchange

• Read-only attachment well     <DIV Class="AttachmentWell">

• Read/write attachment well     <DIV Class="AttachmentWell" Icon="Small" IncludeDelete="1">

• Read/write attachment well that opens the attachment in a new window     <DIV Class="AttachmentWell" Icon="Small" IncludeDelete="1" Target="_blank">

Deleting an Attachment

If you look at the rendered code for the attachment well when you specify a value of 1 for IncludeDelete , you will see that for each attachment there is a check box named http://schemas.microsoft.com/exchange/nosave/deleteattach , which is the URL to the attachment. You delete an attachment by selecting this check box. When the form is posted back to the server, WSS Forms will look through the data to see if the check box is selected for the attachment; if it is, it will open the item and delete the attachment whose URL corresponds to the check box name. Using the attachment well is the easiest way to delete an attachment. You can also manually add the correct HTML elements to your own form.