Image Upload

Description

Upload an image file to the server.

Used with the Grid and UX components. First it is necessary to add an image to the component.

 Application type

Application type
Specify where the application will be running.

 Mobile Settings

Cordova/PhoneGap or HTML5
Specify if the mobile app is running in a native shell (where Cordova is available), or is running in a browser (where only HTML5 upload) is available.

 HTML5 Image Capture Settings

Resize and compress image before upload?
Native image files are quite large and should be compressed prior to uploaded.
Compression folder
Valid compression factors are from 0.1 to 1.0, with 1.0 being minimal compression.
Image Max Width
Maximum image width of uploaded image, aspect ratio will be maintained. This value is optional. The default is 1024.
Image Max Height
Maximum image height of uploaded image, aspect ratio will be maintained. This value is optional.

 Cordova / PhoneGap Settings

Using PhoneGap Build
If you intend to use the integrated PhoneGap App Builder genie with PhoneGap Build, make sure to enable this property.
Cordova picture source
Picture source can be Photo library or Camera.
Image quality
Determines compression factor, a number from 1 to 100 is valid. 50 is recommended due to memory constraints.
Allow editing
Allows the user to zoom and crop the image prior to final image selection.
Image width
Saved image width, optional. The default is 1024.
Image height
Saved image height, optional. The default is 1024.
Save picture to photo album
When enabled, the image is saved to the device's photo library.

 Image File Upload

Image field
Specify the name of the field in the component that will display the uploaded image.
Scale image
You can optionally scale the image before it is saved on the server, or embedded in a component field.
Allowed image filename extensions
Specify a comma delimited list of allowed filename extensions. If the user uploads a file that does not match an allowed extension, the operation is aborted.
Invalid extension error message
The message to display when the selected file is not an allowed file type.
Upload target
Specify if the image should be uploaded to the Alpha Anywhere server, or to a cloud storage provider (e.g. Amazon S3).
Upload folder
Specify the name of the folder where the uploaded image file will be stored. You can use aliases in the name. If you enter a folder without a drive letter, the folder is assumed to be in the webroot. Important: The folder that you specify here is a folder on the machine where your Application Server is running, not a folder on this machine. VERY IMPORTANT: If you have the Security Framework turned on and the upload folder is in the webroot, be sure to set the appropriate permissions for this upload folder and the files that it contains. You can use a session variable to specify the uploaded folder.
File exists action
If the file that was uploaded already exists in the Upload folder, what action should be taken. You can either overwrite the existing file, or rename the uploaded file.
Embedded Image format
Specify the image format to use for the embedded image. All embedded images must be stored in the same format. So, for example, if the user uploads a .bmp image and the Embedded Image Format is JPG, the image will be converted to JPG before it is stored in the database.
Stored filename transformation expression
Specify what value to store in the image field. This is typically some transformation of the uploaded image filename. If you leave this blank, the fully qualified filename is stored in the image field.
On Stored filename compute Xbasic function
(Optional) If you want complete control over the filename of the uploaded image, you can call an Xbasic function to compute the filename.
Maximum file size
Specify the maximum file size that can be uploaded. Specify value in bytes. Specify 0 if you do not want to restrict the size of the file that can be uploaded. IMPORTANT: Regardless of this setting, the server also specifies a maximum POST body size. The lower of this setting and your setting for this property will apply.
Maximum file size exceeded message
Specify the message to display to the user if the uploaded file exceeds the maximum allowed file size.
Create image thumbnails
Specify if the image thumbnails should be created from the uploaded image? You can create multiple thumbnails in different sizes.
Show progress/ allow cancel
On certain browsers it is possible to show progress while files are being uploaded and to allow the user to cancel the operation. IE9 and earlier does not support this feature.
Abort upload button label
Specify the text for the Abort button. This button allows a user to stop an upload before it has completed.
Abort upload message
Specify the message to show if the user aborts an upload.
Progress bar type
Specify the type of progress bar. The 'A5' bar uses a specially styled progress bar that blends well with the selected component style. If you are using certain styles (e.g. GrBlue, GrOlive, etc.) you may want to switch to the 'Basic' style.

 Customization - File Select Window

Window title
Specify the title of the File Select dialog window.
Window position
Specify where the window will be shown.
Sub-theme
Specify the window sub-theme
Auto upload
Specify if the should be uploaded as soon as the user has selected the file to upload. Alternatively, the upload will only start once the user has clicked on the 'Upload' button.
Working message
Specify the working message to display while the file is being uploaded to the server.
Upload button
Specify the button text for the 'Upload' button.
Watermark
Specify the watermark text that appears in the file box. If you use a language tag for the text, be sure that the language definition returns a URL encoded value. See hyperlink below for more help.
File select button image
Select the image that appears on the button to open the file select window.
Prompt
Specify the text for the prompt that appears above the file box. If you use a language tag for the text, be sure that the language definition returns a URL encoded value. See hyperlink below for help.
Window height
Specify the height for the pop-up File Select window.
Window width
Specify the width for the pop-up File Select window.
Cancel button label
Specify the label for the Cancel button. Before the image is uploaded, this button closes the dialog. If a confirmation dialog is shown after the image is uploaded, this button aborts the action and does not save the uploaded image to the database.

 Customized Error Messages

