Version: Upcoming 🦄

Media Features

HybridForms provides several Media Features that can be integrated into your forms and workflows. To include any feature into your App, you must enable the App function flag in the Admin UI of your Form Template. Without this flag, the features described below will not be available. If you would like to use the features locally, you can mimic the configurations using the index.json file. See Index.json Example for details.

Admin UI Feature flags

Media Settings

Use a template variable to configure the global media settings for HybridForms.

<var
    data-hf-name="MediaSettings"
    data-hf-compression='{
        "type": "compress",
        "options": {
            "format": "jpg",
            "jpgQuality": 0.1,
            "maxDimension": 1400
        }
    }'
    data-hf-condition='{
        "cond": [{
            "type": "stage",
            "id": "S1",
            "val": true
        }],
        "else": "invisible"
    }'
    data-hf-condition-picture='{
        "cond": [{
            "type": "stage",
            "id": "S1",
            "val": true
        }],
        "else": "readonly",
        "addNewMedia": true
    }'
    data-hf-characterWhiteListRegExp="[a-zA-Z0-9äöüßÄÖÜ\-.,;:_!@#%&()?'`+=]"
    data-hf-characterWhiteList="abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789äöüßÄÖÜ\-.,;:_!@#%&()?'`+="
    data-hf-invalidCharacterErrorText="{{@InvalidCharsErrorText}}"
    data-hf-saveImageToPhotoAlbum="true"
    data-hf-maxFilenameLength="10"
    data-hf-registerMaps="googleMapsApiKey,hfMap-MapLibreBaseMap,Basemap-OpenLayers"
>
</var>

The typescript representation of the condition object is defined below:

interface IMediaSettings {
    pictureCompression?: IPictureCompression;
    saveImageToPhotoAlbum?: boolean;
    maxFilenameLength?: number;
    characterWhitelistRegExp?: string;
    invalidCharacterErrorText?: string;
    allowedDocumentTypes?: string[];
    video?: IVideoSettings;
}

Feature Conditions

This setting controls the visibility and validation of our media libraries by adding conditions. The same rules apply as for form control conditions. Only the property addNewMedia is specific to the media library conditions. If the property addNewMedia is set to true the user can add new media files to the library even if the condition is not met.

If only the data-property data-hf-condition is provided, the condition applies to all media libraries.

For library-specific conditions, use the corresponding data-property:

data-hf-condition-audio
data-hf-condition-document
data-hf-condition-maps
data-hf-condition-model
data-hf-condition-picture
data-hf-condition-sketches
data-hf-condition-video

If both general and specific conditions are provided, the specific conditions take precedence.

Example of conditions on media features
<var
    data-hf-name="MediaSettings"
    data-hf-condition='{
        "cond": [{
            "type": "stage",
            "id": "ST1",
            "val": true
        }],
        "else": "readonly"
     }'
    data-hf-condition-sketches='{
        "cond": [{
            "type": "stage",
            "id": "ST1",
            "val": true
        }],
        "else": "invisible"
    }'
    data-hf-condition-maps='{
        "cond": [{
            "type": "stage",
            "id": "ST1",
            "val": true
        }],
        "else": "readonly",
        "addNewMedia": true
    }'
></var>

Max Filename Length

Use the option maxFilenameLength to set the maximum length of the filename of an uploaded file. If the filename is longer than the given value, the filename gets shortened. Default value is 80.

<var data-hf-name="MediaSettings" data-hf-maxFilenameLength="20"> </var>

Character Whitelist

Same options as above within the FormSettings-variable. Use this option to set a whitelist of allowed characters for all media files the user is uploading. You can use the regular expression or the string version of the whitelist. If both are provided the regular expression is used. Optionally you can provide your own error text for the invalid character error message. If you want to give the user a hint what characters are not accepted in the current input, you can use the placeholder {0} in your error text (E.g: "The following characters are invalid: 0"). You can also provide translation keys. If no error text is provided, a default error message is used.

Note

The character whitelisting setting of the FormSettings variable is also applied to file names of the uploaded media files. If you want to allow special characters in the uploaded file names, you have to provide them in the media settings variable.

Camera

The Camera Feature supports:

Capturing, uploading and scanning photos directly within the App (Scanning is currently supported only on iOS)
Reading metadata (e.g., EXIF-data, geolocation)
Editing, annotation and sketch functionality
Adding remark

Picture Compression

Use this option to set picture compression for all uploaded images inside this form.

Info

The definition affects all image uploads (inside features and Form Controls).

