UPLOADit
A FileMaker Pro Plug-in that allows you to upload files from your web browser.
|
Features
- Define multiple realms for multiple solutions.
- Take advantage of the multi-threaded operation, which allows fast multi-user uploads.
- Allows multiple file uploads from one web form.
- Pull in information about the file plus any other value from your web form right into FileMaker.
- Change the URL for the response page dynamically.
- Block Single IP Addresses and Ranges of IP Addresses.
- Limit the size and number of the uploaded files.
- Password protect your file uploads.
|
Possible Uses
- Upload images to your web site from any web browser.
- Upload resumes or other information as a part of your online applications.
- Upload files to attach to emails in your custom web based email client (using SMTPit and POP3it).
- Upload homework or research papers as part of your class website.
|

Documentation Overview
The following is a description of each section of the UPLOADit documentation.
Overview of Chapters
The following is an overview of the chapters in the UPLOADit documentation.
Chapter 1: Introduction, Installation, and ConfigurationThis chapter will introduce you to the UPLOADit plug-in, show you how to install the plug-in, and show you some of the Configuration Dialog settings.
Chapter 2: How to set up your Web Page FormThis chapter explains how to set up your web page form to allow your users to upload files to your computer.
Chapter 3: How to set up your UPLOADit FileMaker ScriptThis chapter explains how to set up a FileMaker script in your database that UPLOADit will run when a user uploads a file to your UPLOADit server.
Chapter 4: File Upload ExampleThis chapter explains the File Upload Example solution that comes with the UPLOADit plug-in. This example solution allows you to upload any type of file to your FileMaker Web folder, and then shows you a result page that allows you to view or download the file you uploaded.
Chapter 5: Image Import ExampleThis chapter explains the Image Import Example solution that comes with the UPLOADit plug-in. This example solution allows you to upload a GIF or JPEG image, which will be imported into a container field in the database, and then display a web page showing the image you uploaded.
Chapter 6: Resume Upload ExampleThis chapter explains the Resume Upload Example solution that comes with the UPLOADit plug-in. This example solution first asks a web user for their First and Last Name, and then allows them to upload a resume to the UPLOADit server. It places the user's resume in a folder named with their first name inside of a folder named with their last name.
Chapter 7: IP Address CheckingThis chapter explains how UPLOADit checks IP addresses against the Allow and Deny IP lists you can define for your Realms.
Chapter 8: Credits & Contact Information
Overview of Appendixes
The following is an overview of the appendixes in the UPLOADit documentation.
Appendix A: FunctionsThis appendix lists and describes all the UPLOADit functions available to your FileMaker scripts. Each function lists a few examples, related functions, and possible error responses.
Appendix B: Realm TagsThis appendix lists and describes all the UPLOADit Realm Settings you can define for your Realms. These settings can be used in the UPLOADit_Realms.xml file, the "Upld-DefineRealmXML" function, and the "Realms" tab of the Configuration Dialog.
Appendix C: Function Error ResponsesAppendix D: Browser ErrorsThis Appendix lists and describes the web page errors that UPLOADit will possibly send to your web browser when you try to upload files to it. Each of the errors below are categorized by the main error message. The description then contains the secondary (longer) error message followed by possible reasons for receiving the error.
Appendix E: UPLOADit Flow ChartFollowing is general view of how a file gets from the browser to FileMaker.
Appendix F: GlossaryHere are several definitions that you may find helpful while reading the UPLOADit documentation.
Overview of Figures
The following is an overview of the figures in the UPLOADit documentation.
Chapter 1
Chapter 2
Chapter 3
Chapter 4
Chapter 5
Chapter 6
Chapter 7
Appendix C

