Media files (photos, videos, audio recordings, other) settings

Description

Define settings for uploading media files from the mobile device to the target server. Also define setting for downloading media files from a server to the mobile device. Files can be saved in the device's filesystem, allowing them to be accessed offline.

Discussion

The Upload Target Settings Dialog allows you to define if the media files should be uploaded to the Alpha Anywhere server or to Amazon S3. It can also be used to define where media files are downloaded from and where to store them on the device. In PhoneGap applications, files can be stored in the device's filesystem, allowing the user to access the files when the working in offline.

In the case where you are not using PhoneGap, you can still access photos in your data when you are offline. However, the amount of data you can load into the List will be limited because the photos are stored in Local Storage along with the List data. In order to store images in the List data so that they are available when you are offline, the photo field in your database must be a binary field (as opposed to a character field - which is required if you are using the PhoneGap option) and you must configure the List to embed the image data (as base64 encoded data) into the List (by checking the Embed images into HTML property for the image field in the List settings, Fields pane).

You must define the Upload Settings in the top-most parent List if you have a List hierarchy (i.e. a parent-child relationship between Lists with the child Lists configured to pre-fetch their data).
The Upload Target Settings dialog.

 Upload target Properties

  •  Upload target

    Alpha Anywhere Server or S3

    Specify where the media files (i.e. photos) should be uploaded when data from the List are synchronized. Uploading to S3 is very efficient because the upload takes place directly from the mobile device to S3, without involving the Alpha Anywhere server.

    When you upload to S3, the Alpha Anywhere server actually does play a very small role - before the upload to S3 starts, an Ajax callback is made to the Alpha Anywhere server to 'sign' the URL for the S3 upload using your S3 account credentials. By signing the URL on the Alpha Anywhere server, there is no need to expose your S3 credentials on the client side.
  •  Target filename

    Allows you to specify Javascript code that returns the filename of the uploaded media file when it is stored on S3 or the Alpha Anywhere server. It is very important that the target filename be unique for each uploaded media file or an upload from a user on one device could overwrite an upload from another user on a different device. The default code for this property is:

    return '<DeviceId>_' +e.object.listFieldName + '_' + A5.ts() + '_' +e.name
  • This indicates that the name of the uploaded file on S3 or the Alpha Anywhere server will be composed of the following elements:

    <DeviceId>

    a unique id generated by the mobile device. Unfortunately, is is possible that two or more mobile devices might generate same device id.

    e.object.listFieldName

    name of the field in the List where the uploaded filename will be stored

    e.object.listName

    name of the List that contains the target field

    A5.ts()

    a time stamp string.

  • You can specify that the uploaded files are stored in a folder on the target by including a forward slash in the name. For example, the following Javascript stores the uploaded files from each user in separate folders:

    return '<DeviceId> + '_' + e.object.ListFieldName + '/' + e.name;
  • In the case where you are uploading to the Alpha Anywhere server, this target filename returned by this JavaScript code can be overwritten by an Xbasic function that is called before the uploaded file is saved to disk. See information on the beforeUploadedFileSave below.

 Server Options Properties

 Amazon S3 Properties

  •  Connection String

    If you upload to S3, the name of your S3 storage connection string. Storage connection strings are defined by selecting the Tools menu when the Web Projects Control Panel has focus.

  •  Protected read

    Specify if the files that are uploaded to S3 are protected. Unprotected files can be accessed by anyone who knows the URI of the file. Protected files can only be accessed using a signed URL.

 Progress Display - Uploads Properties

  •  Display progress during media files upload

    Allows you to specify if you want to display progress while media files are uploaded when data in the List are synchronized. Since you can capture a large number of photos while you are disconnected, it can be very helpful to the user to display progress while the media files are uploaded. If you check this property then additional properties are shown that allow you to indicate properties of the progress indicator.

  •  Progress bar color

    Specify the color of the progress bar that is shown while the media files are being uploaded.

  •  Progress bar width

    Specify the width of the progress bar. Use CSS units.

  •  Placeholder for progress indicator

    Specify the name of the [Placeholder] control (see Other Controls section in the UX toolbox) where the progress indicator will be shown.

    You can enter 'Element:name_of_element' to target a specific element on the page rather than a Placeholder. For example:

  •  Javascript - Before Upload

    JavaScript to execute before files are uploaded to the target server. Since uploading the media files might take some time, this event is useful because it allows you to lock the screen and put up your own wait dialog. Your code can reference e.array - an array with information about the media files that will be uploaded.

  •  Javascript - After Upload

    JavaScript to execute after media files have all be uploaded to the target server.

  •  Javascript - onProgress

    You can define you own handler for displaying progress while media files are uploaded.

 Download Settings Properties

  •  Automatically download media files and other linked files when populating the List

    When data to populate the List is fetched from the server, if any fields in the data that are fetched reference linked photos (or other media files), specify if those files should be downloaded to the device.

    If this property is checked, then when you populate the List with data from the server, all of the media files referenced in the List are downloaded to the device and stored in files on the device so that your photos will be available even once you no longer have a connection. (It is recommended that you set this property on).

  •  Target folder on mobile device

    Specify the name of the folder on the mobile device where the media files that are downloaded from the server should be stored. The downloaded files are saved in a sub-folder (with the name of the List). For example, if you specify a target folder name of 'images' and this List is called 'List1', the files will be stored in a folder called 'images/List1'. You can use JavaScript function to specify the folder name. Specify the name as:

    javascript:yourfunctionname
  •  Filesystem

    Specify in which part of the device filesystem, the downloaded files should be stored. If you select <default>, the filesystem returned by the PhoneGap 'window.requestFileSystem(LocalFileSystem.PERSISTENT)' method is used.

    You can generate the name at runtime using a JavaScript function. Specify the name of the JavaScript function with 'javascript:' as the prefix. For example:

    javascript:getFileSystem
  •  Automatically delete un-referenced files

    After fetching new data from the server, if there are files that were previously saved in the mobile device's filesystem that are no longer referenced in the data fetched from the server, should these 'orphan' files be deleted (from the mobile device's filesystem)?

    If you do not check this property you can manage the orphan files yourself using the <listObj>._deleteOrphanMediaFiles() method.

 Progress Display - Downloads Properties

  •  Display progress during media files download

    Specify if progress should be shown while media file(s) are being downloaded from server(s) to the mobile device.

  •  Progress bar color

    Specify the color of the progress bar that is shown while the media files are being downloaded.

  •  Progress bar width

    Specify the width of the progress bar. Use CSS units.

  •  Placeholder for progress indicator

    Specify the name of the [Placeholder] control (see Other Controls section in the UX toolbox) where the progress indicator will be shown.

    You can enter 'Element:name_of_element' to target a specific element on the page rather than a Placeholder. For example:

    Element:DIV1
    Element name must be uppercase.
  •  Javascript - Before Download

    Since downloading media files (which can be quite large) from a server may take some time, you can use this event to put up a wait dialog to tell the user that files are being downloaded.

  •  Javascript - After Download

    If you put up a wait dialog before downloads were started, you can use this event to clear the wait dialog.

  •  Javascript - onProgress

    You can define you own handler for displaying progress while media files are downloaded.

 Errors Properties

  •  File upload error

    Specify the JavaScript to call if there is an error when uploading a media file.

See Also