<var
    data-hf-name="MediaSettings"
    data-hf-compression='{
        "type": "compress",
        "options": {
            "format": "jpg",
            "jpgQuality": 0.1,
            "maxDimension": 1400
        }
    }'
>
</var>

The value of the data-hf-compression must be a JSON string.
The typescript representation of the condition object is defined below:

interface IPictureCompression {
    type: 'original' | 'compress';
    options: IPictureCompressionOptions;
}

interface IPictureCompressionOptions {
    format: 'jpg' | 'png' | 'original';
    jpgQuality: number;
    maxDimension: number;
}

key	value	How to use	Description
type*	String	`"type": "compress"`	Enable or disable picture compression by setting type to `compress` or `original`.
options	Object	`"options": { ... }`	Define the compression depth.

* These options are required.

Compression Options

key	value	How to use	Description
format	String	`"format": "jpg"`	Set the image format of the output file. Conversions to `png` or `jpg` format are supported, default is `original` (the original image format remains the same).
jpgQuality	Number	`"jpgQuality": 0.1`	Set the jpg image quality to compress the output file. Values between `0.1` and `1` are supported. Default value is `0.9`. Note: All uploaded jpgs get compressed. If the format option is set to `jpg`, all pictures get compressed with the given value.
maxDimension	Number	`"maxDimension": 1400`	Set the maximum dimension of the output file. If this property is not provided, the dimensions of the image are not altered.
maxSizeMB	Number	`"maxSizeMB": 3`	Set the maximum file size of the output file. Default is the maximum size of the upload limit of your server. Note: It is recommended to use the `maxDimension` option to reduce file size instead of this property.

If no options are provided and the type is set to "compress", the image file gets compressed with the default values.

Warning

On iOS devices, images are always compressed to a maximum of 8192 pixels on the longest side because of memory limitations.

Save Image to Photo Album

Use this option to save all captured images through HybridForms to the photo album of a mobile device.

Info

The definition does not affect images captured within the web App.

<var data-hf-name="MediaSettings" data-hf-saveImageToPhotoAlbum="true"> </var>

Video

The Video Feature supports:

Recording and uploading videos directly within the App on mobile devices
Reading metadata (e.g., duration, geolocation)
Adding remark

Video Compression

Use this option to set video compression for all uploaded and/or recorded videos inside this form.

Info

The definition affects all video uploads (inside features and Form Controls).

<var
    data-hf-name="MediaSettings"
    data-hf-video='{
                "recordingQuality": 1,
                "maxDurationSec": 20,
                "maxSizeMB": 200
            }'>
</var>

The value of the data-hf-video must be a JSON string.
The typescript representation of the condition object is defined below:

interface IVideoSettings {
    recordingQuality?: number;
    maxDurationSec?: number;
    allowedFormats?: string[];
    maxSizeMB?: number;
    maxWidth?: number;
    maxHeight?: number;
    disableRecording?: boolean;
}

Compression Options

key	value	How to use	Description
recordingQuality	Number	`"recordingQuality": 0.1`	Set the video quality to compress the output file. Values between `0.1` and `1` are supported. Default value is `1`.
maxDurationSec	Number	`"maxDurationSec": 60`	Set the maximum duration for uploaded or recorded videos in seconds. The default is 3 minutes.
allowedFormats	String	`"allowedFormats": "mp4"`	Set the allowed file types for videos that can be uploaded. Supported formats are `mp4`, `mov`, `avi` and `mkv`.
maxSizeMB	Number	`"maxSizeMB": 300`	Set the maximum file size for uploaded or recorded videos. Default is the maximum size of the upload limit of your server.
maxWidth	Number	`"maxWidth": 1920`	Set the maximum width for uploaded videos.
maxHeight	Number	`"maxHeight": 1080`	Set the maximum height for uploaded videos.
disableRecording	Boolean	`true`	Deactivate the recording button within the form.

Warning

On iOS devices, uploaded videos are always compressed.

Audio

The Audio Feature supports:

Recording and uploading audio directly within the App
Reading metadata
Transcription and remark

Map

The Map Feature supports:

Adding custom maps
Reading metadata (e.g., geolocation)
Multiple features (e.g., placing markers, layer visibility and more)
Creating snapshots with sketch functionality
Adding remark

Various libraries can be used to create interactive maps within your Forms. You can configure settings and properties via the Admin UI, while further customizations can be achieved through Custom Code.

Register Maps

Use this option to register maps that should be available in your Form Template. Each of the listed maps has to be registered in the Admin UI. You can find more information on this topic in the section: Integration of maps.

