When to Use a Media Field
A media field is used to display or upload an image or file in the ADM.
When you are not using the ADM (ex: custom code or OData service), media fields can be used to transfer any file or base64 string through the framework.
Generic Flow
When a file is selected, the framework will handle this file in one of two ways:
- Base64 processing: The file is converted to a base64 string. This string is sent as the media field value and will be stored in the database.
- External processing: For external processing a method has to be selected. When a file is selected and saved, this method will process the file. The method will return a link to the location of the stored file, and this link will be stored in the database.
A file will only be uploaded when the form is saved. This means that a file will not be uploaded if the form is closed without saving. The exact process is as follows:
- A file is selected
- The file is loaded in the form
- When clicking the save button, the file is uploaded first
- After the file has been uploaded, saving the form will continue automatically.
Base64 Processing
Base64 encoding allows the framework to store any supported file as a string in the database. Base64 strings can be quite long so you have to store this in an appropriate data type. When you want to use SQL for reading and saving base64 strings, we advise to use VARCHAR(MAX).
Take a look at the following image:
If we encode this image to a base64 format, this would be the result:
data:image/gif;base64,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
When the media field comes to our framework, it will be converted to a .NET string. You have to do a lot for it to break, but if you do, just contact support!
Use Online Image
When you want to display an image from a website in a multi record or single record view, just specify the complete url to the image.
Accepted File Types
A media field accepts the following file types:
| File Type | Extensions |
|---|---|
| Word | .doc, .docx, .docm, .dotx, .docb |
| Excel | .xlsx, .xlsm, .xltx, .xltm |
| Images | .gif, .jpeg, .jpg, .png, .tif, .jif, .jfif |
| Video | .avi, .flv, .wmv, .mov, .mp4, .mpeg, .mpg, .3g2 |
| Audio | .aif, .iff, .mp3, .mpa, .wav, .wma |
| Archives | .7z, .rar, .zip, .zipx, .tar.bz2, .tar.gz |
Configure a Media Control
In this section you will learn how to configure a media control. First you will get information about the object field settings. The second part describes the view field settings.
Object Field
If you create a new media object field or method field, it is possible to change some type specific properties. Of course there are also a lot of generic properties like unique, external name or default value. Refer to common properties for more information about this topic.
- Click on the object.
- Create a new field.
- Change the type from Text to Media.
Maximum Length
The maximum length could be set, but since base64 strings could be quite long it is recommended not to change the default value. However, if your external system has a character limit, just change the value of this property.
Media Target Source
The Media Target Source field is used to select between base64 processing and external processing. When external processing is selected the method that processes the file has to be selected. In the image below the method Ensure file in the object SharePoint.BuildingBlocks.Items is used. This method saves a file to a SharePoint library, or updates the file if it already exists.
The field File Url Ref determines which method output field will contain the url that points to the location of the file.
A media field creates the following context fields that can be used in the connection settings of the selected method:
| Context field | Description |
|---|---|
| MediaField.File.Name | The name of a file when it is uploaded. |
| MediaField.File.LocalPath | Can only be used when the Generic REST Service and the framework run on the same server. Contains the local path to the file. |
| MediaField.File.Contents | Used if the Generic REST Service and the framework run on different servers. Contains the base64 representation of the file. |
View Field
In create and update views, a media control is displayed as an HTML file control with the possibility to add a file.
Multi Record View
| Property | Description |
|---|---|
| Width | Specify the width of image in pixels. If set to 0 it will be the original width size. |
| Height | Specify the height of the image in pixels. If set to 0 it will be the original height size. |
| Downloadable | This property is deprecated. Specifies if a word, excel, pdf or archive file can be downloaded by a user. Browsers usually support downloading images, videos and sound files by right clicking the file. |
| Show Full Picture | If checked the picture will be shown in its original dimensions. If not checked it will be showed as a thumbnail. |
| Show Multiple Files | If checked multiple files will be shown. If not checked only one file will be shown. |
Single Record View
| Property | Description |
|---|---|
| Width | Specify the width of image in pixels. If set to 0 it will be the original width size. |
| Height | Specify the height of the image in pixels. If set to 0 it will be the original height size. |
| Downloadable | This property is deprecated. Specifies if a word, excel, pdf or archive file can be downloaded by a user. Browsers usually support downloading images, videos and sound files by right clicking the file. |
| Events | JavaScript events used to interact with the media control. |
| Show Multiple Files | If checked multiple files will be shown. If not checked only one file will be shown. |
Create and Update View
| Property | Description |
|---|---|
| Read Only | If checked the control can not be changed by the user. |
| Use Data Source | Refer to Data Sources. |
| Width | Specify the width of the control. |
| Height | Specify the height of the control. |
| Allow selection of multiple files | When checked it is possible to select multiple files, otherwise only one file can be selected. |
| Media Target Source | Can be changed to External or Base64. External will let you pick a method which will handle the file processing. Base64 will convert the file to a base64 format. |
| Events | JavaScript events used to interact with the media control. |