Table not updateable
Specify the message to show if the table is not updateable because the logged in user does not have permission to update this table.
Field not updateable
Specify the message to show if the field is not updateable because the logged in user does not have permission to update this field.
Session expired
Specify the message to show if the session has expired. This error could occur if the 'Close File Select window after upload' property is false, the user uploads an image, but then does not click the 'OK' to save button immediately.

 Server-side Events

Before save
Specify the name of the Xbasic function to call after the file has been uploaded, but before it has been saved into the target field in the component. You can use this function to execute code that checks if the binary data that was uploaded is a valid image, or you might want to call a function that scales the image before it is saved to the database. This Xbasic function must be defined in the 'Xbasic functions declarations' section. This function can optionally abort the action.

 Client-side Events

Before upload
Specify the name of the Javascript function to call before the file upload window is shown. If this function returns false, the upload is aborted.
After upload
Specify the name of the Javascript function to call after the file has been successfully uploaded.

 Thumbnails

The Action Javascript builder has an option in the Thumbnail Definition Builder that allows you to specify if the thumbnail file that is created should overwrite an existing file, or be renamed, so as not to conflict with existing files.

When you define how thumbnails are to be created, you can specify if the thumbnail is to be stored as a file on disk, or as binary data in a record. In the case where you specify a file on disk, the builder allows you to specify a 'suffix' that is automatically added to the filename. For example if the suffix is 'thumb1', then the file on disk might called 'image_thumb1.jpg'. However, there may be situations where you don't want the suffix. If you set the suffix to a blank value, the file on disk has no suffix at all (e.g. 'image.jpg').

Prior to Alpha Five Version 12, setting the suffix to a blank value would result in the file on disk being created as 'image_.jpg'.

Of course, if you set the suffix to a blank value, the upload folder for the thumbnails needs to be different than the upload folder for the main image you are uploading, or else when the thumbnail is created, it will overwrite the main image.

 Filename for Uploaded File

When you upload an image or a file to a target character field (rather than a binary field), the uploaded file is saved in a file in the UploadFolder (defined in the builder) and the filename of the file is saved in the target character field. The filename is derived from the filename of the file on the client machine.

A property in the builder allows you to define an Xbasic function in which you can compute the filename to use for the uploaded file.

As shown in the screenshot below, the new 'OnStoredFilename Compute Xbasic Function' property allows you to define the name of an Xbasic function. The Xbasic function exposes the 'e' object which has these properties:

Property
Description
e.targetFileName
the filename for the uploaded file (computed based on the setting for the UploadFolder and the name of the file on the client machine
e.imageBinaryData
binary data that was uploaded

You Xbasic function can change the value in the e.targetFileName property. If you do change this value, the uploaded flle will be stored in the filename specified by the new value in e.targetFileName

The transformation expression (defined in Action Javascript at design time) will be applied to whatever value is in e.targetFilename. So, if your event handler changes the value in e.targetFilename, the transformation expression is applied to this new value.

Your code can optionally set a value for e.storedValue property in the e object. If you set the e.storedValue property, this value will be stored in the target field in the record (and the transformation expression will be ignored).

 File Rename

When you upload images or files and store the uploaded images or files in a filename on a server, there is an option to rename the file if there is an existing file with the same name on the server. Here is how the algorithm that computes the filename in the case of a conflict works. If a filed called "c:\myimages\image1.jpg" exists and you want to create a new file called 'image1.jpg', the new file will be called "c:\myimages\myimage1_1.jpg".

 Xbasic Event Handlers - Control Values

In a UX component, when the server-side Xbasic events defined in the Action Javascript builder fire, the control values for all of the controls on the UX are available to the Xbasic code. For example, assume that the UX had a control called 'FIELD1'. In the Xbasic event handlers, you can reference this value as follows

request.variables.v.r1.field1

 Image Upload in a UX Component

You can upload to an Image control on the component that is, or is not, data bound.

If you upload to a 'data bound' image, then when you submit the UX component, the image field in the table is updated. Watch the video below to learn more.

If you upload to a 'non-data-bound' image control, then when you submit the UX component, your event handler can choose what to do with the uploaded image. Watch the videos below to learn more.

In the case where you upload an image to a non-data bound image control, the afterDialogValidate event needs to load the image from its saved location and store the image in its final destination on the server - either on disk or in a database.

The code example below demonstrates how to get the uploaded image. This example assumes the image was uploaded for an Image control called 'MYIMAGE':

dim blobKey as c
'Every image control has an associated control with a '_hiddena5fn' name.
'After the image has been uploaded, it is stored in temporary session storage
'The 'key' for the data in session storage is stored in this hidden field.

blobKey = e.dataSubmitted.myimage_hiddena5fn
blobKey = word(blobKey,1,":")

dim blobUploaded as b
Session.GetDataFromFile(blobUploaded,blobKey)
Session.DeleteSessionFile(blobKey)

'You now have the uploaded image data in a variable called 'blobUploaded'
'Your event handler can process this data.

You can also upload images to image controls in Repeating Sections. Watch the video below to learn more.

See Also