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