- Application type
- Mobile Settings
- HTML5 Image Capture Settings
- Cordova / PhoneGap Settings
- Image File Upload
- Customization - File Select Window
- Customized Error Messages
- Server-side Events
- Client-side Events
- Filename for Uploaded File
- File Rename
- Xbasic Event Handlers - Control Values
- Image Upload in a UX Component
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
- Specify where the application will be running.
- 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.
- 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.
- 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 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.
- Window title
- Specify the title of the File Select dialog window.
- Window position
- Specify where the window will be shown.
- 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.
- 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.
- 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.
- 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.
- 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.
- Before upload
- After upload
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').
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.
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:
- the filename for the uploaded file (computed based on the setting for the UploadFolder and the name of the file on the client machine
- 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
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).
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".
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.