Chapter 1
Introduction, Installation, and Configuration
This chapter will introduce you to the UPLOADit plug-in, show you how to install the plug-in, and show you some of the Configuration Dialog settings.
Introduction
Welcome to UPLOADit! This plug-in will allow your users to upload any file they want from their computer to your FileMaker computer using only their web browser. There are several reasons why you may want to do this. Here are some examples:
- You may want to allow people to upload images to your web server and immediately be able to display those images on your web site.
- You may want to allow people to upload resumes to your web server as part of an employment web site.
- You may want to allow people to upload files they wish to attach to emails using your custom web based email client (using SMTPit and POP3it).
- You may want to allow students to upload their homework, essays, term papers, or research papers to your class web site.
There are probably several other examples you can think of for allowing people to upload files to your web site.
So, you may be wondering how this plug-in works. The concept is actually fairly simple. UPLOADit is basically a mini web server that allows a web browser to submit an HTML form to it. One of the form elements can be a "file" element that allows the user to browse their hard drive for a file to upload. When they submit the form, the web browser connects to UPLOADit and sends all of the form data, including the file the user chose, to the plug-in. The plug-in saves the file out to the hard drive and then calls a FileMaker script in your FileMaker database to inform you that someone just uploaded a file. Your FileMaker script then can read in the form values and ask UPLOADit for the path and file name of the file the user just uploaded. At this point, you can manipulate the uploaded file, if you want, by copying it, moving it, renaming it, deleting it, etc. Your FileMaker script then instructs UPLOADit to redirect the user's web browser to a final response page. To see a visual representation of this, please see our flowchart in Appendix E.
Installation
Installing UPLOADit is very easy. If FileMaker Pro is open, close it. Next, locate the folder on your hard drive that contains your FileMaker Pro application. For Macintosh, this is usually in the "Applications" folder; while on Windows, it is usually in the "Program Files" folder. Next to the FileMaker Pro application, you should see a folder named FileMaker Extensions (on Macintosh; See Figure 1.1) or System (on Windows; See Figure 1.2). Copy the plug-in file into this folder to install it into FileMaker Pro.
Figure 1.1 Installing on Macintosh
Figure 1.2 Installing on Windows
After installing the plug-in as described above, you can open FileMaker Pro again and set the default preferences if you wish. To do this on Windows, go to the "Edit" menu, select "Preferences" and then select "Application". This should bring up the "Application Preferences" dialog. Next, click on the "Plug-ins" tab, and then double-click the UPLOADit plug-in. On Mac OS X, go to the "FileMaker Pro" menu, select "Preferences" and then select "Application". This should bring up the "Application Preferences" dialog. Next, click on the "Plug-ins" tab, and then double-click the UPLOADit plug-in.
Configuration
Basics
Once the Configuration Dialog is open, click the Basics tab where you can set the following values. Port is where you specify the TCP/IP port number you want your UPLOADit server to listen for connections on. The valid TCP/IP port numbers are in the range from 0 to 65535, though you will probably not be able to use a port number less than 1024 on Mac OS X.
Max Connections is the maximum number of simultaneous connections your UPLOADit server will accept at any given time. The Automatically Start Server check box allows you to start your UPLOADit server automatically when FileMaker Pro is opened.
Figure 1.3 Basics Tab
Realms
The Realms Tab allows you to create and edit your realms. See Appendix B for more information about the realm settings you can define here.
Figure 1.4 Realms Tab
Advanced
The Advanced Tab holds settings that you will most likely never need to change. You should not change any of the settings on this tab unless you know exactly what you are doing, or if our tech support team instructs you to change the settings.
About
The About Tab reports which version of UPLOADit you are using, who the plug-in is registered to, and how many seats the plug-in is registered for. You can also use the "Upld-Version" function to bring up the Configuration Dialog by passing the function the string "CONFIGURE" or the string "ABOUT". To make sure that you have the most recent version of UPLOADit, please visit our website (http://uploadit.cnsplug-ins.com/)
Figure 1.5 About Tab
Registration
When you decide to purchase UPLOADit, you can obtain a license from our secure online purchase form at https://secure.comm-unity.net/products.htm?product=UPLOADit. Once you have purchased a license to use UPLOADit, we will send you a registration code to register your copy of the plug-in. To do that, open any of the example databases and press the "Register UPLOADit" button and enter your registration information. You can also register by opening the configuration dialog, and clicking on the "Registration" button.

Chapter 2
How to set up your Web Page FormThis chapter explains how to set up your web page form to allow your users to upload files to your computer.
Example Web Page Form
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:
Figure 2.1 Example Realm XML
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:
Figure 2.2 Example HTML Page
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:
Figure 2.3 Action Attribute
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:
Figure 2.4 Example URL
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:
Figure 2.5 Example HTML Page 2
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:
Figure 2.6 Upld-GetFieldValue Example
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:
Figure 2.7 Upld-GetFieldValue Example 2
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.

Chapter 3
How to set up your UPLOADit FileMaker ScriptThis chapter explains how to set up a FileMaker script in your database that UPLOADit will run when a user uploads a file to your UPLOADit server.
Example UPLOADit Script
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:
Figure 3.1 Example Realm XML
Second, here is an example web form page that we will base the rest of the chapter on:
Figure 3.2 Example HTML Page
When a user presses the submit button on the above form, their web browser will submit each of the values from the <input> tags, plus whatever file they have selected, to the UPLOADit server. After the UPLOADit server has received the entire file and saved it to the hard drive in the /UPLOADit/test/ folder (Figure 3.1; Line 5), it will pause the user's web browser and will call the "UPLOADit Test Realm" FileMaker script in the "mydb.fp5" database (Figure 3.1; Lines 6 and 7). This FileMaker script should retrieve all the values from the <input> tags it needs, including the name of the file, and then it must call the "Upld-ReleaseClient" function to un-pause the user's web browser and to redirect it to its final location, the Result URL.
Here is an example script that does that:
Figure 3.3 Example Script
Line 1 of this script creates a new record in the database to store information about the newly uploaded file. Lines 2, 3, and 4 retrieve the values from the <input> tags with the names "id", "First_Name", and "Last_Name" respectively. Line 5 uses the "Upld-GetFieldValue" function to retrieve the filename of the file that was uploaded. To do this, you specify the name of the "file" type <input> tag from the form. Note that instead of retrieving the actual file into your database, this will simply return the path and file name to the location on your hard drive where UPLOADit saved the file. Also note that if someone uploads a file with a file name that is the same as an existing file on your server, and you have the plug-in set to make the file name unique, this function will return that unique file name to you. (In other words, if the plug-in needs to rename the file that someone uploads, it will give you the path to the renamed file.) Line 6 uses the "Upld-ReleaseClient" function to release the user's web browser and to redirect it to the Result URL. You must do this or the user's web browser will either sit there forever doing nothing or eventually return an error to the user saying that the web server (UPLOADit in this case) is not responding. The last line simply exits the record so that it will commit the new data.
In Figure 3.2 above, we included a hidden field named "id" (Line 7), which could hold a unique value for a record to update with information. Using that id to update a specific record requires our FileMaker script to perform a find operation so that we can update the correct record. Here is an example script that does that:
Figure 3.4 Example Script with Find
Line 1 of this script turns on the Error Capture mode that allows the script to intercept any error messages that might pop up during the script. In this script, it is used to make sure that if the Find operation does not find the record, FileMaker will not pop up the "No Records were found" dialog, but instead the script will handle that error itself. Line 2 of this script enters Find Mode so that we can find the record we are looking for. Line 3 of this script sets the "id" field with the value from the web form. (Remember that since we are in Find Mode, this is the same as someone using FileMaker to enter Find Mode and type a value into the "id" field.) Line 4 then tells FileMaker to perform the Find to see if it can find the record we are looking for (the record where the id field matches what was in the web form).
The script now takes two courses of action depending on whether or not FileMaker could find the record we are looking for. If FileMaker can find the record we are looking for, the Status(CurrentError) function will return 0 (zero), meaning there was no error, and the script can then extract the other web form values into the fields in the found record (Lines 6, 7, and 8). If FileMaker cannot find the record we are looking for, the Status(CurrentError) function will return a non-zero value (probably 401), so Lines 10 and 11 will run. Line 10 simply shows all the records in the database instead of leaving it in a Found Set of 0 records. Line 11 uses the "Upld-SetResultURL" function to set an alternate Result URL for UPLOADit to redirect this user's web browser to. This page could say something like "The record with the id you specified could not be found".
Line 13 of the script will then release the user's web browser and redirect it to its final location, either http://www.mydomain.com/thanks.htm, if the script found the record in the database, or if the script could not find the record in the database, http://www.mydomain.com/error.htm. Line 14 exits the record to commit it, and Line 15 turns Error Capture back off so that FileMaker will begin displaying error dialogs again if it needs to.
For more examples of UPLOADit scripts, please see the example solutions that came with the UPLOADit plug-in, and the chapters in this documentation that explain those examples.

Chapter 4
File Upload ExampleThis chapter explains the File Upload Example solution that comes with the UPLOADit plug-in. This example solution allows you to upload any type of file to your FileMaker Web folder, and then shows you a result page that allows you to view or download the file you uploaded.
Installing the Example
Installing this example solution is easy. In the UPLOADit archive you downloaded, you should find a "File Upload Example" folder. Inside the "File Upload Example" folder, you should see a database named "FileUpload.fp5" and a subfolder named "FileUpload". Copy the entire "FileUpload" folder into the "Web" folder inside your FileMaker Pro Application Folder. Then double-click the "FileUpload.fp5" database to open it in FileMaker.
FileMaker should now be open and the "FileUpload.fp5" database should be loaded. You now need to check the Web Companion settings to make sure they are set correctly to use this example solution. So, if you are on Windows, go to the "Edit" menu, select "Preferences", and then select "Application". If you are on Mac OS X, go to the "FileMaker Pro" menu, select "Preferences", and then select "Application". You should now be looking at FileMaker Pro's Application Preferences dialog. Switch to the "Plug-ins" tab and you should see a list of installed plug-ins. You should at least see the UPLOADit plug-in and the Web Companion plug-in in the list. If you do not see the UPLOADit plug-in, please follow the instructions in Chapter 1, which tells you how to install the UPLOADit plug-in. If you do not see the Web Companion plug-in, please install it from your FileMaker Pro CD.
Find the Web Companion plug-in in the list and make sure there is a checkmark next to it (meaning it is active). If there is no checkmark, click in the square next to it to make the checkmark appear and to make the plug-in active. Next select the Web Companion plug-in and press the "Configure..." button. You should now be looking at the Web Companion Configuration dialog. At the bottom of the dialog, make sure the "TCP/IP Port Number" is set to 80. Then press the "OK" button. The Web Companion plug-in should now be configured to work with this example solution.
Finally, just to make sure, you need to check to see if the "FileUpload.fp5" database is being shared via Web Companion. To do that, select the "FileUpload.fp5" database, go to the "File" menu, and select "Sharing...". You should now be looking at the "File Sharing for 'FileUpload.fp5'" dialog. In the second "Companion Sharing" section, make sure a checkmark appears next to "Web Companion" in the list. If there is no checkmark, click in the square next to it to make the checkmark appear. Then press the "OK" button.
The example solution is now installed and ready to test.
Testing the Example
To test the File Upload Example solution, make sure you have installed it according to the instructions above. If you have installed it properly, you should have the "FileUpload" folder inside the "Web" folder inside your FileMaker Pro application folder; you should have the "FileUpload.fp5" database opened in FileMaker Pro; you should have the Web Companion plug-in active and listening on port 80; and you should have the "FileUpload.fp5" database shared via the Web Companion.
Now that everything is installed, switch to the "FileUpload.fp5" database and press the "Start Server" button. The "Global_Result" field should update with the results:
Figure 4.1 Global_Result after Start Server script
The UPLOADit server should now be running.
Next, open up your favorite web browser and type in this URL in the location bar:
Figure 4.2 URL for FileUpload Example
Then press enter and the UPLOADit File Upload Example web page should load. Fill in a First and Last Name in the "First Name" and "Last Name" fields. Next, you should see a "Browse..." or "Choose a File..." button under the "File to Upload" heading. Press this button, and the web browser should present you with a standard Open File dialog for you to choose a file. Choose any file on your hard drive. Finally, press the "Submit" button on the web form, and the web browser will upload your selected file to the UPLOADit plug-in.
When UPLOADit receives the entire file, it will save it to the hard drive. It will then call a script in the "FileUpload.fp5" database, which creates a new record, copies the information from the web form into the fields in the database, and tells the UPLOADit plug-in that it can redirect the web browser to the "thanks.htm" page.
So, UPLOADit will redirect your web browser to the "thanks.htm" page, which will show you the information you filled into the form and will provide a link to the file you uploaded. If you selected an image or a text file or something else that the web browser can display, then clicking on the link will show you the file that you uploaded. If you selected a file that the web browser cannot display, then clicking on the link will download the file back to your computer.
You have now seen this example solution in action. Next you can see how this solution works.
Exploring the Example
Now that you have seen this example solution work, take a look back at the FileUpload.fp5 example database to see how it works. First, look at the main fields in the database:
- Global_Result
- This field is used by the Start Server and Stop Server scripts to report the results of Starting and Stopping the server.
- Full_Path
- This field holds the full path and file name of the file that is uploaded. UPLOADit gives us this when we ask for it.
- File_Name
- This is a calculation field that simply returns just the file name of the Full_Path field. We need this so that we can allow the user to display or download the file they uploaded.
- ID
- This field holds a unique id for the record. We need this so that we can redirect the web browser back to a page showing the user what they uploaded.
- First_Name
- This field holds the value the user enters on the web page form.
- Last_Name
- This field holds the value the user enters on the web page form.
- Result
- The UPLOADit script uses this field to report the results of setting the Result URL and Releasing the user's web browser.
Next, take a look at the main scripts. First, there is the Start Server script, which only has one Set Field script step in it that sets the "Global_Result" field. The calculation for the Set Field script step is this:
Figure 4.3 Start Server Set Field Calculation
The first External function call in Line 1 uses the "Upld-DefineRealmXML" function to define a realm for use with this example solution. Since this example solution allows you to upload files into a folder that is inside the Web folder inside your FileMaker application folder, this example solution sets up the realm from within the database so it can determine where your FileMaker application folder is. In all likely hood, you will know exactly where your FileMaker application folder is, so in your own solution, you will probably define your realm within the UPLOADit_Realms.xml file or with the UPLOADit Configuration Dialog. We only do it this way here because there is no way for the example solution to know beforehand where your FileMaker application folder is, and it makes installing the solution easier on you until you understand more about how UPLOADit works.
The second External function call in Line 10 uses the "Upld-Port" function to set the TCP/IP port to 8080. This port is the same as what is used in the "default.htm" file in the FileUpload folder that you will look at in a second.
The third External function call uses the "Upld-StartServer" function to start the UPLOADit server to have it listen for incoming connections.
The second main script, named Stop Server, is more simple. It too has only a single Set Field script step in it that sets the Global_Result field. The calculation for that Set Field script step is:
Figure 4.4 Stop Server Set Field Calculation
This just uses the "Upld-StopServer" function to stop the UPLOADit server.
The final main script is the script that UPLOADit calls when a user uploads a file to your UPLOADit server. This script is named "UPLOADit" and looks like the following:
Figure 4.5 UPLOADit Script
Line 1 uses the New Record/Request script step to create a new record in the database to store information about the new file the user uploaded. Lines 2, 3, and 4 call the "Upld-GetFieldValue" function to retrieve the values from the web form, including the full path and file name of the uploaded file.
Line 5 then tells UPLOADit where it should redirect the web browser to as a result of this file upload. The Result URL is set to something like:
Figure 4.6 Result URL
This will make the browser load a web page through the Web Companion that finds the record with the ID "ABCD1234" and displays the fields from that record. Line 5 also uses the "Upld-ReleaseClient" function to actually release the user's web browser and redirect it to that result page. Remember that you must always release the user's web browser, otherwise it will just sit there and do nothing, or eventually timeout and give the user an error saying something like "the server is not responding."
Line 6 in the UPLOADit script simply exits the record we created.
Those are the three main scripts in the database. Now take a look at the default.htm and thanks.htm pages in the FileUpload folder inside of the Web folder inside your FileMaker application folder. (If you have not looked at Chapter 2, "How to set up your Web Page Form", now might be a good time to read through it.)
The default.htm page has a web form in it with a <form> tag that looks like this:
Figure 4.7 default.htm Form Tag
If you have read Chapter 2, "How to set up your Web Page Form", you should see that this is set to connect to the UPLOADit server running on your machine at port 8080, and that it will upload files to the "FileUpload" realm.
The <input> tags for the form are the following:
Figure 4.8 default.htm Input Tags
The first and second <input> tags allow the user to type in their First and Last Name respectively. The third <input> tag allow the user to "Browse" for or "Choose" a file they want to upload. The last <input> tag is the Submit button they press to submit the form to UPLOADit.
When the user fills in the form, selects a file to upload, and presses the Submit button, the web browser connects to the UPLOADit server, and sends it all of the form data, including the File. UPLOADit saves the file to the hard drive and then calls the "UPLOADit" script in the FileUpload.fp5 file. That script creates a new record in your database, copies the data from the web form into the database fields, and then tells UPLOADit to redirect the browser to the "thanks.htm" page, which uses some CDML to display the data from the database fields:
Figure 4.9 thanks.htm CDML
Line 2 above provides a link to the file that the user uploaded. Lines 3 and 4 display the data from the First and Last Name that the user filled in when they submitted the web form.
That is all there is to the File Upload example solution. The next two example solutions are more advanced.

Chapter 5
Image Import ExampleThis chapter explains the Image Import Example solution that comes with the UPLOADit plug-in. This example solution allows you to upload a GIF or JPEG image, which will be imported into a container field in the database, and then display a web page showing the image you uploaded.
Installing the Example
Installing this example solution is easy. In the UPLOADit archive you downloaded, you should find an "Image Import Example" folder. Inside the "Image Import Example" folder, you should see a database named "ImageImport.fp5", a file named "UPLOADit_Realms.xml", and a subfolder named "ImageImport". Copy the entire "ImageImport" folder into the "Web" folder inside your FileMaker Pro Application Folder. Copy the "UPLOADit_Realms.xml" file to the same place you copied the UPLOADit plug-in file when you installed it. (On Windows, copy the "UPLOADit_Realms.xml" file to the "System" folder inside your FileMaker application folder. On Mac, copy the "UPLOADit_Realms.xml" file to the "FileMaker Extensions" folder inside your FileMaker Application folder.) If you have already manually edited the "UPLOADit_Realms.xml" file, then you may just want to open up the one from the Image Import Example, and copy the "ImageImport" realm into your existing "UPLOADit_Realms.xml" file instead of overwriting it with the one from the Image Import Example. Finally, double-click the "ImageImport.fp5" database to open it in FileMaker.
FileMaker should now be open and the "ImageImport.fp5" database should be loaded. You now need to check the Web Companion settings to make sure they are set correctly to use this example solution. So, if you are on Windows, go to the "Edit" menu, select "Preferences", and then select "Application". If you are on Mac OS X, go to the "FileMaker Pro" menu, select "Preferences", and then select "Application". You should now be looking at FileMaker Pro's Application Preferences dialog. Switch to the "Plug-ins" tab and you should see a list of installed plug-ins. You should at least see the UPLOADit plug-in and the Web Companion plug-in in the list. If you do not see the UPLOADit plug-in, please follow the instructions in Chapter 1, which tells you how to install the UPLOADit plug-in. If you do not see the Web Companion plug-in, please install it from your FileMaker Pro CD.
Find the Web Companion plug-in in the list and make sure there is a checkmark next to it (meaning it is active). If there is no checkmark, click in the square next to it to make the checkmark appear and to make the plug-in active. Next select the Web Companion plug-in and press the "Configure..." button. You should now be looking at the Web Companion Configuration dialog. At the bottom of the dialog, make sure the "TCP/IP Port Number" is set to 80. Then press the "OK" button. The Web Companion plug-in should now be configured to work with this example solution.
Finally, just to make sure, you need to check to see if the "ImageImport.fp5" database is being shared via Web Companion. To do that, select the "ImageImport.fp5" database, go to the "File" menu, and select "Sharing...". You should now be looking at the "File Sharing for 'ImageImport.fp5'" dialog. In the second "Companion Sharing" section, make sure a checkmark appears next to "Web Companion" in the list. If there is no checkmark, click in the square next to it to make the checkmark appear. Then press the "OK" button.
The example solution is now installed and ready to test.
Testing the Example
To test the Image Import Example solution, make sure you have installed it according to the instructions above. If you have installed it properly, you should have the "ImageImport" folder inside the "Web" folder inside your FileMaker Pro application folder; you should have copied the "UPLOADit_Realms.xml" file to the "System" or "FileMaker Extensions" folder in your FileMaker Pro application folder (or copy the "ImageImport" realm from that file into your existing "UPLOADit_Realms.xlm" file); you should have the "ImageImport.fp5" database opened in FileMaker Pro; you should have the Web Companion plug-in active and listening on port 80; and you should have the "ImageImport.fp5" database shared via the Web Companion.
Now that everything is installed, switch to the "ImageImport.fp5" database and press the "Start Server" button. The "Global_Result" field should update with the words:
Figure 5.1 Global_Result after Start Server script
The UPLOADit server should now be running.
Next, open up your favorite web browser and type in this URL in the location bar:
Figure 5.2 URL for Image Import Example
Then press enter and the UPLOADit Image Import Example web page should load. Fill in a First and Last Name in the "First Name" and "Last Name" fields. Next, you should see a "Browse..." or "Choose File..." button under the "File to Upload" heading. Press this button, and the web browser should present you with a standard Open File dialog for you to choose a file. Choose any GIF or JPEG image file on your hard drive. (For the purposes of this example, you have to select an image that is less than 1 megabyte in size. This is simply an option defined in the realm and can be changed or omitted to allow any file size. See the "Exploring the Example" section below for more information.)
Finally, press the "Submit" button on the web form, and the web browser will upload your selected file to the UPLOADit plug-in. The browser should then prompt you for a User Name and Password. Fill in anything you want for the User Name, but use "imagetest" as the password, and the UPLOADit server will allow you to upload the image.
When UPLOADit receives the entire file, it will save it to the hard drive. It will then call a script in the "ImageImport.fp5" database, which creates a new record, copies the information from the web form into the fields in the database, and tells the UPLOADit plug-in that it can redirect the web browser to the "thanks.htm" page.
So, UPLOADit will redirect your web browser to the "thanks.htm" page, which will show you the information you filled into the form, including the image that you uploaded. If you go back to FileMaker and look at the last record in the database, you should also see the image you uploaded in the container field.
You have now seen this example solution in action. Next you can see how this solution works.
Exploring the Example
Now that you have seen this example solution work, take a look back at the ImageImport.fp5 example database to see how it works. First, look at the main fields in the database:
- Global_Result
- This field is used by the Start Server and Stop Server scripts to report the results of Starting and Stopping the server.
- Full_Path
- This field holds the full path and file name of the file that is uploaded. UPLOADit gives us this when we ask for it.
- First_Name
- This field holds the value the user enters on the web page form.
- Last_Name
- This field holds the value the user enters on the web page form.
- User_Name
- This field holds the value the user enters into the User Name/Password dialog that the web browser presents to them when they try to upload an image.
- ID
- This field holds a unique id for the record. We need this so that we can redirect the web browser back to a page showing the user what they uploaded.
- Image
- This is a container field that will hold the image the user uploads.
- Import_Result
- This field is used to report any errors that may occur when trying to import the image.
- Release_Result
- The UPLOADit script uses this field to report the results of setting the Result URL and Releasing the user's web browser.
Next, take a look at the main scripts. The first main script is the "Start Server" script, which only has one Set Field script step in it that sets the "Global_Result" field. The calculation for the Set Field script step is:
Figure 5.3 Start Server Set Field Calculation
The first External function call uses the "Upld-Port" function to set the TCP/IP port of the UPLOADit server to 8080. The second External function call uses the "Upld-StartServer" function to start the UPLOADit server.
The second main script, named Stop Server, also only has one Set Field script step in it that sets the "Global_Result" field. The calculation for that Set Field script step is:
Figure 5.4 Stop Server Set Field Calculation
This calculation uses the "Upld-StopServer" function to stop the UPLOADit server from listening for incoming connections.
Before we look at the final main script in the database, let us think about what we need to do to get the image that is uploaded into the container field in our database. When someone uploads an image, we need to create a new record in our database and store all the information from the web form in the fields in our database. For the image, though, all we are able to get is the full path and file name to the image that was uploaded. We need to import that image into our container field from the hard drive.
However, this is not as easy as it sounds because of one problem with FileMaker's Insert Picture script step: you cannot dynamically define the full path and file name of the image you want to import. So, the only way to import an image into FileMaker with a script is to either present the user at the FileMaker computer with a dialog to ask where the image is, or to always import an image from the same location on the hard drive and that has the same file name. Obviously the first option will not work because this is supposed to be a server with no user sitting at the FileMaker computer, so we have to work with the second option.
To import an image from the same location on the hard drive and with the same file name every time, we have to be able to copy the image the user uploads to a set location on the hard drive and rename it to a set name so that FileMaker will be able to import it. So, UPLOADit contains a number of "File" functions for manipulating files on your hard drive. The main "UPLOADit" script below uses these functions.
So, here is the final main script in the Image Import example database. This script is named "UPLOADit", and it is the script that UPLOADit calls when a user uploads an image to your UPLOADit server. This script looks like the following:
Figure 5.5 UPLOADit Script
Line 1 of this script uses the New Record/Request script step to create a new record to store the information the user just uploaded. Lines 2 through 5 call the "Upld-GetFieldValue" function to retrieve the First_Name, Last_Name, UPLOADit_User, and UPLOADit_File values respectively. We now have all the data from the web form.
Line 6 starts the process of importing the image into container field in our new record. This line first checks to make sure we have a path and file name in the Full_Path field. Line 7 looks to see if the file name ends in ".JPG" or ".JPEG". If this is a JPEG image, then we need to copy and rename our uploaded image to a set location on our hard drive to import the image. Since we may have done this before, we need to delete any existing import image so that we can copy the new image over. So, Line 8 checks to see if "image.jpg" exists, and if it does, Line 9 deletes the image.
Line 11 checks to make sure the Delete function did not return an error. Then, Line 12 copies the newly uploaded image to our set location on the hard drive, renaming it to "image.jpg" at the same time. Line 13 checks to make sure the Copy function did not return an error. We can now import the image.
Line 14 uses the Set Error Capture script step to allow the script to handle any errors it may generate instead of displaying an error dialog on the screen. Line 15 tells FileMaker to focus on the "Image" container field, so that Line 16 can import the image into that container field. Line 17 checks to see if FileMaker had an error importing the image, and if so, Line 18 sets our "Import_Result" field so that we can report this error back to our web user. Finally, Line 20 turns the Error Capture feature back off so that FileMaker will begin displaying error dialogs again if it needs to.
Lines 24 through 39 do the same thing as lines 7 through 22, except it is set up to import a GIF image instead of a JPEG image.
Line 45 checks to see if our "Import_Result" field has an error in it, and if it does, Line 46 sets the Result URL to an error web page that will display the error from the "Import_Result" field to the web user. If the "Import_Result" field does not contain an error, then Line 48 sets the Result URL to our "thanks" web page, which displays the information the user uploaded, including the image the user uploaded. Finally, Line 50 uses the "Upld-ReleaseClient" function to release the web browser and redirect it to its final location, and Line 51 Exits our new record.
Those are the three main scripts in the Image Import example database. Now, take a look at the "UPLOADit_Realms.xml" file inside the "System" or "FileMaker Extensions" folder inside your FileMaker application folder. If you open the "UPLOADit_Realms.xml" file in a text editor like Notepad or BBEdit®, you should see a realm defined in it that looks like this:
Figure 5.6 Image Import Realm XML
Line 1 starts with the Realm tag and gives the realm the name "ImageImport". This is the name used in the "action" attribute of the <form> tag in the "default.htm" web page as you will see below. Line 2 defines the Path where UPLOADit should place the uploaded images. It defines the path as "/UPLOADit/ImageImport/NewFiles/". On Windows, this will end up being "C:\UPLOADit\ImageImport\NewFiles\". On Mac, this will end up on the startup volume in the computer in the folder "/UPLOADit/ImageImport/NewFiles/".
Lines 3 and 4 tell UPLOADit to call the "UPLOADit" script in the "ImageImport.fp5" database when someone uploads an image. Line 5 defines a password that the user must enter before they are allowed to upload an image to the UPLOADit server. When you define a password, the web browser will prompt the user for a User Name and Password before being able to upload the data. They can enter anything they want for the "Username" field, but the password they enter must match what you have defined in the realm. Finally, Line 6 defines a Maximum File Size of "1m" or "1 megabyte". This limits the file size of the image a user can upload to 1 megabyte. If a user tries to upload an image larger than 1 megabyte, they will receive an error web page.
To finish up this example solution, take a look at the "default.htm" and "thanks.htm" web pages in the "ImageImport" folder inside of the "Web" folder inside your FileMaker application folder. (If you have not looked at Chapter 2, "How to set up your Web Page Form", now might be a good time to read through it.)
The "default.htm" page has a web form in it with a <form> tag that looks like this:
Figure 5.7 default.htm Form Tag
If you have read Chapter 2, "How to set up your Web Page Form", you should see that this is set to connect to the UPLOADit server running on your machine at port 8080, and that it will upload files to the "ImageImport" realm.
The <input> tags for the form are the following:
Figure 5.8 default.htm Input Tags
The first and second <input> tags allow the user to type in their First and Last Name respectively. The third <input> tag allows the user to "Browse" for or "Choose" the image they want to upload. The last <input> tag is the Submit button they press to submit the form to UPLOADit.
When the user fills in the form, selects an image to upload, and presses the submit button, the web browser connects to the UPLOADit server to send the data. In this example, though, we have defined a password for the realm the user must enter before being able to upload an image. So, the web browser prompts the user for a User Name and Password. If the user types "imagetest" for the Password, then UPLOADit allows the web browser to send it all of the form data, including the image. UPLOADit saves the image to the hard drive and then calls the "UPLOADit" script in the ImageImport.fp5 database (Figure 5.6; Lines 3 and 4). That script creates a new record in your database, copies the data from the web form into the database fields, imports the image into the container field, and then tells UPLOADit to redirect the web browser to the "thanks.htm" page. The "thanks.htm" page uses CDML to display the data from the database fields back to the user:
Figure 5.9 thanks.htm CDML
Lines 2, 3, and 4 display the data from the First Name, Last Name, and User Name fields respectively. Line 6 displays the image from the container field in the record.
This concludes the Image Import example solution. The next solution is a little more complicated on the web browser side to show how you can mix UPLOADit in with your other CDML web pages.

Chapter 6
Resume Upload ExampleThis chapter explains the Resume Upload Example solution that comes with the UPLOADit plug-in. This example solution first asks a web user for their First and Last Name, and then allows them to upload a resume to the UPLOADit server. It places the user's resume in a folder named with their first name inside of a folder named with their last name.
Installing the Example
Installing this example solution is easy. In the UPLOADit archive you downloaded, you should find a "Resume Upload Example" folder. Inside the "Resume Upload Example" folder, you should see a database named "ResumeUpload.fp5", a file named "UPLOADit_Realms.xml", and a subfolder named "ResumeUpload". Copy the entire "ResumeUpload" folder into the "Web" folder inside your FileMaker application folder. Copy the "UPLOADit_Realms.xml" file to the same place you copied the UPLOADit plug-in file when you installed it. (On Windows, copy the "UPLOADit_Realms.xml" file to the "System" folder inside your FileMaker application folder. On Mac, copy the "UPLOADit_Realms.xml" file to the "FileMaker Extensions" folder inside your FileMaker application folder.) If you have already manually edited the "UPLOADit_Realms.xml" file, then you may just want to open up the one from the Resume Upload Example, and copy the "ResumeUpload" realm into your existing "UPLOADit_Realms.xml" file instead of overwriting it with the one from the Resume Upload Example folder. Finally, double-click the "ResumeUpload.fp5" database to open it in FileMaker.
FileMaker should now be open and the "ResumeUpload.fp5" database should be loaded. You now need to check the Web Companion settings to make sure they are set correctly to use this example solution. So, if you are on Windows, go to the "Edit" menu, select "Preferences", and then select "Application". If you are on Mac OS X, go to the "FileMaker Pro" menu, select "Preferences", and then select "Application". You should now be looking at FileMaker Pro's Application Preferences dialog. Switch to the "Plug-ins" tab and you should see a list of installed plug-ins. You should at least see the UPLOADit plug-in and the Web Companion plug-in in this list. If you do not see the UPLOADit plug-in, please follow the instructions in Chapter 1, which tells you how to install the UPLOADit plug-in. If you do not see the Web Companion plug-in, please install it from your FileMaker Pro CD.
Find the Web Companion plug-in in the list and make sure there is a checkmark next to it (meaning it is active). If there is no checkmark, click in the square next to it to make the checkmark appear and to make the plug-in active. Next, select the Web Companion plug-in and press the "Configure..." button. You should now be looking at the Web Companion Configuration dialog. At the bottom of the dialog, make sure the "TCP/IP Port Number" is set to 80. Then press the "OK" button. The Web Companion plug-in should now be configured to work with this example solution.
Finally, just to make sure, you need to check to see if the "ResumeUpload.fp5" database is being shared via the Web Companion. To do that, select the "ResumeUpload.fp5" database, go to the "File" menu, and select "Sharing...". You should now be looking at the "File Sharing for 'ResumeUpload.fp5'" dialog. In the second "Companion Sharing" section, make sure a checkmark appears next to "Web Companion" in the list. If there is no checkmark, click in the square next to it to make the checkmark appear. Then press the "OK" button.
The example solution is now installed and ready to test.
Testing the Example
To test the Resume Upload Example solution, make sure you have installed it according to the instructions above. If you have installed it properly, you should have the "ResumeUpload" folder inside the "Web" folder inside your FileMaker application folder; you should have copied the "UPLOADit_Realms.xml" file to the "System" or "FileMaker Extensions" folder in your FileMaker application folder (or copied the "ResumeUpload" realm from that file into your existing "UPLOADit_Realms.xml" file); you should have the "ResumeUpload.fp5" database opened in FileMaker; you should have the Web Companion plug-in active and listening on port 80; and you should have the "ResumeUpload.fp5" database shared via the Web Companion.
Now that everything is installed, switch to the "ResumeUpload.fp5" database and press the "Start Server" button. The "Global_Result" field should update with the words:
Figure 6.1 Global_Result after Start Server script
The UPLOADit server should now be running.
Next, open up your favorite web browser and type in this URL in the location bar:
Figure 6.2 URL for Resume Upload Example
Then press enter and the UPLOADit Resume Upload Example web page should load. Fill in a First and Last Name in the "First Name" and "Last Name" fields. Then, press the "Submit" button. Pressing the "Submit" button will send the data you have entered to the Web Companion, which will add a record in the "ResumeUpload.fp5" database and then load up a second page asking you to select your resume.
So, press the "Browse..." or "Choose File..." button and select your resume (or any file really), and then press the "Submit" button again. This time, pressing the "Submit" button will send the file you are uploading to the UPLOADit plug-in, which will save the file to the hard drive in a folder named with the First Name you entered, inside a folder named with the Last Name you entered. It will then call a script in your database which will find the new record in the database and put the full path and file name of the resume that was uploaded into the record. It will then tell the UPLOADit plug-in that it can redirect the web browser to the "thanks.htm" page.
So, UPLOADit will redirect your web browser to the "thanks.htm" page, which thanks you, by name, for uploading your resume. If you go back to FileMaker and look in the record it created in the database, you should see the full path and file name of the resume that was uploaded. You can also look in the "ResumeUpload" folder inside the "UPLOADit" folder on your main hard drive to see the folder structure it created and where it stored the resume that was uploaded.
You have now seen this example solution in action. Next you can see how this solution works.
Exploring the Example
Now that you have seen this example solution work, take a look back at the "ResumeUpload.fp5" database to see how it works. First, look at the main fields in the database:
- Global_Result
- This field is used by the Start Server and Stop Server scripts to report the results of starting and stopping the server.
- ID
- This field holds a unique id for the record. We need this so that we can find the record we are working with from the web browser.
- First_Name
- This field holds the value the user enters on the web page form.
- Last_Name
- This field holds the value the user enters on the web page form.
- First_Name_Clean
- This field is a calculation field that takes the First_Name field and removes all spaces and punctuation. This field is then used to create a folder name on the hard drive.
- Last_Name_Clean
- This field is a calculation field that takes the Last_Name field and removes all spaces and punctuation. This field is then used to create a folder name on the hard drive.
- Full_Path
- This field holds the full path and file name of the resume that is uploaded. UPLOADit gives us this when we ask for it.
- Result
- The UPLOADit script uses this field to report the results of setting the Result URL and Releasing the user's web browser.
Next take a look at the main scripts. The first main script is the "Start Server" script, which only has one Set Field script step in it that sets the "Global_Result" field. The calculation for the Set Field script step is:
Figure 6.3 Start Server Set Field Calculation
The first External function call uses the "Upld-Port" function to set the TCP/IP port of the UPLOADit server to 8080. The second External function call uses the "Upld-StartServer" function to start the UPLOADit server.
The second main script, named "Stop Server", also only has one Set Field script step in it that sets the "Global_Result" field. The calculation for that Set Field script step is:
Figure 6.4 Stop Server Set Field Calculation
This calculation uses the "Upld-StopServer" function to stop the UPLOADit server from listening for incoming connections.
Before we look at the final main script in the database, let us think about how this example works. Unlike the previous examples, this example separates the data entry onto two separate web pages. The first web page simply asks for the user's First and Last Name. This web page uses the Web Companion to create a new record in the database and return a web page that asks the user for a file. When the user selects a file and presses the "Submit" button, we have to find the record they created with the first web page so that we can update that record with the name of the file they uploaded.
So, since we need to be able to find the record to update it with the file name, we need to provide some way of identifying the record. This is where the "ID" field comes in. When the second web page that asks for the user to upload a file is served by the Web Companion, it includes a hidden form field that holds the value from the "ID" field in the database. (You can see this by viewing the source of the web page and by looking at the CDML for the "upload.htm" page below.) When the user selects a file and presses the "Submit" button, the file is uploaded to the UPLOADit server along with that ID field. The script that UPLOADit calls then must use the value from that ID field to find the correct record in the database and update it.
So, here is the final main script in the Resume Upload example database. This script is named "UPLOADit", and it is the script that UPLOADit calls whenever a user uploads their resume to the UPLOADit server. This script looks like the following:
Figure 6.5 UPLOADit Script
Line 1 uses the Set Error Capture script step to allow the script to handle any errors it may generate instead of displaying an error dialog on the screen. Line 2 makes FileMaker go into Find Mode. We do this so that we can try to find the record we need to update. Line 3 uses the "Upld-GetFieldValue" function to extract the value from the hidden form field named "ID" into the "ID" field in the database. Then, Line 4 makes FileMaker perform the Find to try to find the record.
If FileMaker finds the record, then the Status(CurrentError) function will return 0 (zero). So, Line 5 uses the Status(CurrentError) function to see if FileMaker did find the record we were looking for. If it did, then we use the "Upld-GetFieldValue" function to retrieve the full path and file name of the resume file the user uploaded. If FileMaker did not find the record we were looking for, then Line 8 makes FileMaker Find all the records, and Line 9 changes the Result URL in UPLOADit to point to an error web page.
Line 11 then uses the "Upld-ReleaseClient" function to tell UPLOADit to release the web browser and redirect it to its final location, either the "thanks.htm" page (as defined in the "ResumeUpload" Realm XML), or the "error.htm" page if FileMaker could not find the record we needed to update. Line 12 exits the record we modified and Line 13 uses the Set Error Capture script step to allow FileMaker to start displaying error dialogs again if it needs to.
Those are the three main scripts in the Resume Upload example database. Now, take a look at the "UPLOADit_Realms.xml" file inside the "System" or "FileMaker Extensions" folder inside your FileMaker application folder. If you open the "UPLOADit_Realms.xml" file in a text editor like NotePad or BBEdit®, you should see a realm defined in it that looks like this:
Figure 6.6 Resume Upload Realm XML
Line 1 starts with the <realm> tag and gives the realm the name "ResumeUpload". This is the name used in the "action" attribute of the <form> tag in the "default.htm" web page as you will see below. Line 2 defines the Path where UPLOADit should place the uploaded resumes. It defines the path as "/UPLOADit/ResumeUpload/". On Windows, this will end up being "C:\UPLOADit\ResumeUpload\". On Mac, this will end up on the startup volume in the computer in the folder "/UPLOADit/ResumeUpload/".
Line 3 and 4 tell UPLOADit to call the "UPLOADit" script in the "ResumeUpload.fp5" database when someone uploads an image. Line 5 uses the <whenfileexists> tag to define what UPLOADit should do in the event a user tries to upload a second file with the same name as an existing file on the server's hard drive. In this case, it uses the "backup" option, which means UPLOADit will rename the existing file to a "Backup" file, and save the new file with its correct name. You can test this by uploading the same file twice to this example solution.
Finally, take a look at the "default.htm", "upload.htm", and "thanks.htm" web pages in the "ResumeUpload" folder inside of the "Web" folder inside your FileMaker application folder. (If you have not looked at Chapter 2, "How to set up your Web Page Form", now might be a good time to read through it.)
The "default.htm" page for this example solution is not like the pages from the other example solutions. The <form> tag in this page does not reference the UPLOADit server yet, it simply uses the Web Companion to create the initial record. The form on this page looks like the following:
Figure 6.7 default.htm Form
Line 1 sets the <form> tag to use the "Post" method and sets the "action" attribute to use "FMPro" (which is the Web Companion). Lines 2, 3, and 4 set up some hidden form fields that tell the Web Companion which web page to return as a result, the Database to add a record to, and the Layout the fields should be on in that database, respectively.
Line 7 has an <input> tag for the user to enter their First Name. Line 9 has an <input> tag for the user to enter their Last Name. Finally, line 10 has a "Submit" button for the user to submit the form with. Notice that the Name attribute is set to "-new" so that the Web Companion will know it needs to create a new record in the database with the information from this form.
Next, the "upload.htm" page has a web form in it with a <form> tag that looks like this:
Figure 6.8 upload.htm Form Tag
If you have read Chapter 2, "How to set up your Web Page Form", you should see that this is set to connect to the UPLOADit server running on your machine at port 8080, and it will upload files to the "ResumeUpload" realm. The difference between the "action" attribute in this <form> tag and the "action" attribute in the <form> tags of the other examples is that this includes two sub-folders after the realm name. Here we are using CDML to put in the "Last_Name_Clean" and "First_Name_Clean" fields from the database. If the fields in the database had "John" and "Doe" in the "First_Name" and "Last_Name" fields respectively, then the above Action attribute would show up like this in the form:
Figure 6.9 upload.htm Form Action attribute
Since the Path for the "ResumeUpload" has been defined as "/UPLOADit/ResumeUpload/" in the "UPLOADit_Realms.xml" file above, when the user uploads a file to the UPLOADit server, it would appear in the "/UPLOADit/ResumeUpload/Doe/John/" folder on the Mac, or "C:\UPLOADit\ResumeUpload\Doe\John\" on Windows. UPLOADit would create the "Doe" and "John" sub-folders if they did not already exist.
The <input> tags for the "upload.htm" form are the following:
Figure 6.10 upload.htm Input Tags
Line 1 sets up the hidden ID form value that holds the "ID" field from the database record so that the "UPLOADit" script can find the record we need to update. (See the explanation of the "UPLOADit" script above.) Line 2 sets up a hidden "UPLOADit_Result_URL" form value to tell UPLOADit where it should redirect the web browser after the user has uploaded their resume. This is an alternative to defining the Result URL in the "UPLOADit_Realms.xml" file or in the script using the "Upld-SetResultURL" function.
Line 3 gives the user a "Browse..." or "Choose File..." button for them to select their resume file. Line 4 is the "Submit" button for the user to press to submit the form to UPLOADit.
When the user selects a file to upload and presses the submit button, the web browser sends UPLOADit the form data, including the file. UPLOADit saves the file to the hard drive, creating the first and last name folders if needed, and then calls the "UPLOADit" script in the "ResumeUpload.fp5" database. That script finds the existing record based on the "ID" field, updates it with the full path and file name of the resume the user uploaded, and then tells UPLOADit to release the web browser. UPLOADit then redirects the web browser to the Result URL from that hidden form value (Figure 6.10; Line 2), which is the "thanks.htm" page. The "thanks.htm" page uses CDML to display a "Thank You" note to the user, calling them by name:
Figure 6.11 thanks.htm CDML
This concludes the Resume Upload Example solution.

Chapter 7
IP Address Checking
This chapter explains how UPLOADit checks IP addresses against the Allow and Deny IP lists you can define for your Realms.
Checking Procedure
When a user connects to your UPLOADit server to upload a file, the plug-in checks to make sure that user can connect to your UPLOADit server by comparing the user's IP address against the Denied and Allowed IP addresses that you have defined for your realms. Below is the process in which UPLOADit decides if it needs to block a user's IP addresses: (You may wish to refer to the example realm in Figure 7.1 below when you are reading through this process.)
- The plug-in first assumes that the IP Address is not blocked. This is the default.
- The plug-in then checks to see if it should be denying all IP addresses. It checks that using this method:
- The plug-in looks to see if you have denied all IP addresses for the realm the user is uploading files to. (It looks to see if you have <denyip>all</denyip> in the realm.)
- If the realm does not have all IP Addresses denied, it looks to see if the default realm has denied all IP addresses. (It looks to see if you have <defaultdenyip>all</defaultdenyip>.)
- If the default realm does deny all IP Addresses, it looks back into the realm the user is uploading files to and checks to see if all IP Addresses have been re-allowed. (It looks to see if you have <allowip>all</allowip> in the realm.)
- The plug-in now knows if it should consider all IP addresses to be denied or allowed, so it takes one of two courses:
- If all IP addresses are being denied, the plug-in uses this method to see if it should re-allow this IP address:
- The plug-in looks to see if the IP address has been allowed by the realm the user is trying to upload files to. (It looks to see if there is an <allowip>X.X.X.X</allowip> in the realm where the IP address is X.X.X.X, or if there is an <allowip>Y.Y.Y.Y-Z.Z.Z.Z</allowip> in the realm where the IP address is in the range Y.Y.Y.Y-Z.Z.Z.Z.)
- If the plug-in does not find the IP address in the list of allowed IP addresses in the realm, it looks to see if the IP address has been allowed by the default realm. (It looks to see if there is a <defaultallowip>X.X.X.X</defaultallowip> where the IP address is X.X.X.X, or if there is a <defaultallowip>Y.Y.Y.Y-Z.Z.Z.Z</defaultallowip> where the IP address is in the range Y.Y.Y.Y-Z.Z.Z.Z.)
- If the plug-in does not find the IP Address in either of the list of allowed IP addresses, it checks to see if the IP address is the loopback address (127.0.0.1), and if so, it allows the connection. (The plug-in does this so that when testing your UPLOADit server on your own machine, it will always allow you to connect.)
- If the plug-in could not find the IP address in any of the above allowed IP address lists, it blocks the IP address and the user receives an error web page telling them their IP address has been blocked.
- If all IP addresses are being allowed, the plug-in uses this method to see if it should deny this IP address:
- The plug-in looks to see if the IP address has been denied by the realm the user is trying to upload files to. (It looks to see if there is a <denyip>X.X.X.X</denyip> in the realm where the IP address is X.X.X.X, or if there is a <denyip>Y.Y.Y.Y-Z.Z.Z.Z</denyip> in the realm where the IP address is in the range Y.Y.Y.Y-Z.Z.Z.Z.)
- If the plug-in does not find the IP address in the list of denied IP addresses in the realm, it looks to see if the IP address has been denied by the default realm. (It looks to see if there is a <defaultdenyip>X.X.X.X</defaultdenyip> where the IP address is X.X.X.X, or if there is a <defaultdenyip>Y.Y.Y.Y-Z.Z.Z.Z</defaultdenyip> where the IP address is in the range Y.Y.Y.Y-Z.Z.Z.Z.)
- If the plug-in could not find the IP address in any of the above denied IP address lists, it allows the user to upload the file.
Here is an example UPLOADit_Realms.xml file with example allowed and denied IP lists:
Figure 7.1 Example UPLOADit_Realms.xml file
Here are some example users that are trying to upload files to the UPLOADit server, and the reasons why they would be denied or allowed to connect to the UPLOADit server (based on the above UPLOADit_Realms.xml file):
- User A has the IP Address 192.168.0.14.
- If this user tried to upload files to the default realm, his IP address would be blocked because all IP addresses have been denied in the default realm, and only the IP addresses in the range 192.168.0.1 to 192.168.0.10 have been allowed.
- If this user tried to upload files to the "test1" realm, his IP address would be allowed to connect because even though the default realm has denied all IP addresses, his IP address is in the range 192.168.0.11 to 192.168.0.20, which has been allowed by the "test1" realm.
- If this user tried to upload files to the "test2" realm, his IP address would be allowed to connect because even though the default realm has denied all IP addresses, the "test2" realm has re-allowed all IP addresses.
- User B has the IP Address 172.16.0.25.
- If this user tried to upload files to the default realm, her IP address would be blocked because all IP addresses have been denied in the default realm, and her IP address is not in the range 192.168.0.1 to 192.168.0.10.
- If this user tried to upload files to the "test1" realm, her IP address would be allowed to connect because even though the default realm has denied all IP address, her IP address is 172.16.0.25, which has been specifically allowed.
- If this user tried to upload files to the "test2" realm, her IP address would be blocked because her IP address is 172.16.0.25, which has been specifically denied.
- User C has the IP Address 192.168.0.7.
- If this user tried to upload files to the default realm, his IP address would be allowed to connect because even though the default realm has denied all IP addresses, his IP address is in the range 192.168.0.1 to 192.168.0.10, which has been re-allowed by the default realm.
- If this user tried to upload files to the "test1" realm, his IP address would be allowed to connect because even though the default realm has denied all IP addresses, his IP address is in the range 192.168.0.1 to 192.168.0.10, which has been re-allowed by the default realm.
- If this user tried to upload files to the "test2" realm, his IP address would be allowed to connect because even though the default realm has denied all IP addresses, the "test2" realm has re-allowed all IP addresses.

Chapter 8
Credits & Contact Information
Credits
Programming, documentation, and example databases by Jake Traynham
Concept, web design, and example databases by Jesse Traynham
Documentation, and example databases by Daniel Sims
Special thanks to the beta testers.
Contact Information
Email: UPLOADit@cnsplug-ins.com
UPLOADit Website: http://uploadit.cnsplug-ins.com/
Main Website: http://www.cnsplug-ins.com/
Purchase: https://secure.comm-unity.net/products.htm?product=UPLOADit
Phone: 817-560-4226
Fax: 817-244-0340
You can write us at:
Comm-Unity Networking Systems
8652 Camp Bowie West
Fort Worth, Texas 76116