Web Applications - Image Upload Feature Pack

To purchase this Feature Pack, please click here. To purchase the File Upload, Image Upload and File/Image Download Feature Pack Bundle click here.

The Image Upload Feature Pack allows you to upload images from the user's machine to the server.

Here are some of the things you can do with the Image Upload Feature Pack:

Define a button that will upload an image to the server and store the filename of the uploaded image in a field in the current Grid record (this is a 'linked image')
Define a button that will upload an image to the server and store the binary contents of the file in a BLOB field in the current Grid record (this is an 'embedded image')
Scale the uploaded images before that are saved. You can scale the image by specifying a percentage of the source image, or you can specify absolute dimensions (in either inches or pixels).
Optionally preview how the image looks in the Grid after is has been uploaded, and then undo the action.
Turn on the 'Insert image' button in the HTML editor (used for editing memo fields in the current Grid record) so that you can upload images to the server and then put the image in the HTML memo that you are editing.
Note: If you have the optional File Upload Feature Pack, then there is also an 'Insert linked file'' button that you can display on the HTML Editor toolbar. This allows you to upload files to the server and insert hyperlinks to these files in the HTML memo that you are editing.

When you have the Image Upload Feature Pack installed the following new options become enabled in the Grid builder:

New 'Image Upload' action in Action Javascript
New options for configuring the HTML Editor for Memo fields - you can turn on/off the 'Insert image' button on the HTML Editor toolbar.

Note: If you want to upload files, rather than images, File Upload Feature Pack might be better suited to your needs.

New Action Javascript Actions

The 'Upload Image' action allows you to upload an image and then either store a link to that image in a field in the current record, or embed the image in a field in the current record.

Upload Image Action

The Upload Image action allows you to upload an image file to the server and then store the uploaded image in a field in the Grid table by reference or as an embedded object.

The screenshots below show the builder.

First part of the Image Upload Builder

Scrolled View of the Image Upload Builder

Image Field

The builder allows you to select a field in the Grid in which the uploaded image file will be stored (either by reference, or as an embedded object). Only the controls on the Grid that have a control type of 'Image' are shown in the dropdown box when you select the field.

If you select a character field (this would include a .dbf file of type Image File Reference), then the uploaded image is stored by reference (i.e. the field in the table stores the name of the image file). If you select a BLOB field (this would include the .dbf JPeg and Bitmap fields), then the uploaded image is stored as an embedded object.

VERY IMPORTANT: Be sure that you have set the Updateable property of the Image field to allow updates!

Scale Image

You can optionally scale the uploaded image before it is saved to the database. There are several scaling options. You can specify a ratio, or an absolute image size.

If you select a ratio, the dialog to define scaling will look like this:

Scale image dialog if you select the 'Ratio' option.

If you specify an absolute image size, the dialog will look like this:

This dialog allows you to specify a scaling method. The options are 'Scale width and height proportionally' and 'Scale width and height independently'. In the 'Scale width an height proportionally' case you specify a single dimension which applies to the width, height, or if you select 'Maximum dimension' it applies to either the width or the height, depending on which dimension is larger in the source image.

If you select the 'Scale width and height independently' option, then you can specify dimensions for both the height and the width.

NOTE: If you specify a BeforeSave server side event, when the event fires, the image will already have been scaled if you define a scaling option. So, if your event also scales the image, it will be scaling an already scaled image.

Allowed and Disallowed File Extensions

You can limit the types of files that the user can upload. You can either supply a list of allowed extensions, or a list of disallowed extensions.

Embedded Image Format

This property is shown if the Grid is based on a SQL database and you have selected a binary field as the image target. You must specify whether the image will be stored as a jpeg or bmp object.

Upload Folder, File exists action, and Stored filename transformation expression

If the target field is a character field, these properties are displayed:

If you are uploading to a Character Field the Builder prompts for 'Upload folder' , 'File exists action' and 'Stored filename transformation expression'

The Upload Folder is the folder on the server where the uploaded file will be stored. If you specify a relative filename, the folder is in the webroot.

VERY IMPORTANT: If you have the Security Framework turned on, be sure to set the appropriate permissions for this upload folder and the files that it contains.

