Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email properties
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email Settings dialog
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • Appearance
  • Basic usage
  • Upload as a URL
  • Upload as inline Base64-encoded binary
  • Validating a file upload
  • The accept attributes
  • Controlling upload between the client and the server
  • Rationale
  • When synchronization takes place
  • Events
  • Empty files
  1. XForms
  2. Controls

Upload

PreviousButtonNextDialog

Last updated 1 year ago

Appearance

Example of the upload control before selection:

Example of the upload control sending a file in the background, with progress bar and "Cancel" button:

Basic usage

XForms allows you to upload files with the XForms upload control:

<xf:upload ref="files/file[1]">
  <xf:filename ref="@filename"/>
  <xf:mediatype ref="@mediatype"/>
  <xxf:size ref="@size"/>
</xf:upload>

The related section of the XForms model can look like this:

<xf:instance id="my-instance">
  <files>
    <file filename="" mediatype="" size=""/>
  </files>
</xf:instance>
<xf:bind nodeset="file" type="xs:anyURI"/>

The file element is the element storing the result of the file upload. The result can be stored in two ways:

  • As a URL: By specifying the type xs:anyURI.

The optional xf:filename, xf:mediatype, and xxf:size (the latter is an Orbeon Forms extension) allow storing metadata about an uploaded file:

  • xf:filename: stores the file name sent by the user agent

  • xf:mediatype: store the media type sent by the user agent

  • xxf:size: stores the actual size in bytes of the uploaded data

SECURITY NOTE: The file name and the media type are provided by the user agent (typically a web browser). Not only are they not guaranteed to be correct, but they must not be trusted.

Upload as a URL

The result of a file upload when using xs:anyURI contains metadata parameters and typically looks like this:

file:/home/tomcat/apache-tomcat-6.0.29/temp/xforms_upload_2351863081926002422.tmp?
  filename=orbeon-logo-trimmed-42.png&
  mediatype=image%2Fpng&
  size=8437&
  signature=1726db1bea2b3be2f635f60e4f99dc72864548c5

NOTE: The metadata includes a signature placed by the <xf:upload> control. This signature allows <xf:output> to verify that signature and disallow display or download of file: URLs not constructed by <xf:upload>. This enhances the security of uploads.

The URL stored as the value of the upload is temporary and only valid until either:

  • the session expires,

  • the Java VM quits,

  • or a new file upload replaces the existing URI in the XForms instance.

NOTE: Using the xs:anyURI type allows Orbeon Forms to make sure the uploaded file does not have to reside entirely in memory. This is the preferred method for uploading large files.

Upload as inline Base64-encoded binary

The result of a file upload looks as follows when using xs:base64Binary:

<file filename="photo.jpg" mediatype="image/jpeg" size="2345">
/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAQDAwQDAwQEBAQFBQQFBwsHBwYGBw4KCggLEA4RERAO
  EA8SFBoWEhMYEw8QFh8XGBsbHR0dERYgIh8cIhocHRz/2wBDAQUFBQcGBw0HBw0cEhASHBwcHBwc
  ...
</file>

In this case, the uploaded file is encoded an directly embedded into the XML instance. This is a good method to handle small files only, because the entire file is converted and stored in memory.

Validating a file upload

You can validate a file based on its name, mediatype, and size. Assume file metadata is stored into:

<file filename="" mediatype="" size="">

The following bind checks that if an uploaded file is present, the file size is no greater than 500,000 bytes and the mediatype is a JPEG image:

<xf:bind
    ref="file"
    constraint="
        . = '' or (
            @size le 500000 and
            @mediatype = ('image/jpeg', 'image/pjpeg')
        )"
/>

Note that Internet Explorer can send the image/pjpeg mediatype.

SECURITY NOTE: The file name and the media type are provided by the user agent (typically a web browser). Not only are they not guaranteed to be correct, but they must not be trusted.

The accept attributes

[SINCE Orbeon Forms 4.3]

<xf:upload ref="file" accept="image/*">

The accept attribute is an XForms 2.0 feature. For backward compatibility, the mediatype attribute is also supported.

SECURITY NOTE: This is not a guarantee that the file sent will have that mediatype, because some browsers do not support that feature, and even when it does, the browser must not be trusted.

Controlling upload between the client and the server

Rationale

With regular controls such as input, textarea, etc., upon a change of value by the user a small Ajax request is sent by the browser to the server to synchronize the data into the XForms data model.

With uploaded files, this is often not possible, because files can be very large and so take a significant amount of time to be sent to the server, up to minutes or even hours depending on file size and connection speed.

So there is a distinction to make between:

  • selection: the user selecting a file with the upload control's file selector

  • synchronization: the file data being fully sent to the server and available for processing by XForms

Orbeon Forms is able in most cases to synchronize files in the background: the user can keep working with the page while files are being uploaded.

When synchronization takes place

Any files are selected but not synchronized upon a submission with replace="all", those files are synchronized then.

In other cases, the process works as follows:

  • as soon as the user selects a file with an upload control, the file is automatically scheduled for synchronization with the server

  • background synchronization starts as soon as possible:

    • immediately if no other upload is pending

    • when other pending uploads have completed

  • pending uploads can be canceled by the user with a Cancel button

  • while background synchronization is taking place, the user can keep interacting and updating the page

  • no boilerplate code or otherwise is needed to start synchronization!

By default, <xf:submission> checks for uploads and interrupts the submission if:

  • the effective serialization is not none

  • there is a pending upload

    • for an upload control

      • which is relevant

      • and bound to the instance being submitted

If a submission detects that there is a pending upload, the submission terminates with:

  • dispatching the xforms-submit-error event

  • with an event('error-type') set to xxforms-pending-uploads

You can this way detect pending uploads on submission with code like:

<xf:action
    ev:event="xforms-submit-error"
    if="event('error-type') = 'xxforms-pending-uploads'">
    ...
</xf:action>

This can be overridden with the xxf:uploads AVT attribute:

<xf:submission xxf:uploads="false" ...>

In addition, the xxf:pending-uploads() function returns the number of pending uploads. Example:

<xf:bind
    ref="save-button"
    readonly="xxf:pending-uploads() gt 0">

Events

NOTE: xforms-select is no longer dispatched when a file is selected.

Empty files

By default, empty uploaded files are rejected. This behavior can be changed using the following property:

<property
    as="xs:boolean"
    name="oxf.fr.upload.reject-empty-files"
    value="false"/>

As Base64-encoded text: By specifying the type xs:base64Binary. Base64 is a mechanism to encode any binary data using a 65-character subset of US-ASCII. Using this mechanism allows embedding binary data into XML documents, at the typical cost of taking 50% more space than the original binary data. For more information, please refer to the .

The URL is only accessible from the server side, and will not be accessible from a client such as a web browser. It is not guaranteed to be a file: URL, only that it can be read with Orbeon Forms's or <xf:output>.

The contents of the file can be retrieved using the . The result will be an XML document containing a single root element containing the uploaded file in Base64-encoded text.

The accept attribute is simply passed to the web browser. As of 2013, most web browsers do support filtering files based on that attribute, as per the . For example:

See .

RFC
URL generator
URL Generator
HTML specification
[SINCE Orbeon Forms 2023.1]
Upload control events