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