hf-registeredMaps
<var data-hf-name="MediaSettings" 
    data-hf-registerMaps="googleMapsApiKey,hfMap-MapLibreBaseMap,Basemap-OpenLayers">
</var>

Sketch

The Sketch Feature supports:

An interactive canvas for drawing, placing shapes, and inserting text
Custom backgrounds
Reading metadata
Adding remark

In addition to the default backgrounds in the HybridForms App (such as 'blank' and 'grid'), you can use predefined backgrounds by specifying image files in your Form Template. You can also enable the 'SketchTemplates' feature flag in the Admin UI, which allows you to use images from the Picture, Model and Maps feature as sketch templates.

<!--  background images for sketches -->
<var
    data-hf-name="SketchTemplates"
    data-hf-templates='[
        {"image": "sketchBackground01.jpg", "label": "Testtemplate"},
        {"image": "schaltplan.png", "label": "Schaltplan", "thumbnailImage": "schaltplan_tn.png"},
        {"image": "sketchBackground02.jpg", "label": "Platine"},
        {"image": "sketchBackground03.jpg", "label": "Nebula"}
    ]'
    data-hf-show-default-templates="true"
>
</var>

Light Sketch templates Dark Sketch templates
Sketch templates

The specific backgrounds are defined by listing the image name and the display label inside a JSON array.

Note

Provide the images the same way as other images referenced inside your Form Template.

The JSON array consists of the key/value pairs "image", "label", "thumbnailImage", where image and label are required data and the thumbnailImage is optional. If no "thumbnailImage" property is provided, the original image is presented on the sketch gallery. If you provide high resolution sketch templates always provide a thumbnail image, because the size of the image and the number of sketch templates could lead to performance issues.

The variable option data-hf-show-default-templates can be configured as true, thereby enabling the default sketch backgrounds within the HybridForms App, or it can be set as false to disable them.

Customized Color Palette

Use this variable to predefine the color palette for the drawing feature.

Info

The definition affects all drawing possibilities (inside the features and Form Controls).

Light Custom Color Palette Dark Customized Color Palette
Custom Color Palette

Info

The JSON array entries contain the key/value pairs "color", "text" and "default" where key/value pair "color" and "text" are required.

The variables option data-hf-extend-default-colors has to be a boolean value:

true extends the HybridForms App default color palette. If new default color is set in FormDefintion the HybridForms App default color will be overwritten.
false overwrites the HybridForms App default color palette.
If not set the HybridForms App default color palette will be overwritten.

<var
    data-hf-name="DrawingColorPalette"
    data-hf-colors='[
        { "color": "#000000", "text": "black" },
        { "color": "#0000ff", "text": "blue" },
        { "color": "#ff0000", "text": "red", "default": true },
        { "color": "#00b900", "text": "green" },
        { "color": "#ffa500", "text": "orange" }
    ]'
    data-hf-extend-default-colors="false"
>
</var>

key	value	How to use	Description
color*	String	`"color": "#32a952"`	Provide a value for your color palette listing. The value has to be a legal Hexadecimal CSS color value.
text*	String	`"text": "green"`	Provide a name for your color palette listing.
default	Boolean	`"default": true`	Specify the default color of the palette. If no default value is specified, the first value of the list will be set as default.

* These options are required.

Model

The Model Feature supports:

Uploading and displaying interactive 3D models
Rotating, zooming, inspecting, and measuring the model
Editing options (e.g., cropping)
Reading metadata
Adding remark
Creating snapshots with sketch functionality

Document

The Document Feature supports:

Uploading and displaying common document formats (PDF, DOCX, XLSX, etc.)
Page navigation and zoom
Adding remark
Drawing, highlighting and text annotations directly on PDF documents
- Saving annotated versions while keeping the original intact

Allowed Document File Types

Use this option to set the allowed file types for documents that can be uploaded in the document feature. The value must be a comma-separated list of file extensions (without the dot).

hf-registeredMaps
<var data-hf-name="MediaSettings" 
    data-hf-allowedDocumentTypes="pdf,docx">
</var>

Media Settings​

Feature Conditions​

Max Filename Length​

Character Whitelist​

Camera​

Picture Compression​

Compression Options

Save Image to Photo Album​

Video​

Video Compression​

Compression Options

Audio​

Map​

Register Maps​

Sketch​

Customized Color Palette​

Model​

Document​

Allowed Document File Types​

Media Settings

Feature Conditions

Max Filename Length

Character Whitelist

Camera

Picture Compression

Save Image to Photo Album

Video

Video Compression

Audio

Map

Register Maps

Sketch

Customized Color Palette

Model

Document

Allowed Document File Types