First, we will look at an example UPLOADit_Realms.xml file, which holds information about the realms your users can upload files to. Here is the example realm file we will be using for this chapter:
- <UPLOADit>
- <defaultsysadmin>webmaster@mydomain.com</defaultsysadmin>
- <defaultresulturl>http://www.mydomain.com/thanks.htm</defaultresulturl>
- <realm name="test">
- <path>/UPLOADit/test/</path>
- <database>mydb.fp5</database>
- <script>UPLOADit Test Realm</script>
- </realm>
- </UPLOADit>
Second, here is an example web form page that we will base the rest of the chapter on:
- <html>
- <head>
- <title>UPLOADit test</title>
- </head>
- <body>
- <form name="UPLOADit_Form" method="post" action="http://www.mydomain.com:8080/test/" enctype="multipart/form-data">
- <input type="hidden" name="id" value="392">
- <p>Please fill in your First and Last Name, then select a file, and then press the submit button.</p>
- <p>First Name: <input type="text" name="First_Name"></p>
- <p>Last Name: <input type="text" name="Last_Name"></p>
- <p>File to Upload: <input type="file" name="UPLOADit_File"></p>
- <p><input type="submit" value="Submit"></p>
- </form>
- </body>
- </html>
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:
- New Record/Request
- Set Field [id, External("Upld-GetFieldValue", "id")]
- Set Field [First Name, External("Upld-GetFieldValue", "First_Name")]
- Set Field [Last Name, External("Upld-GetFieldValue", "Last_Name")]
- Set Field [File Name, External("Upld-GetFieldValue", "UPLOADit_File")]
- Set Field [UPLOADit Result, External("Upld-ReleaseClient", "")]
- Exit Record/Request
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:
- Set Error Capture [On]
- Enter Find Mode []
- Set Field [id, External("Upld-GetFieldValue", "id")]
- Perform Find [Replace Found Set]
- If [Status(CurrentError) = 0]
- Set Field [First Name, External("Upld-GetFieldValue", "First_Name")]
- Set Field [Last Name, External("Upld-GetFieldValue", "Last_Name")]
- Set Field [File Name, External("Upld-GetFieldValue", "UPLOADit_File")]
- Else
- Show All Records
- Set Field [UPLOADit Result, External("Upld-SetResultURL", "http://www.mydomain.com/error.htm"]
- End If
- Set Field [UPLOADit Result, External("Upld-ReleaseClient", "")]
- Exit Record/Request
- Set Error Capture [Off]
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.