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.