First, we will look at an example UPLOADit_Realms.xml file, which holds information about the realms your users can upload files to. Here is the example realm file we will be using for this chapter:
- <UPLOADit>
- <defaultsysadmin>webmaster@mydomain.com</defaultsysadmin>
- <defaultresulturl>http://www.mydomain.com/thanks.htm</defaultresulturl>
- <realm name="test1">
- <path>/UPLOADit/test1/</path>
- <database>mydb.fp5</database>
- <script>UPLOADit Test1 Realm</script>
- </realm>
- <realm name="test2">
- <path>/UPLOADit/test2/</path>
- <database>mydb.fp5</database>
- <script>UPLOADit Test2 Realm</script>
- </realm>
- </UPLOADit>
Here is an example web page you could use to upload files to an UPLOADit server that was running with the above UPLOADit_Realms.xml file:
- <html>
- <head>
- <title>UPLOADit test</title>
- </head>
- <body>
- <form name="UPLOADit_Form" method="post" enctype="multipart/form-data" action="http://www.mydomain.com:8080/test1/">
- <p>Please select a file and press the submit button.</p>
- <p><input type="file" name="UPLOADit_File"></p>
- <p><input type="submit" value="Submit"></p>
- </form>
- </body>
- </html>
First, look at the <form> tag on Line 6. If you have worked with HTML web forms before, you are probably familiar with some of the attributes in this tag, but others, like the "enctype" attribute, may not be familiar at all. The "name" attribute is simply the name of the form object on your webpage. You can give it any name you want, or just completely omit the name if you do not need to use it. The "method" attribute must be set to "post" so that the web browser will send the data from your form (including your file) to the plug-in in a way that the plug-in can understand it. The "enctype" attribute must be set to "multipart/form-data" so that the web browser will send the data from your form (including your file) to the plug-in in a way that the plug-in can understand it.
The "action" attribute tells the web browser what action to take when the user presses the "submit" button on the form. This is usually where you see a URL to a CGI program on a web server to do something with the data from the form. UPLOADit itself acts as the CGI program here, so all you need to do is specify the URL to your UPLOADit server. This must be a full URL and unless you have your UPLOADit server listening on the default HTTP port (port 80), you must specify the port number as well. The first folder (directory) name in the URL needs to be the name of the realm the file will be uploaded to. After that, you can optionally specify subfolders inside the realm's path to upload the actual file into. So, the action from the example form above on Line 6 is this:
- http://www.mydomain.com:8080/test1/
The first part is the domain name (or IP address) and TCP/IP port of the computer running your UPLOADit server. In this example, the computer is at the domain name "www.mydomain.com" and the UPLOADit server is listening on port 8080. The last part is the name of the realm to which this file is being uploaded; the "test1" realm. From the example UPLOADit_Realms.xml file above, we know that if a user uploads a file to the "test1" realm, the file will end up in the "test1" folder inside the "UPLOADit" folder on the root of the main hard drive on the UPLOADit server. For example, if someone uploaded a file named "myimage.jpg", the file would be uploaded to "C:\UPLOADit\test1\myimage.jpg" on a Windows machine or "/UPLOADit/test1/myimage.jpg" on a Mac OS X machine.
As mentioned above, you can optionally specify subfolders inside the realm's path to upload the actual file to. Take for example this URL:
- http://www.mydomain.com:8080/test1/newfiles/monday/
If a user submitted a form with the above URL in the "action" attribute of the form, and they were uploading a file named "flower.jpg", the file would be uploaded to "/UPLOADit/test1/newfiles/monday/flower.jpg" on a Mac OS X machine (or "C:\UPLOADit\test1\newfiles\monday\flower.jpg" on a Windows machine). If either the "newfiles" or "monday" subfolders did not exist prior to the user uploading the file, the UPLOADit server will create them on the hard drive and then save the file inside.
Now that you understand the <form> tag, look at the <input> tags on Lines 8 and 9. Our example only has two <input> tags.
The first <input> tag has a "type" of "file", which may be new to you. When you have a "file" type <input> tag, the web browser will usually display a text field followed by a button that says "Browse..." or "Choose a File...". When the user presses the "Browse..." or "Choose a File..." button, the web browser will display a standard open file dialog where they can choose a single file. After choosing the file and closing the dialog, the filename will show up in the text field next to the "Browse..." or "Choose a File..." button. The "name" attribute for your "file" type <input> tag can be anything of your choosing, but you must give it a name if you want to retrieve the path to the file into your database. If you want to allow your users to upload more than one file at a time, simply include more than one of these "file" type <input> tags, and make sure that the "name" attributes of each of them are unique.
If you have worked with HTML web forms before, you should be able to recognize the second <input> tag. The second <input> tag has a "type" of "submit" and a "value" of "Submit". This will display a submit button to the user on the web page and it will display the word "Submit" on the button. When the user presses this button, the web browser will submit the form to your UPLOADit server.
So, after the user selects a filename and presses the "Submit" button on the form, the browser will connect to your UPLOADit server and submit the form data, including the file, to the plug-in. The plug-in will read in the data from the browser and save the file to the /UPLOADit/test1/ folder on your hard drive (Figure 2.1; Line 5). It will then call the "UPLOADit Test1 Realm" script in the "mydb.fp5" database to inform your database that a user has uploaded a file (Figure 2.1; Lines 6 and 7). The database then can read in the information about the upload (like the file name of the file), and then it must release the web browser with the "Upld-ReleaseClient" function. (For more information about setting up your UPLOADit script, please see Chapter 3 of this documentation.) The plug-in will then redirect the web browser to the Result URL that is defined. In this case, it would redirect the web browser to http://www.mydomain.com/thanks.htm (Figure 2.1; Line 3).
You may be wondering what else you can add to the web form. Look at this example web form with more information in it:
- <html>
- <head>
- <title>UPLOADit test</title>
- </head>
- <body>
- <form name="UPLOADit_Form" method="post" enctype="multipart/form-data" action="http://www.mydomain.com:8080/test2/new/02_04/">
- <input type="hidden" name="id" value="392">
- <input type="hidden" name="UPLOADit_Result_URL" value="http://www.mydomain.com/specialthanks.htm">
- <p>Please fill in your First and Last Name, then select a file, and then press the submit button.</p>
- <p>First Name: <input type="text" name="FirstName"></p>
- <p>Last Name: <input type="text" name="LastName"></p>
- <p>File to Upload: <input type="file" name="UPLOADit_File"></p>
- <p><input type="submit" value="Submit"></p>
- </form>
- </body>
- </html>
The first thing to look at is the "action" attribute in the <form> tag on Line 6. You will note that this form will be submitted to the "test2" realm and that it wants to upload the files to the subfolders "/new/02_04/". Based on the UPLOADit_Realms.xml file in Figure 2.1, if a user uploaded a file named "car.gif", the file would be stored on the hard drive at "C:\UPLOADit\test2\new\02_04\car.gif" on a Windows machine or "/UPLOADit/test2/new/02_04/" on a Mac OS X machine.
The second thing to notice is that there are a couple of "hidden" type <input> tags in the form. These form elements will not be displayed to the user on the web page, but when the form is submitted, you can retrieve the values from those form elements just like any other form element. When a user submits this form, the plug-in would call the "UPLOADit Test2 Realm" script in the "mydb.fp5" database (Figure 2.1; Lines 11 and 12). That script can then use the "Upld-GetFieldValue" function with the parameter "id" to retrieve the value "392" from the form (Line 7). This is what it would look like in your FileMaker script:
- Set Field [id_from_form, External("Upld-GetFieldValue", "id")]
The second "hidden" type <input> tag on Line 8 has the name "UPLOADit_Result_URL". If you supply a form element with this name in your form, the plug-in will redirect the web browser to that result URL instead of what is defined in the UPLOADit_Realms.xml file. Based on the UPLOADit_Realms.xml file from above, when someone submits a file to the "test2" realm, it would normally redirect the web browser to http://www.mydomain.com/thanks.htm (Figure 2.1; Line 3). However, since this "hidden" type <input> tag with the name "UPLOADit_Result_URL" has been defined, the web browser would be redirected to http://www.mydomain.com/specialthanks.htm. Additionally, you can use the "Upld-SetResultURL" function in your FileMaker script to redirect the web browser to a different location than what is defined in the UPLOADit_Realms.xml file.
The third thing to notice about this new web form are the two "text" type <input> tags on Lines 10 and 11. These tags ask the user to input their First and Last Name along with the file they are uploading. To retrieve the values from these fields, you would use the "Upld-GetFieldValue" function like so:
- Set Field [First_Name, External("Upld-GetFieldValue", "FirstName")]
- Set Field [Last_Name, External("Upld-GetFieldValue", "LastName")]
One last thing to keep in mind is that just because you are submitting these forms through the UPLOADit plug-in, it does not mean that the actual web page that contains the form cannot be served up through the Web Companion, Lasso, or some other dynamic database middle-ware. For an example of this, please see the Resume Upload Example and Chapter 6 of this document which explains that example.