The File exists action can either be 'Rename' (so that it does not overwrite an existing file in the Upload Folder) or 'Overwrite' (so that any existing file would be automatically overwritten.

The Stored filename transformation expression allows you to define an Xbasic expression to transform the actual filename of the uploaded file to a value that should be stored in the target field. When you click the smart field associated with this property, the help text gives examples. For example, you might just want to store the relative filename of the uploaded file.

Maximum file size

You can specify the maximum size of the file that the server will accept. Unfortunately, it is not possible to know what the file size of the uploaded file is until after it has been uploaded. Only after the file has been uploaded can the server check the size of the file and send back a message to the client saying that the file was too large.

Auto upload

If you check this button then as soon as the user selects a file, the upload begins. Otherwise, the user must press the Upload button.

Previewing the Uploaded Image

After the image has been uploaded, you can optionally preview the image before saving it to the database. If you want to preview the image after it has been uploaded, then un-check the 'Close file select window after upload' property.

The screenshot shown below shows the File Select window with a preview of the image that was just uploaded. Notice that the window shows the image, but the image field in the Grid also shows the image that was just uploaded. If you cancel at this point, the image that is shown in the Grid will revert to its original value.

File Upload Window showing a preview of the image that was uploaded

If the 'Close file select window after upload' property is unchecked, you will see a number of options for customizing the appearance of the window in which the uploaded image can be previewed. One big advantage of previewing the uploaded image is that it allows you to change your mind and NOT save the uploaded image to the database.

If you do not preview the uploaded image, then the image is saved to the database as soon as the upload completes and the action cannot be undone.

Server-Side Events

This action exposes two server-side Xbasic events:

beforeSave
onSave

The BeforeSave Event

This event is called as soon as the uploaded file has been received by the Server. The event can abort the action.

Some of the ways in which this event can be used include:

check the binary data to ensure that it is a valid image
scale the image to a different size

After you have specified the name of the event, click on the hyperlink to get a sample function prototype. Copy this prototype to the clipboard, and then paste it into the Xbasic Function Declarations property of the Grid.

The function prototype shows what properties are in the 'e' object that is passed into the Xbasic function.

Notice that if you want to abort the action, set e.abort = .t. and e.abortMessage to the reason why the action was aborted. This message is displayed to the user.

Here is a sample function prototype:

function xbBeforeSave as v (e as p)
'This function is called after an image has been uploaded, but before it is saved to a field in the current record.
'The binary data that was uploaded is passed into the function. Your script can check if it is a valid image and abort if not.
'The most typical reason for defining this event handler is to scale the image before it is saved.

'The e object that is passed in contains:
'e.fileBlob - the binary data that was uploaded. Your script can manipulate this value.
'e.uploadedFilename - the filename of the file on the client computer

'In addition, e contains
'e.tmpl - the Grid definition
'e.rv - request variables
'e.rtc - a pointer variable that is passed to all server side events

'Your event can set these two properties
'e.abort - if you set this to .t., the uploaded file is not saved to the database
'e.abortMessage - message to display to user why the action was aborted.

end function

Note: While your event handler can scale the image, it is also possible to scale the image by setting the 'Scale image' property. If you want to have more control over how the image is scaled, then you should NOT define a 'Scale image' property and instead, do the scaling in the BeforeSave event.

If you want to write you own scaling functionality, you might find the a5_scale_imageBlob() function to be useful. See the Release Notes for Version 10 for more information on this function.

The OnSave Event

The OnSave event is called after the uploaded image has been processed and is ready to saved into a field in the current Grid record. A typical use of this event would be to save a thumbnail of the uploaded image at the same time that the image itself is saved in the Grid record.

The function prototype shows what properties are in the 'e' object that is passed into the Xbasic function.

Here is a sample function prototype:

function xbOnSave as v (e as p)
'This function is called when the uploaded image data is saved to a record in the Grid.
'A possible use of this function would be to save a thumbnail of the uploaded image in another field in the current record.

'The e object that is passed in contains:
'e.tmpl - the Grid definition
'e.rv - request variables
'e.rtc - a pointer variable that is passed to all server side events
'e.__si - state information
'e.ops = misc properties that were defined in the builder for the image upload action
'e.tableType - 'SQL' or 'DBF'
'e.tempImageFilenameOnServer - temporary file in the session folder where the uploaded image was stored

'If the Grid is based on a SQL database (e.tableType = 'SQL'), then e contains:
'e.cn - a pointer to an open connection to the database
'e.args - the sql::arguments object that contains the data that was passed to the query that saved the data
'e.targetFieldType - the data type of the field in which the image is stored ('C' - character or 'B' - binary)
'e.embeddedImageFormat - in the case where the image is embedded, the format (jpg or bmp) that the image was converted to before it was stored in the table

'If the Grid is based on a DBF database (e.tableType = 'DBF'), then e contains:
'e.targetFieldType - the data type of the field in which the image is stored ('I' - image file ref, 'C' - character, 'J' - jpeg, or 'B' - bmp)
'e.tbl = tbl - pointer to the open table in which the uploaded imaged was stored - DO NOT CLOSE THIS TABLE!!.

'e.imageFilenameOnServer - if the image was linked (i.e. stored in a Character field or Image File Ref Field (dbf only)), the full filename of the image file on the server. This property if blank if the image is embedded.
'e.imageBlob - if the image is embedded, the binary image data (after it has been converted to the required type)
'e.valueStoredInField - if the image was linked (i.e. stored in a Character or Image File Ref Field (dbf only) ), the actual filename (after it has been transformed) that was stored in the character field.

end function

Uploading Images when Using the HTML Editor

Important: This feature is not supported in Working Preview mode.

Watch Video - Uploading Images into the HTML Editor

If the Image Upload Feature Pack is installed, then the Field Properties dialog for a Memo field will show a new property: 'Allow image upload'.

Note: If the optional File Upload Feature Pack is installed, then the Field Properties dialog for a Memo field also shows the 'Allow file upload' property.

The 'File Upload' feature allows you to upload files (e.g. .pdf, .excel, .doc, etc.) and then put hyperlinks to these files in the HTML memo.

Image shows the Field Properties Dialog for an HTML Memo field if both the File Upload and Image Upload Feature Packs are Installed.

If 'Allow image upload' is enabled, then you must specify the folder where uploaded images are stored. You must enter a relative folder name here. The folder will be created in the webroot if it does not already exist.

If you allow image upload, then the toolbar will show a new button when you are editing the memo.

If you click the icon, the File Select window appears:

The wording and icons used in the window can be customized by clicking on the 'Image upload dialog customization' property smart field.

Image selection window

Here is how the HTML memo field might look after an image has been uploaded: