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.

Table of Contents

Documentation Overview

Overview of Chapters
Overview of Appendixes
Overview of Figures

Chapter 1

Introduction, Installation, and Configuration

1.1 Introduction
1.2 Installation
1.3 Configuration

Chapter 2

How to set up your Web Page Form

2.1 Example Web Page Form

Chapter 3

How to set up your UPLOADit FileMaker Script

3.1 Example UPLOADit Script

Chapter 4

File Upload Example

4.1 Installing the Example
4.2 Testing the Example
4.3 Exploring the Example

Chapter 5

Image Import Example

5.1 Installing the Example
5.2 Testing the Example
5.3 Exploring the Example

Chapter 6

Resume Upload Example

6.1 Installing the Example
6.2 Testing the Example
6.3 Exploring the Example

Chapter 7

IP Address Checking

7.1 Checking Procedure

Chapter 8

Credits & Contact Information

8.1 Credits
8.2 Contact Information

Appendix

Functions

Realm Tags

Function Error Responses

Browser Errors

UPLOADit Flow Chart

Glossary

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 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.
Chapter 2: How to set up your Web Page Form

This 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 Script

This 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 Example

This 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 Example

This 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 Example

This 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 Checking
This 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.

Upld-DefineRealmXML
Upld-DeleteRealm
Upld-File-Copy
Upld-File-CreateFolder
Upld-File-Delete
Upld-File-Exists
Upld-File-GetPathToDB
Upld-File-GetPathToFM
Upld-File-Move
Upld-File-Rename
Upld-File-Size
Upld-GetFieldValue
Upld-Port
Upld-Register
Upld-ReleaseClient
Upld-SetResultURL
Upld-StartServer
Upld-StopServer
Upld-Version
Appendix A: Functions
This 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.
Allowed IP Addresses
Database
Denied IP Addresses
Maximum File Count
Maximum File Size
Password
Realm Name
Result URL
Script
System Administrator's Email Address
Upload Path
UPLOADit Tag
When File Exists
Appendix B: Realm Tags
This 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.
Understanding Error Responses
Appendix C: Function Error Responses
Blocked IP Address
Could Not Get File Name
Database/Script Problem
Disk Error
Error Receiving Data
File Error
File Error
File Error
File is too Large
File Stream Error
Invalid Content-Type
Malformed Authorization Header
Malformed Headers
Malformed Headers
Malformed Method
Malformed Request/Realm
Memory Error
Memory Error
Realm Not Found
Result URL Error
Too Many Files
Unauthorized
Unauthorized
Unknown Error
Unsupported HTTP Version
Unsupported Method
Appendix D: Browser Errors
This 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.
Step 1
Step 2
Appendix E: UPLOADit Flow Chart
Following is general view of how a file gets from the browser to FileMaker.
CGI
Domain
Form
IP Address
Realm
TCP/IP Port
UPLOADit_Realms.xml
URL
Appendix F: Glossary
Here 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

1.1 Installing on Macintosh
1.2 Installing on Windows
1.3 Configuration Dialog - Basics Tab
1.4 Configuration Dialog - Realms Tab
1.5 Configuration Dialog - About Tab

Chapter 2

2.1 Web Form Example Realm XML
2.2 Web Form Example HTML Page
2.3 Web Form Example Action Attribute
2.4 Web Form Example URL
2.5 Web Form Example HTML Page 2
2.6 Web Form Example Upld-GetFieldValue
2.7 Web Form Example Upld-GetFieldValue 2

Chapter 3

3.1 UPLOADit Script Example Realm XML
3.2 UPLOADit Script Example HTML Page
3.3 UPLOADit Script Example Script
3.4 UPLOADit Script Example Script with Find

Chapter 4

4.1 File Upload Example Start Server Result
4.2 File Upload Example URL
4.3 File Upload Example Start Server Script
4.4 File Upload Example Stop Server Script
4.5 File Upload Example UPLOADit Script
4.6 File Upload Example Result URL
4.7 File Upload Example Form Tag
4.8 File Upload Example Input Tags
4.9 File Upload Example thanks.htm CDML

Chapter 5

5.1 Image Import Example Start Server Result
5.2 Image Import Example URL
5.3 Image Import Example Start Server Script
5.4 Image Import Example Stop Server Script
5.5 Image Import Example UPLOADit Script
5.6 Image Import Example Realm XML
5.7 Image Import Example default.htm Form Tag
5.8 Image Import Example default.htm Input Tags
5.9 Image Import Example thanks.htm CDML

Chapter 6

6.1 Resume Upload Example Start Server Result
6.2 Resume Upload Example URL
6.3 Resume Upload Example Start Server Script
6.4 Resume Upload Example Stop Server Script
6.5 Resume Upload Example UPLOADit Script
6.6 Resume Upload Example Realm XML
6.7 Resume Upload Example default.htm Form
6.8 Resume Upload Example upload.htm Form Tag
6.9 Resume Upload Example upload.htm Form Action
6.10 Resume Upload Example upload.htm Input Tags
6.11 Resume Upload Example thanks.htm CDML

Chapter 7

7.1 Example UPLOADit_Realms.xml file with IP checking

Appendix C

C.1 Error Response Form
C.2 Error Response Example
C.3 Error Response Script

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:

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 Form

This 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:

  1. <UPLOADit>
  2. <defaultsysadmin>webmaster@mydomain.com</defaultsysadmin>
  3. <defaultresulturl>http://www.mydomain.com/thanks.htm</defaultresulturl>
  4. <realm name="test1">
  5. <path>/UPLOADit/test1/</path>
  6. <database>mydb.fp5</database>
  7. <script>UPLOADit Test1 Realm</script>
  8. </realm>
  9. <realm name="test2">
  10. <path>/UPLOADit/test2/</path>
  11. <database>mydb.fp5</database>
  12. <script>UPLOADit Test2 Realm</script>
  13. </realm>
  14. </UPLOADit>
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:

  1. <html>
  2. <head>
  3. <title>UPLOADit test</title>
  4. </head>
  5. <body>
  6. <form name="UPLOADit_Form" method="post" enctype="multipart/form-data" action="http://www.mydomain.com:8080/test1/">
  7. <p>Please select a file and press the submit button.</p>
  8. <p><input type="file" name="UPLOADit_File"></p>
  9. <p><input type="submit" value="Submit"></p>
  10. </form>
  11. </body>
  12. </html>
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:

  1. http://www.mydomain.com:8080/test1/
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:

  1. http://www.mydomain.com:8080/test1/newfiles/monday/
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:

  1. <html>
  2. <head>
  3. <title>UPLOADit test</title>
  4. </head>
  5. <body>
  6. <form name="UPLOADit_Form" method="post" enctype="multipart/form-data" action="http://www.mydomain.com:8080/test2/new/02_04/">
  7. <input type="hidden" name="id" value="392">
  8. <input type="hidden" name="UPLOADit_Result_URL" value="http://www.mydomain.com/specialthanks.htm">
  9. <p>Please fill in your First and Last Name, then select a file, and then press the submit button.</p>
  10. <p>First Name: <input type="text" name="FirstName"></p>
  11. <p>Last Name: <input type="text" name="LastName"></p>
  12. <p>File to Upload: <input type="file" name="UPLOADit_File"></p>
  13. <p><input type="submit" value="Submit"></p>
  14. </form>
  15. </body>
  16. </html>
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:

  1. Set Field [id_from_form, External("Upld-GetFieldValue", "id")]
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:

  1. Set Field [First_Name, External("Upld-GetFieldValue", "FirstName")]
  2. Set Field [Last_Name, External("Upld-GetFieldValue", "LastName")]
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 Script

This 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:

  1. <UPLOADit>
  2. <defaultsysadmin>webmaster@mydomain.com</defaultsysadmin>
  3. <defaultresulturl>http://www.mydomain.com/thanks.htm</defaultresulturl>
  4. <realm name="test">
  5. <path>/UPLOADit/test/</path>
  6. <database>mydb.fp5</database>
  7. <script>UPLOADit Test Realm</script>
  8. </realm>
  9. </UPLOADit>
Figure 3.1 Example Realm XML

Second, here is an example web form page that we will base the rest of the chapter on:

  1. <html>
  2. <head>
  3. <title>UPLOADit test</title>
  4. </head>
  5. <body>
  6. <form name="UPLOADit_Form" method="post" action="http://www.mydomain.com:8080/test/" enctype="multipart/form-data">
  7. <input type="hidden" name="id" value="392">
  8. <p>Please fill in your First and Last Name, then select a file, and then press the submit button.</p>
  9. <p>First Name: <input type="text" name="First_Name"></p>
  10. <p>Last Name: <input type="text" name="Last_Name"></p>
  11. <p>File to Upload: <input type="file" name="UPLOADit_File"></p>
  12. <p><input type="submit" value="Submit"></p>
  13. </form>
  14. </body>
  15. </html>
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:

  1. New Record/Request
  2. Set Field [id, External("Upld-GetFieldValue", "id")]
  3. Set Field [First Name, External("Upld-GetFieldValue", "First_Name")]
  4. Set Field [Last Name, External("Upld-GetFieldValue", "Last_Name")]
  5. Set Field [File Name, External("Upld-GetFieldValue", "UPLOADit_File")]
  6. Set Field [UPLOADit Result, External("Upld-ReleaseClient", "")]
  7. Exit Record/Request
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:

  1. Set Error Capture [On]
  2. Enter Find Mode []
  3. Set Field [id, External("Upld-GetFieldValue", "id")]
  4. Perform Find [Replace Found Set]
  5. If [Status(CurrentError) = 0]
  6. Set Field [First Name, External("Upld-GetFieldValue", "First_Name")]
  7. Set Field [Last Name, External("Upld-GetFieldValue", "Last_Name")]
  8. Set Field [File Name, External("Upld-GetFieldValue", "UPLOADit_File")]
  9. Else
  10. Show All Records
  11. Set Field [UPLOADit Result, External("Upld-SetResultURL", "http://www.mydomain.com/error.htm"]
  12. End If
  13. Set Field [UPLOADit Result, External("Upld-ReleaseClient", "")]
  14. Exit Record/Request
  15. Set Error Capture [Off]
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 Example

This 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:

  1. Realm XML Loaded.
  2. Port set to 8080
  3. Server Started on port: 8080
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:

  1. http://127.0.0.1/FileUpload/
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:

  1. External("Upld-DefineRealmXML",
  2. "<UPLOADit>" &
  3. " <realm name='FileUpload' action='update'>" &
  4. " <path>" & External("Upld-File-GetPathToFM", "") & "/Web/FileUpload/Files/</path>" &
  5. " <database>" & Status( CurrentFileName) & "</database>" &
  6. " <script>UPLOADit</script>" &
  7. " </realm>" &
  8. "</UPLOADit>"
  9. ) & "¶" &
  10. External("Upld-Port", "8080") & "¶" &
  11. External("Upld-StartServer", "")
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:

  1. External("Upld-StopServer", "")
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:

  1. New Record/Request
  2. Set Field [Full_Path, External("Upld-GetFieldValue", "UPLOADit_File")]
  3. Set Field [First_Name, External("Upld-GetFieldValue", "First_Name")]
  4. Set Field [Last_Name, External("Upld-GetFieldValue", "Last_Name")]
  5. Set Field [Result, External("Upld-SetResultURL", "http://127.0.0.1/FileUpload/FMPro?-format=thanks.htm&-db=" & Status(CurrentFileName) & "&-lay=Detail&id=" & ID & "&-find") & "¶" & External("Upld-ReleaseClient", "")]
  6. Exit Record/Request
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:

  1. http://127.0.0.1/FileUpload/FMPro?-format=thanks.htm&-db=FileUpload.fp5 &-lay=Detail&id=ABCD1234&-find
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:

  1. <form name="UPLOADit_Form" method="post" action="http://127.0.0.1:8080/FileUpload/" enctype="multipart/form-data">
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:

  1. <input type="text" name="First_Name">
  2. <input type="text" name="Last_Name">
  3. <input type="file" name="UPLOADit_File">
  4. <input type="submit" value="Submit">
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:

  1. <h3>Below is the result of your submission.</h3>
  2. Filename: <a href="Files/[FMP-field: File_Name]">[FMP-field: File_Name]</a><br>
  3. First Name: [FMP-field: First_Name]<br>
  4. Last Name: [FMP-field: Last_Name]
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 Example

This 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:

  1. Port set to 8080
  2. Server Started on port: 8080
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:

  1. http://127.0.0.1/ImageImport/
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:

  1. External("Upld-Port", "8080") & "¶" &
  2. External("Upld-StartServer", "")
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:

  1. External("Upld-StopServer", "")
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:

  1. New Record/Request
  2. Set Field [First_Name, External("Upld-GetFieldValue", "First_Name")]
  3. Set Field [Last_Name, External("Upld-GetFieldValue", "Last_Name")]
  4. Set Field [User_Name, External("Upld-GetFieldValue", "UPLOADit_User")]
  5. Set Field [Full_Path, External("Upld-GetFieldValue", "UPLOADit_File")]
  6. If [not IsEmpty(FullPath)]
  7. If [(Upper(RightWords(Full_Path, 1)) = "JPG") or (Upper(RightWords(Full_Path, 1)) == "JPEG")]
  8. If [External("Upld-File-Exists", "/UPLOADit/ImageImport/image.jpg") = "True"]
  9. Set Field [Import_Result, External("Upld-File-Delete", "/UPLOADit/ImageImport/image.jpg")]
  10. End If
  11. If [LeftWords(Import_Result, 1) <> "ERROR"]
  12. Set Field [Import_Result, External("Upld-File-Copy", "src='" & Full_Path & "'; dest='/UPLOADit/ImageImport/image.jpg' ")]
  13. If [LeftWords(Import_Result, 1) <> "ERROR"]
  14. Set Error Capture [On]
  15. Go to Field [Image]
  16. Insert Picture ["image.jpg"]
  17. If [Status(CurrentError) <> 0]
  18. Set Field [Import_Result, "ERROR: FileMaker had an error importing the image: " & Status(CurrentError)]
  19. End If
  20. Set Error Capture [Off]
  21. End If
  22. End If
  23. Else
  24. If [Upper(RightWords(Full_Path, 1)) = "GIF"]
  25. If [External("Upld-File-Exists", "/UPLOADit/ImageImport/image.gif") = "True"]
  26. Set Field [Import_Result, External("Upld-File-Delete", "/UPLOADit/ImageImport/image.gif")]
  27. End If
  28. If [LeftWords(Import_Result, 1) <> "ERROR"]
  29. Set Field [Import_Result, External("Upld-File-Copy", "src='" & Full_Path & "'; dest='/UPLOADit/ImageImport/image.gif' ")]
  30. If [LeftWords(Import_Result, 1) <> "ERROR"]
  31. Set Error Capture [On]
  32. Go to Field [Image]
  33. Insert Picture ["image.gif"]
  34. If [Status(CurrentError) <> 0]
  35. Set Field [Import_Result, "ERROR: FileMaker had an error importing the image: " & Status(CurrentError)]
  36. End If
  37. Set Error Capture [Off]
  38. End If
  39. End If
  40. Else
  41. Set Field [Import_Result, "ERROR: From the UPLOADit Script: Image file name did not end in '.jpg', '.jpeg', or '.gif'"]
  42. End If
  43. End If
  44. End If
  45. If [LeftWords(Import_Result, 1) = "ERROR"]
  46. Set Field [Release_Result, External("Upld-SetResultURL", "http://127.0.0.1/ImageImport/FMPro?-format=error.htm&-db=" & Status(CurrentFileName) & "&-lay=Detail&id=" & ID & "&-find")]
  47. Else
  48. Set Field [Release_Result, External("Upld-SetResultURL", "http://127.0.0.1/ImageImport/FMPro?-format=thanks.htm&-db=" & Status(CurrentFileName) & "&-lay=Detail&id=" & ID & "&-find")]
  49. End If
  50. Set Field [Release_Result, External("Upld-ReleaseClient", "") & "¶" & Release_Result]
  51. Exit Record/Request
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:

  1. <realm name="ImageImport">
  2. <path>/UPLOADit/ImageImport/NewFiles/</path>
  3. <database>ImageImport.fp5</database>
  4. <script>UPLOADit</script>
  5. <password>imagetest</password>
  6. <maxfilesize>1m</maxfilesize>
  7. </realm>
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:

  1. <form name="UPLOADit_Form" method="post" action="http://127.0.0.1:8080/ImageImport/" enctype="multipart/form-data">
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:

  1. <input type="text" name="First_Name">
  2. <input type="text" name="Last_Name">
  3. <input type="file" name="UPLOADit_File">
  4. <input type="submit" value="Submit">
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:

  1. <h3>Below is the result of your submission.</h3>
  2. First Name: [FMP-field: First_Name]<br>
  3. Last Name: [FMP-field: Last_Name]<br>
  4. User Name: [FMP-field: User_Name]<br>
  5. Your Image:<br>
  6. <img src="[FMP-Image: Image]">
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 Example

This 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:

  1. Port set to 8080
  2. Server Started on port: 8080
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:

  1. http://127.0.0.1/ResumeUpload/
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:

  1. External("Upld-Port", "8080") & "¶" &
  2. External("Upld-StartServer", "")
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:

  1. External("Upld-StopServer", "")
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:

  1. Set Error Capture [On]
  2. Enter Find Mode []
  3. Set Field [ID, External("Upld-GetFieldValue", "ID")]
  4. Perform Find [Replace Found Set]
  5. If [Status(CurrentError) = 0]
  6. Set Field [Full_Path, External("Upld-GetFieldValue", "UPLOADit_File")]
  7. Else
  8. Show All Records
  9. Set Field [Result, External("Upld-SetResultURL", "http://127.0.0.1/ResumeUpload/error.htm")]
  10. End If
  11. Set Field [Result, External("Upld-ReleaseClient", "") & "¶" & Result]
  12. Exit Record/Request
  13. Set Error Capture [Off]
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:

  1. <realm name="ResumeUpload">
  2. <path>/UPLOADit/ResumeUpload/</path>
  3. <database>ResumeUpload.fp5</database>
  4. <script>UPLOADit</script>
  5. <whenfileexists>backup</whenfileexists>
  6. </realm>
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:

  1. <form name="UPLOADit_Form" method="post" action="FMPro">
  2. <input type="hidden" name="-format" value="upload.htm">
  3. <input type="hidden" name="-db" value="ResumeUpload.fp5">
  4. <input type="hidden" name="-lay" value="Detail">
  5. <h2>Please fill in your First Name and Last Name, and then press the Submit button.</h2>
  6. <h3>First Name</h3>
  7. <input type="text" name="First_Name">
  8. <h3>Last Name</h3>
  9. <input type="text" name="Last_Name">
  10. <input type="submit" name="-new" value="Submit">
  11. </form>
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:

  1. <form name="UPLOADit_Form" method="post" action="http://127.0.0.1:8080/ResumeUpload/[FMP-Field: Last_Name_Clean]/[FMP-Field: First_Name_Clean]/" enctype="multipart/form-data">
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:

  1. action="http://127.0.0.1:8080/ResumeUpload/Doe/John/"
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:

  1. <input type="hidden" name="ID" value="[FMP-Field: ID]">
  2. <input type="hidden" name="UPLOADit_Result_URL" value="http://127.0.0.1/ResumeUpload/FMPro?-format=thanks.htm &-db=ResumeUpload.fp5&-lay=Detail&ID=[FMP-Field: ID]&-find">
  3. <input type="file" name="UPLOADit_File">
  4. <input type="submit" value="Submit">
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:

  1. <h2 class="title">Thank you, [FMP-Field: First_Name] [FMP-Field: Last_Name], for uploading your resume.</h2>
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.)

  1. The plug-in first assumes that the IP Address is not blocked. This is the default.

  2. The plug-in then checks to see if it should be denying all IP addresses. It checks that using this method:

    1. 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.)
    2. 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>.)
    3. 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.)

  3. The plug-in now knows if it should consider all IP addresses to be denied or allowed, so it takes one of two courses:

    1. If all IP addresses are being denied, the plug-in uses this method to see if it should re-allow this IP address:

      1. 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.)
      2. 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.)
      3. 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.)
      4. 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.

    2. If all IP addresses are being allowed, the plug-in uses this method to see if it should deny this IP address:

      1. 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.)
      2. 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.)
      3. 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:

  1. <UPLOADit>
  2. <defaultpath>/UPLOADit/</defaultpath>
  3. <defaultresulturl>http://www.mydomain.com/thankyou.htm</defaultresulturl>
  4. <defaultdenyip>all</defaultdenyip>
  5. <defaultallowip>192.168.0.1-192.168.0.10</defaultallowip>
  6. <realm name="test1">
  7. <path>/UPLOADit/test1/</path>
  8. <allowip>172.16.0.25</allowip>
  9. <allowip>192.168.0.11-192.168.0.20</allowip>
  10. </realm>
  11. <realm name="test2">
  12. <path>/UPLOADit/test2/</path>
  13. <allowip>all</allowip>
  14. <denyip>172.16.0.25</denyip>
  15. </realm>
  16. </UPLOADit>
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):

  1. 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.

  2. 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.

  3. 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

Appendix A: Functions

This 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.

Upld-DefineRealmXML

Use this function to define realms from within your database. The XML you give this function is set up in the exact same way the UPLOADit_Realms.xml file is set up. When you define realms with this function, they are immediately available and they are added to the UPLOADit_Realms.xml file for the next time your UPLOADit server is stopped and restarted.


Example

External("Upld-DefineRealmXML", "<UPLOADit><realm name='newrealm'><path>/UPLOADit/newrealm/</path></realm></UPLOADit>")
External("Upld-DefineRealmXML", New_Realm_XML_Field)

Related


Possible Error Responses [?]

"XXX; Line: YYY; Column: ZZZ"
The plug-in had a problem parsing the XML you gave it. The error will be XXX. The error occurred at line YYY, column ZZZ in the XML you gave it.
"Could not allocate memory for the Upload Server."
The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.

Upld-DeleteRealm

Use this function to delete a defined realm. You can delete any realm that has been defined either through the Upld-DefineRealmXML function, through the Configuration Dialog, or through the UPLOADit_Realms.xml file. The parameter you give this function should be the name of the realm you need to delete.


Example

External("Upld-DeleteRealm", "myrealm")

Related


Possible Error Responses [?]

"No Realm exists with the name 'XXX'"
The realm you were trying to delete does not exist.
"Could not allocate memory for the Upload Server."
The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.
"You must specify the name of the Realm to Delete."
You did not specify the name of a realm. Make sure you define a parameter.

Upld-File-Copy

Use this function to copy one file to another location on your hard drive. This function takes two named parameters, the "src" and "dest" parameters. The "src" parameter is the full path to the file that you would like to copy. The "dest" parameter is the full path to the folder where you would like to copy the file to. (The "dest" parameter can also point to a non-existent file, and the file you are copying will be renamed as it is copied.) The "src" and "dest" parameters can be in any order, but they must be separated by a semicolon (";").


Example

External("Upld-File-Copy", "src='c:\UPLOADit\image.jpg'; dest='c:\my files\' ")
External("Upld-File-Copy", "src='/UPLOADit/flower.jpg'; dest='/UPLOADit/image.jpg' ")

Related


Possible Error Responses [?]

"You cannot copy Folders with this function; you must specify a File."
You can only copy files with this function.
"Source File does not exist."
The file you are trying to copy does not exist.
"Source File is invalid: XXX"
XXX represents the reason why the file you are trying to copy or the path to that file is invalid.
"You must specify the Source File ('src' parameter)."
You did not specify the file you are trying to copy. Make sure you have the 'src' parameter defined.
"File Destination is invalid: XXX"
XXX represents the reason why the destination path you are trying to copy the file to is invalid.
"You must specify the File Destination ('dest' parameter)."
You did not specify a destination for the file you are trying to copy. Make sure you have the 'dest' parameter defined.
"File Copy Failed: XXX"
XXX represents an error from the operating system.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

Upld-File-CreateFolder

Use this function to create a folder (directory) on your hard drive. This function takes one parameter, which can be named, but does not have to be. The "folder" parameter is the full path to the non-existent folder that you would like to create. If you specify multiple sub-folders that do not exist, they will all be created. In other words, if you specify the folder "c:\this\is\a\test\", and none of the "this", "is", "a", or "test" folders exist, they will all be created.


Example

External("Upld-File-CreateFolder", "folder='/UPLOADit/new folder/' ")
External("Upld-File-CreateFolder", "c:\this\is\a\test\")

Related


Possible Error Responses [?]

"You must specify a name for the New Folder ('folder' parameter)."
You did not specify a name for the folder you are trying to create. Make sure you have the 'folder' parameter defined.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper function syntax.
"Folder Creation Failed: XXX"
XXX represents an error from the operating system.

Upld-File-Delete

Use this function to delete a file from your hard drive. This function takes one parameter, which can be named, but does not have to be. The "file" parameter is the full path to the existing file that you would like to delete.


Example

External("Upld-File-Delete", "file='c:\UPLOADit\delete me.txt' ")
External("Upld-File-Delete", "/Documents/old image.jpg")

Related


Possible Error Responses [?]

"You cannot delete Folders with this function; you must specify a File."
You can only delete files with this function.
"File does not exist."
The file you are trying to delete does not exist.
"File Name is invalid: XXX"
XXX represents the reason why the file you are trying to delete or the path to that file is invalid.
"You must specify a File to Delete ('file' parameter)."
You did not specify the file you are trying to delete. Make sure you have the 'file' parameter defined.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.
"File Deletion Failed: XXX"
XXX represents an error from the operating system.

Upld-File-Exists

Use this function to see if a file exists on your hard drive. This function takes one parameter, which can be named, but does not have to be. The "file" parameter is the full path to the file that you are testing the existence of.

Example

External("Upld-File-Exists", "file='c:\UPLOADit\test.txt' ")
External("Upld-File-Exists", "/Documents/image.jpg")

Related


Possible Error Responses [?]

"You must specify a File to test ('file' parameter)."
You did not specify the file you are trying to test for. Make sure you have the 'file' parameter defined.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.
"File-Exists: XXX"
XXX represents an error from the operating system.

Upld-File-GetPathToDB

Use this function to retrieve the path to the folder containing the database you specify. This function will only work for databases that are on the local machine. The parameter you give must be the file name of the database you need the path from. If you need the path of the database where your script is running, you can use the Status(CurrentFileName) function to get the file name of the database. (If you ever changed the name of your database, using the Status(CurrentFileName) function would take that into account and this function would always work as expected.)


Example

External("Upld-File-GetPathToDB", "mydb.fp5")
External("Upld-File-GetPathToDB", Status(CurrentFileName))

Related


Possible Error Responses [?]

"Database 'XXX' is not on the local hard drive."
The database that you specified does not exist on the local hard drive (most likely it is a shared database), so the plug-in can't return the file path to you.
"Database 'XXX' does not exist."
The database you specified is not currently open in FileMaker.
"You must specify the name of the database."
You did not specify the name of the database that you are trying to get the file path for.

Upld-File-GetPathToFM

Use this function to retrieve the path to the folder containing the FileMaker Pro application on your hard drive. This function does not take a parameter, so you can use the empty string ("").


Example

External("Upld-File-GetPathToFM", "")

Related


Upld-File-Move

Use this function to move one file to another location on your hard drive. This function takes two named parameters, the "src" and "dest" parameters. The "src" parameter is the full path to the file that you would like to move. The "dest" parameter is the full path to the folder where you would like to move the file to. (The "dest" parameter can also point to a non-existent file, and the file you are moving will be renamed as it is moved.) The "src" and "dest" parameters can be in any order, but they must be separated by a semicolon (";").


Example

External("Upld-File-Move", "src='c:\UPLOADit\image.jpg'; dest='c:\my files\' ")
External("Upld-File-Move", "src='/UPLOADit/flower.jpg'; dest='/UPLOADit/image.jpg' ")

Related


Possible Error Responses [?]

"You cannot move Folders with this function; you must specify a File."
You can only move files with this function.
"Source File does not exist."
The file you are trying to move does not exist.
"Source File is invalid: XXX"
XXX represents the reason why the file you are trying to move or the path to that file is invalid.
"You must specify the Source File ('src' parameter)."
You did not specify the file you are trying to move. Make sure you have the 'src' parameter defined.
"File Destination is invalid: XXX"
XXX represents the reason why the destination path you are trying to copy the file to is invalid.
"You must specify the File Destination ('dest' parameter)."
You did not specify a destination for the file you are trying to move. Make sure you have the 'dest' parameter defined.
"File Move Failed: XXX"
XXX represents an error from the operating system.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

Upld-File-Rename

Use this function to rename an existing file on your hard drive. This function takes two named parameters, the "file" and "newname" parameters. The "file" parameter is the full path to the file that you would like to rename. The "newname" parameter is the new file name for the existing file. The "file" and "newname" parameters can be in any order, but they must be separated by a semicolon (";").


Example

External("Upld-File-Rename", "file='c:\UPLOADit\image.jpg'; newname='image_backup.jpg' ")
External("Upld-File-Rename", "file='/UPLOADit/flower.jpg'; newname='image.jpg' ")

Related


Possible Error Responses [?]

"You cannot rename Folders with this function; you must specify a File."
The path you specified pointed to a folder instead of a file.

"File does not exist."
The path you specified pointed to a non-existent file.

"You must specify the File to Rename ('file' parameter)."
You did not specify a file to rename. Make sure you have the 'file' parameter defined.

"You must specify a New Name for the File ('newname' parameter)."
You did not specify a new name for the file. Make sure you have the 'newname' parameter defined.

"File Renaming Failed: XXXX"
The plug-in could not rename the file for some reason. The "XXXX" should be the reason why it could not rename the file.

"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

Upld-File-Size

Use this function to get the size of a file on your hard drive. This function takes one parameter, which can be named, but does not have to be. The "file" parameter is the full path to the file that you would like to get the size of.


Example

External("Upld-File-Size", "file='/UPLOADit/image.jpg' ")
External("Upld-File-Size", "c:\my files\document.txt")

Related


Possible Error Responses [?]

"You cannot get the size of Folders with this function; you must specify a File."
You can only get the size of files with this function.
"File does not exist."
The file you are trying to get the size of does not exist.
"File Name is invalid: XXX"
XXX represents the reason why the file you are trying to get the size of or the path to that file is invalid.
"You must specify a File to get its Size ('file' parameter)."
You did not specify the file you are trying to get the size of. Make sure you have the 'file' parameter defined.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.
"Getting File Size Failed: XXX"
XXX represents an error from the operating system.

Upld-GetFieldValue

When a user uploads a file to your UPLOADit server, they submit a web form with their web browser. This web form can contain any number of web form fields. Use this function to get the value from any one of those form fields. The parameter you give this function should be the name of the field you need the value of. For example, if the web form contained a form field like this:

<input type="text" name="FirstName">

Then you could use this function with the parameter "FirstName" to get the value the user entered into that field in their web browser.

You also use this function to get special values about the currently connected user. Use one of the following parameter names to get that special value:

  • "UPLOADit_Realm" - The name of the realm the currently connected user has uploaded files to.
  • "UPLOADit_User" - The user name the currently connected user used in the User Name/Password dialog presented to them when they uploaded. (Note: The User Name/Password dialog is only displayed when you have defined a Password in your realm.)
  • "UPLOADit_Result_URL" - If the web form has defined this value, this will return the Result URL that the users web browser will be redirected to. Most likely you will not need to retrieve this value into your database.
  • "UPLOADit_IP" - The IP address of the currently connected user.

This function is only useful when a user's web browser is connected to your UPLOADit server. When a user uploads a file to your UPLOADit server, and you have defined a database and script to run when this happens, UPLOADit will call that script in your database. In the script that UPLOADit calls, you can use this function to retrieve the values from this user's web browser and then call the "Upld-ReleaseClient" function to redirect the user's web browser to its final location.


Example

External("Upld-GetFieldValue", "FirstName")
External("Upld-GetFieldValue", "UPLOADit_User")

Related


Possible Error Responses [?]

"There is no client connected."
A user's web browser must be connected to your UPLOADit server to retrieve values from the web form they submitted. If you get this error, you have either already called "Upld-ReleaseClient", or you are not calling this function from the script that you have told UPLOADit to call when someone uploads a file.
"You must specify which field value to retrieve."
You did not specify the name of the form field you are trying to get the value of.

Upld-Port

Use this function to define the TCP/IP port that you need your UPLOADit server to listen for connections on. By default, the port is set to 8080, but you can use anything in the range of 0 to 65535. There is one exception to this and that is on Mac OS X, where you cannot set the port below 1024 unless the FileMaker Pro process is running with super user privileges (something that is probably not a good idea). You must define this port before starting the server if you need it to be different than the default. (Note: If you change the port that your UPLOADit server listens for connections on, make sure you update the "action" attribute of your web form that upload files to your UPLOADit server. For more information on setting up your web form, please see the Chapter 2, "How to set up your Web Page Form", in this documentation.)


Example

External("Upld-Port", "7777")

Related


Possible Error Responses [?]

"You cannot change the port when the server is running. Stop the server and try again."
You tried to change the port after the UPLOADit server was started.
"Could not allocate memory for the Upload Server."
The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.

Upld-Register

Use this function to register your copy of UPLOADit. There are two ways you can use this function. If you specify the parameter "DIALOG", the plug-in will display a dialog asking you to fill in your registration information. Alternatively, you can specify your registration information in the order "First Name", "Last Name", and "Registration Number" all separated by the pipe character ("|"; usually created by typing shift-backslash). Whenever you use this function, you will be presented with a dialog containing our License Agreement for the plug-in that asks you to accept the agreement. If you need to use this function in a startup script to register the plug-in every time the solution starts, you can auto-accept the License Agreement by adding "|I Accept the License Agreement" to the end of your registration information.


Example

External("Upld-Register", "DIALOG")
External("Upld-Register", "John|Doe|12-3456-7890-ABC-DEF-01")
External("Upld-Register", "First Name|Last Name|Registration Number|I Accept the License Agreement")

Upld-ReleaseClient

When a user uploads a file to your UPLOADit server, and you have defined a database and script to run when this happens, UPLOADit will call that script in your database. In the script that UPLOADit calls, you can retrieve the values from the form that you need, possibly set a Result URL, and then you must release the user's web browser so that it can be redirected to its final location. Use this function to do that. If you do not use this function to release the user's web browser, the user's web browser will never get redirected and will either sit there forever doing nothing, or eventually time out and tell the user that the server did not respond. This function does not take a parameter, so you can use the empty string ("").


Example

External("Upld-ReleaseClient", "")

Related


Possible Error Responses [?]

"There is no client connected."
If you get this error, you have either already called "Upld-ReleaseClient", or you are not calling this function from the script that you have told UPLOADit to call when someone uploads a file.

Upld-SetResultURL

When a user uploads a file to your UPLOADit server, and you have defined a database and script to run when this happens, UPLOADit will call that script in your database. In the script that UPLOADit calls, you can retrieve the values from the form that you need, and based on those values, you can decide if you need to redirect the user's web browser to an alternate page than what is defined in the realm or in the web form. You would then release the user's web browser to redirect it to the URL you have specified. One possible use for this feature is to validate the information the user has filled into your web form. For example, if your form asks for their name, zip code, and their resume file, and they submit the form without filling in their name field, you could redirect their web browser to an "error" page instead of the default "thank you" page that you have defined in your realm. (For more information on setting the Result URL based on form field values, please see Chapter 3, "How to set up your UPLOADit FileMaker Script".)


Example

External("Upld-SetResultURL", "http://www.yahoo.com/")
External("Upld-SetResultURL", "http://www.myserver.com/error.htm?desc=Missing%20Name")

Related


Possible Error Responses [?]

"There is no client connected."
A user's web browser must be connected to your UPLOADit server to set the Result URL to forward their web browser to after you release the client. If you get this error, you have either already called "Upld-ReleaseClient", or you are not calling this function from the script that you have told UPLOADit to call when someone uploads a file.
"You must specify the Result URL."
You did not specify the Result URL you want to set.

Upld-StartServer

Use this function to start your UPLOADit server. This function first loads your realms from the UPLOADit_Realms.xml file, and then starts the server if it could successfully load the realm file. If this function has a problem loading the UPLOADit_Realms.xml file, it will report that error to your result field and not start the server. If you make changes to the UPLOADit_Realms.xml file on your hard drive, you will need to stop (using the Upld-StopServer function) and restart the server (using this function). If you make changes to the realms using the Upld-DefineRealmXML function or through the Configuration Dialog, those changes are active immediately; you do not need to stop and restart the server for those changes to take effect. (Changes made through the Upld-DefineRealmXML function or through the Configuration Dialog will be saved to your UPLOADit_Realms.xml file so that they will be retained if you do stop and restart your server, though.) This function does not take a parameter, so you can use the empty string ("").


Example

External("Upld-StartServer", "")

Related


Possible Error Responses [?]

"Max Connections needs to at least be set to 1."
The Max Connections setting was set to 0, which means that no one would be able to connect.
"Port is invalid: XXX"
The port you specified is invalid.
"There was an error creating the server connection; check the Port."
The plug-in could not start listening for incoming connections. You might want to check the TCP/IP Port to make sure it is not conflicting with another service on your computer. If you are on OS X, you may need to make sure you are not trying to use a TCP/IP Port number less than 1024.
"Error Loading Realm XML File: XXX; Line: YYY; Column: ZZZ"
The plug-in had a problem parsing the UPLOADit_Realms.xml file. The error will be XXX. The error occurred at line YYY, column ZZZ in the UPLOADit_Realms.xml file.
"The server has already been started on port: XXX"
The UPLOADit server is already running on TCP/IP Port XXX.
"Could not allocate memory for the Upload Server."
The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.
"Error parsing parameters: XXX"
The function had a problem parsing the parameters you gave it. Please check the function definition above for the proper parameter syntax.

Upld-StopServer

Use this function to stop your UPLOADit server. If you make changes to your UPLOADit_Realms.xml file on your hard drive, you can use this function and then the "Upld-StartServer" function to enable your changes. This function does not take a parameter, so you can use the empty string ("").


Example

External("Upld-StopServer", "")

Related


Possible Error Responses [?]

"Upload Server Object is NULL."
The plug-in could not create an instance of the UPLOADit Server. Most likely, this will never happen.

Upld-Version

Use this function to return the version of the UPLOADit plug-in you have loaded in FileMaker Pro.

If you will be using the Auto Plug-in Update feature of the latest versions of FileMaker Server to distribute this plug-in to FileMaker Pro client machines, you will want to use the special "AUTO UPDATE" parameter with this function. When you use the special "AUTO UPDATE" parameter with this function, it will return the version of the plug-in in a "Auto Update friendly" form that can be used with the TextToNum() calculation function in FileMaker to accurately determine if one version is newer than another. Any time that you will be working with the version of the plug-in for Auto Update purposes, you should use the "AUTO UPDATE" parameter.

You can also use this function to bring up the UPLOADit Configuration Dialog without having to go through FileMaker Pro's Application Preferences dialog. If you give this function the parameter "CONFIGURE", it will open the UPLOADit Configuration Dialog just as if you went through FileMaker Pro's Application Preferences dialog. If you give this function the parameter "ABOUT", it will open the UPLOADit Configuration Dialog, but the first tab that will be shown will be the "About" tab, which contains version and registration information for the plug-in.


Example

External("Upld-Version", "")
External("Upld-Version", "AUTO UPDATE")
External("Upld-Version", "CONFIGURE")
External("Upld-Version", "ABOUT")

Appendix B: Realm Tags

This 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.

Allowed IP Addresses

The Allowed IP Addresses are a list of IP addresses that are allowed to connect to your UPLOADit server. If you have blocked a range of IP addresses, you can unblock certain IP addresses using these allowed IP addresses. You can unblock all IP addresses by using the word "all". You can unblock a single IP address by specifying that single IP address. You can unblock a range of IP addresses by specifying the starting IP address, followed by a dash ("-"), followed by the ending IP address. By default, all IP addresses are allowed to connect to your UPLOADit server. For more information on how UPLOADit determines if an IP address will be blocked, please see Chapter 7, "IP Address Checking". You can define a default list of allowed IP addresses for the plug-in to use if you have not defined a list of allowed IP addresses in your named realm.


Example

<allowip>all</allowip>
<defaultallowip>172.16.0.25</defaultallowip>
<defaultallowip>192.168.0.50-192.168.0.100</defaultallowip>

Related


Database

The Database value is the database that contains the script the plug-in needs to call when a user uploads a file to your UPLOADit server. If you define a database to use, the database must be open when a user uploads a file to your UPLOADit server. Otherwise, the plug-in will not be able to tell your database that a user has uploaded a file, and your database will not be able to release the user's web browser to redirect it to its final location. If this database is not open when a user tries to upload a file to your UPLOADit server, the user will receive an error web page telling them that the database is not open. You can define a default database for the plug-in to use if you have not defined a database in your named realm.


Example

<database>mydb.fp5</database>
<defaultdatabase>UPLOADit.fp5</defaultdatabase>

Related


Denied IP Addresses

The Denied IP Addresses are a list of IP addresses that are not allowed to connect to your UPLOADit server. If a user with one of these IP addresses tries to connect to your UPLOADit server, the plug-in will return an error web page to them telling them their IP address has been blocked. You can block all IP addresses by using the word "all". You can block a single IP address by specifying that single IP address. You can block a range of IP addresses by specifying the starting IP address, followed by a dash ("-"), followed by the ending IP address. If you block all IP addresses, or if you block a range of IP addresses, you can unblock certain IP addresses by specifying those IP addresses in the Allowed IP Addresses list. By default, all IP addresses are allowed to connect to your UPLOADit server. For more information on how UPLOADit determines if an IP address will be blocked, please see Chapter 7, "IP Address Checking". You can define a default list of denied IP addresses for the plug-in to use if you have not defined a list of denied IP addresses in your named realm.


Example

<denyip>all</denyip>
<denyip>192.168.0.100</denyip>
<defaultdenyip>172.16.0.1-172.16.0.255</defaultdenyip>

Related


Maximum File Count

The Maximum File Count setting will be used by the plug-in to limit the number of files a user can upload in a single connection to your UPLOADit Server. If a user tries to upload more files than the maximum file count you define, the plug-in will return an error page to the user telling them that the number of files they tried to upload was greater than the allowed number. You can define a default maximum file count for the plug-in to use if you have not defined a maximum file count in your named realm.


Example

<maxfilecount>5</maxfilecount>
<defaultmaxfilecount>2</defaultmaxfilecount>

Related


Maximum File Size

The Maximum File Size setting will be used by the plug-in to limit the size of files that a user can upload to your UPLOADit Server. If a user tries to upload a file larger than the maximum file size you define, the plug-in will return an error web page to the user telling them that the file they tried to upload was too large. This value is a number followed by three optional letters, "k", "m", and "g" which stand for "kilobyte", "megabyte", and "gigabyte" respectively. If you want to limit the file size to 256 bytes, you would specify "256". If you want to limit the file size to 16 kilobytes, you would specify either "16384" or simply "16k". If you want to limit the file size to 2 megabytes, you would specify either "2097152" or simply "2m", etc. You can define a default maximum file size for the plug-in to use if you have not defined a maximum file size in your named realm.


Example

<maxfilesize>16k</maxfilesize>
<defaultmaxfilesize>2m</defaultmaxfilesize>

Related


Password

The Password value is used by the plug-in to present users with a standard Web Browser Password dialog to request a password to upload a file to your UPLOADit server. If you define a password for your realm, then when a user tries to upload a file to your UPLOADit server, their web browser will display a dialog asking for a username and password to access your server. They can put anything they want in the "User Name" field, but what they put in the "Password" field must match the password you have defined. (If want to know what the user entered into the "User Name" field, you can use the "Upld-GetFieldValue" function with the "UPLOADit_User" parameter.) You can define a default password for the plug-in to use if you have not defined a password in your named realm. (Note: The password will always be stored as plain text in the UPLOADit_Realms.xml file. When editing the realm with the UPLOADit Configuration Dialog, the password will be obscured by bullets.)


Example

<password>secret</password>
<defaultpassword>test</defaultpassword>

Related


Realm Name

The name of the Realm is what you use to differentiate between multiple realms that you have defined. Naming your realms allows you to have multiple realms for different users or groups of users to upload files to your UPLOADit server. The realm name is used in the Action parameter of your web form to tell your UPLOADit server what realm the form applies to, which dictates the rest of the realm settings, such as where to save the files on the hard drive. Realm names must be unique and are case-insensitive. While it is possible to include spaces and accented characters or other special characters in the name, it is best to use only letters and numbers in your realm name and exclude any spaces from the name.


Example

<realm name="myrealm">

Result URL

The Result URL is the URL (web address) that the plug-in will redirect the users' web browser to after they have uploaded a file (and after you have called the "Upld-ReleaseClient" function if you have a database and script defined for your realm). You can define a default result url for the plug-in to use if you have not defined a result url in your named realm.


Example

<resulturl>http://www.yahoo.com/</resulturl>
<defaultresulturl>http://www.myserver.com/thankyou.htm</defaultresulturl>

Script

The Script value is the script in your database the plug-in needs to call when a user uploads a file to your UPLOADit server. If you define a script to use, the script must exist in your database when a user uploads a file to your UPLOADit server. Otherwise, the plug-in will not be able to tell your database that a user has uploaded a file, and your database will not be able to release the user's web browser to redirect it to its final location. If the script is not defined in the database when a user tries to upload a file to your UPLOADit server, the user will receive an error web page telling them that the script could not be found in the database. You can define a default script for the plug-in to use if you have not defined a script in your named realm.


Example

<script>UPLOADit</script>
<defaultscript>New File</defaultscript>

Related


System Administrator's Email Address

The System Administrator's Email Address is used whenever the plug-in needs to return an error web page to the users' web browsers. If there is a problem uploading the file or if there is any other reason to return an error web page to the browser (like if the user's IP Address has been blocked), the System Administrator's Email Address is included in the error web page so that users can email somebody if they think they should not be getting the error or if they do not understand the error. You can define a default system administrator email address for the plug-in to use if you have not defined a system administrator email address in your named realm.


Example

<sysadmin>webmaster@mydomain.com</sysadmin>
<defaultsysadmin>"John Doe" <john.doe@mydomain.com></defaultsysadmin>

Upload Path

The Upload Path is the full path on your hard drive to the folder (directory) where files are placed when users upload them from their web browser. If the folder does not exist, the plug-in will create it when you start your UPLOADit server. You can define a default upload path for the plug-in to use if you have not defined an upload path in your named realm.


Example

<path>/UPLOADit/</path>
<defaultpath>C:\UPLOADit\</defaultpath>

Related


UPLOADit Tag

The <UPLOADit> tag is the root tag for the XML document. This tag contains all the other UPLOADit xml tags and must appear in your XML file. This tag is the equivalent to the <HTML> tag in HTML files.


Example

<UPLOADit>
...
</UPLOADit>

When File Exists

The When File Exists value is used by the plug-in to determine what action to take when a user uploads a file with the same name as an existing file on your UPLOADit server. The three options you can select are "Make Unique", "Backup", and "Overwrite".

The "Make Unique" option will take the name of the newly uploaded file and append a number to the end making the file unique. For example, if there is an existing file named "image.jpg" on your server, and a user uploads a file with the name "image.jpg", the new file will be saved to your hard drive with the name "image1.jpg". If a second user uploads a file with the name "image.jpg", the new file will be saved to your hard drive with the name "image2.jpg", etc.

The "Backup" option will rename the existing file with the word "Backup" in it, and then save the newly uploaded file to your hard drive with the existing name. For example, if there is an existing file named "image.jpg" on your server, and a user uploads a file with the name "image.jpg", the existing file will be renamed to "image Backup.jpg", and the new file will be saved to your hard drive with the name "image.jpg". If a second user uploads a file with the name "image.jpg", the existing file be renamed to "image Backup1.jpg", and the new file will be saved to your hard drive with the name "image.jpg", etc.

The "Overwrite" option will simply overwrite the existing file with the newly uploaded file.

You can define a default when file exists value for the plug-in to use if you have not defined a when file exists value in your named realm.


Example

<whenfileexists>make unique</whenfileexists>
<whenfileexists>backup</whenfileexists>
<defaultwhenfileexists>overwrite</defaultwhenfileexists>

Related


Appendix C: Function Error Responses


Understanding Error Responses

Every function in UPLOADit returns a response indicating the success or failure of that function. If the function is successful, it will return a response indicating that it set the value you were trying to set, completed the task that needed to be completed, or return the information that you requested. If however, the function is not successful, it will return an Error Response. This Error Response will be in the form:

  1. ERROR: <Function Name>: <Error Description>
Figure C.1 Error Response Example

For example, if you call the Upld-DeleteRealm function without specifying a parameter, the function would return the following Error Response:

  1. ERROR: DeleteRealm: You must specify the name of the Realm to Delete.
Figure C.2 Error Response Example

Error Responses always start with the word "ERROR" in all caps, followed by a colon, followed by the function that had the error, followed by a colon, followed by the actual error that occurred. You can use the various FileMaker Calculation Text Functions to extract the different parts of the Error Response for your own use. For instance, if you want to know if the response you received from a function was an error, you can use the LeftWords() Calculation function to return the first word and see if it is "ERROR". An example of this is as follows:

  1. Set Field [Result, External("Upld-DeleteRealm, "myrealm"]
  2. If [LeftWords(Result, 1) = "ERROR"]
  3. Show Message ["Could not delete realm"]
  4. Else
  5. Show Message ["The realm was deleted."]
  6. End If
Figure C.3 Error Response Script

Appendix D: Browser Errors

This 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.

Blocked IP Address

"This server is currently blocking your IP address."


You would get this error if your IP address was blocked by the realm you are trying to upload to, or by the default realm. Check your UPLOADit_Realm.xml file to see if your IP address is being blocked with the <denyip> and/or <defaultdenyip> tags. You may also need to refer to Chapter 7, "IP Address Checking".


Could Not Get File Name

"The Server had a problem getting the file name for the file you are trying to upload."


This error would come up if for some reason the plug-in could not find or decode the file name of the file you are trying to upload. Most likely you will never see this error.


Database/Script Problem

"There was a problem with the database or script for this realm: XXXX"


This error will come up if UPLOADit has a problem locating the database and script defined for the realm, or running that script. The "XXXX" above will be replaced with the specific error the plug-in had.


Disk Error

"The Server could not write data to the disk."


This error would come up if the plug-in had a problem writing data to the hard drive. It may mean that the hard drive is full.


Error Receiving Data

"The server had an error receiving data or came to an unexpected end of the data stream. Please try again."


If the plug-in has a problem reading the data from the web browser, or if the web browser does not format the data correctly when sending to the plug-in, you will get this error. Of course, if the web browser was closed or crashed when trying to upload data to the plug-in, then the plug-in wouldn't be able to display this error to the user.


File Error

"The Server could not create a file on the disk for the incoming file."


You might get this error if the hard drive was full or write protected.


File Error

"The Server could not create an FSSpec for the incoming file."


You may get this error on the Mac if the plug-in cannot create a file with the correct file name.


File Error

"The Server could not open the file for writing for the incoming file."


You may get this error if the hard drive is full or write protected.


File is too Large

"This Server does not accept files over XXXX bytes."


You would get this error if you are trying to upload a file that is larger than the Maximum File Size setting allows. Check your UPLOADit_Realms.xml file to see if the Maximum File Size setting you have defined for your realm is smaller than the file you are trying to upload.


File Stream Error

"The Server could not create a file stream for the incoming file."


You may get this error if the hard drive is full or write protected.


Invalid Content-Type

"This server only accepts 'multipart/form-data' Content-Types."


The plug-in can only accept form data in one way. If you get this error, check to make sure the "enctype" attribute of your <form> tag is set to "multipart/form-data".


Malformed Authorization Header

"The Authorization Header was not correct."


You would get this error if your web browser did not send the username/password authentication header correctly. Most likely, this will never happen.


Malformed Headers

"The HTTP Headers were not correct - Content-Type Missing Multipart Boundary."


The plug-in can only accept form data in one way. If you get this error, check to make sure the "enctype" attribute of your <form> tag is set to "multipart/form-data".


Malformed Headers

"The HTTP Headers were not correct - Missing Content-Type."


You would get this error if your web browser did not properly format the HTTP headers. Most likely this will never happen.


Malformed Method

"The HTTP Method was either missing or malformed."


You would get this error if your web browser did not correctly format the HTTP Headers. Most likely this will never happen.


Malformed Request/Realm

"The HTTP Request/Realm was either missing or malformed."


You would get this error if your web browser did not format the HTTP headers correctly. Most likely, this will never happen.


Memory Error

"The Server could not create a memory buffer for the incoming file."


You may get this error if the plug-in is out of memory. Most likely, this will never happen.


Memory Error

"The server had a memory error while trying to receive data. Please try again."


You may get this error if the plug-in is out of memory. Most likely, this will never happen.


Realm Not Found

"Realm Not Found: XXXX"


You would get this error if the realm you defined in the "action" attribute of your <form> tag was not valid or misspelled. However, if the plug-in cannot find the realm you define, it falls back to the default realm, so you may never see this error.


Result URL Error

"The Server was not given a Result URL to forward you to after you submitted the form. Please contact the system administrator."


You would get this error if the plug-in did not have a Result URL to redirect the web browser to after a user uploads a file. Check to make sure you have defined the Result URL either in the UPLOADit_Realms.xml file (using a <resulturl> tag), the web form (using a form element with the name "UPLOADit_Result_URL"), or in your scripts (using "Upld-SetResultURL").


Too Many Files

"This Server does not accept more than XXXX files."


You would get this error if your realm has a maximum number of files defined and you are trying to upload more files than are allowed.


Unauthorized

"The password you supplied was not correct."


If you have defined a password for your realm, you would get this error if you typed in the wrong password from the web browser and then canceled the attempt to re-enter your password.


Unauthorized

"You need to specify a password in order to upload files to this server."


You would get this error if you have a password defined for your realm, but cancel the username password dialog your web browser displays. Usually, the web browser does not display these errors and simply prompts you for your username and password.


Unknown Error

"The server had an unknown error while trying to receive data. Please try again."


This is sort of a catch all error. Hopefully, you will never see this error.


Unsupported HTTP Version

"This server only accepts HTTP/1.0 and HTTP/1.1 requests."


You would get this error if your web browser is not compliant with HTTP/1.0 or HTTP/1.1. Most likely, this will never happen.


Unsupported Method

"This server only accepts the POST Method."


You would get this error if you tried to browse directly to the plug-in with your web browser. Since UPLOADit does not have the capability to serve web pages, and only accepts form uploads, this error would be displayed.


Appendix E: UPLOADit Flow Chart

Following is general view of how a file gets from the browser to FileMaker.

Step 1


Step 2


Appendix F: Glossary

Here are several definitions that you may find helpful while reading the UPLOADit documentation.

CGI

This is an acronym that stands for "Common Gateway Interface". Basically, it's a program that sits on a web server and handles special requests from web browsers. The Web Companion in FileMaker is an example of a CGI that allows you to view the contents of your database in your web browser. The UPLOADit plug-in also acts as a CGI.

Domain

A Domain identifies a computer, usually one that hosts some service that you can access, like a web service. "www.filemaker.com" is a domain which identifies FileMaker, Inc.'s web service, which you can get to with any web browser.

Form

A Form is something that can be included in an HTML web page that allows a user to type information into fields which can be submitted to a CGI for processing. You can use a Form to add a new record to your database using the Web Companion. You use a Form with UPLOADit to specify a file that you would like to upload to your FileMaker computer.

IP Address

An IP Address identifies a computer on a network, such as the Internet. You can use an IP address instead of a Domain name to access some internet services. While every computer on the Internet has an IP address, not every computer on the Internet has a Domain name. UPLOADit uses IP Addresses to determine if a user can connect his or her computer to the UPLOADit server you have running.

Realm

UPLOADit uses the term "Realm" to define a collection of settings that control how a user uploads a file to your UPLOADit server. The Realm has settings in it that define where a file will be placed on your hard drive, how big that file can be, the database and script to use when a user uploads a file, and several other things. You can have multiple Realms defined for your UPLOADit server which allows different users or groups of users to upload files to separate places on your hard drive.

TCP/IP Port

All Internet services listen on specific TCP/IP Ports. If the Internet was a street, and a Domain name (or IP address) was an apartment building, the individual apartments in a single apartment building would be the TCP/IP Ports. Most Internet services hide the TCP/IP Port setting from you because they are almost always the same. For instance, most web services listen on TCP/IP Port 80, so when typing a URL into the Location Bar of your web browser, you only have to type in the Domain name. UPLOADit uses port 8080 by default.

UPLOADit_Realms.xml

The UPLOADit_Realms.xml file stores the Realms you have defined for your UPLOADit server. For more information about the XML tags in this document, please see Appendix B.

URL

This is an acronym that stands for "Universal Resource Locator". All it is the domain name and file path you type into the Location Bar in your web browser. "http://www.filemaker.com/" is a URL, as is "http://www.cnsplug-ins.com/products.htm?product=UPLOADit".