File Upload, Webcam and Screenshot

Form Reform provides specialized form controls for file upload and image capture through integration with Snapshot.

The respective form input blocks for the Snapshot tools are:

  • Drag & Drop File Input - for general Drag & Drop image and other file upload within a form.
  • Screengrab File Input - to capture Screengrab images and upload the images within a form.
  • Webcam File Input - to capture Webcam images and upload the images within a form.

How it works

Snapshot buttonsThe file upload input blocks in Form Reform use the respective Snapshot tools. If you are not already familiar with them, go and have a play with the front end block demonstrations provided by the buttons.

(Not the screengrab of the buttons here, the live demo on the linked page)

Don't get confused at this point. The Snapshot tool blocks as illustrated above are the direct Snapshot tool buttons and are not the Form Reform input blocks. 

The blocks that integrate with Form Reform are as named ...File Input and appear in the Form Reform group of the block add dialogue as displayed below:

v9 Form input blocks

Not the Snapshot blocks

Quarantine

Each of these input blocks can be added to a Form Reform form as you would any other form input control. They look like form inputs and when used they show thumbnails for the files uploaded. When clicked, these form inputs open the respective snapshot control as an overlay. 

The visitor can then upload images and other files including webcam captures and screengrabs, within limitations configured in the block edit dialogue.

The important concept at this stage is that any file uploaded is placed in a quarantine folder without any renaming. Then, when the form is submitted, an Import Quarantine Files form handler copies the quarantined files to the configured destination folder and renames them according to the configured snapshot tool settings.

Debris left in quarantine is automatically cleared, or you can explicitly clear quarantine with the Clear Quarantine Files form handler. For example, perhaps in On Error processing you choose to forcibly clear quarantine.

All of this is specific to a visitor's session. 

In the screengrab below:

  1. A Drag & Drop File Input block, as it first appears.
  2. A Drag & Drop File Input block with two files uploaded to quarantine
  3. A Form Reform Submit block, where the handler pipeline uses Import Quarantine Files to copy the files from quarantine into their destination folders.

Why Quarantine?

  1. Quarantine provides an extra level of security for uploaded files.
  2. Quarantine facilitates multi-step forms, where a file is uploaded in one step, but not imported from quarantine until a subsequent step.
  3. Quarantine allows a visitor some scope to change their mind. They can click the trash can and upload a replacement before submitting a form.
  4. Quarantine takes the overhead of uploading files out of the overhead of processing the form handler pipeline. Visitors get a more responsive experience.
  5. Quarantine provides a state where a file is uploaded and potentially usable before it is copied into its final location. A quarantined file could be sent in an email or used for other form processing and never actually imported.
  6. Quarantine allows the full functionality of Snapshot to be used to edit images, assign an owner, assign files to folders and filesets.

Block Configuration

Configuration of these blocks follows the usual Form Reform input tabs

  • Form Control - name the form input, add a label and placeholder etc. This is the same as any other Form Reform block.
  • Validation - add a required note, set minimum and maximum limits on the number of files required, set a custom fail message. This is the same as any other Form Reform block.
  • Snapshot - this tab is the big one. It shows the full configuration options for the respective snapshot tool. Any quantity of files limit set here affects the front end dialogues. This is separate to the limits set for form validation in the preceding tab. In general, they should be configured to agree!
  • Initial Value - we don't repopulate file inputs from previously submitted forms, so this tab has a stripped down set of options compared to other Form Reform blocks.
  • Behaviour - visibility and rendering in form states. This is the same as any other Form Reform block.

Security Considerations

When adding a file upload to a form you need to consider security and permissions, especially if the form is open to unregistered visitors.

The block configuration dialogues allow image sizes to be constrained, declared file types to be constrained, number of uploads to be limited and various spam checks to be invoked both at the time of the upload (via Snapshot) and through form validation in the handler pipeline.

In Concrete CMS every file needs an owner. A file owner cannot be a guest/visitor. We manage this by assigning an owner to uploaded files in Guests upload as this user. This requires a bit of general configuration. To enable guests/visitors to upload files with their forms, you need to:

  1. Create one or more user(s) to own the uploaded files.
  2. Assign file manager permissions to the user(s) so they can Add Files to the final destination folder and so they can Add Files and Delete Files from the quarantine folder.

Remember, this user is only used internally. Your guests/visors do not have the permissions of this user. They remain guests. But the Snapshot tools use the special user(s) to allow files to be added and removed from quarantine and added to their final destination folder.

In our screengrab below, we have created a user called PublicUpload and assigned permission to add and remove files from the quarantine folder. Similar permission and user(s) will be needed for any site allowing guest/visitor users to upload files with Form Reform.

Also in our screenshot is the upload folder where we are placing the files once imported from quarantine, which we have given permission for the PublicUpload user to only add files.

This approach can grow to become more sophisticated where you need to add further structure to the imported files, for example:

  • Consider different destination folders for each form on your site.
  • Consider different 'upload as' users for each form on your site.
  • Consider creating subfolders named after the visitor first name / last name and zip code - taken from form fields.

In general, when visitors can upload files with your Form Reform forms, the block configuration should be the absolute minimum needed to facilitate the upload. Tie everything down so you don't get unwanted surprises.

Using uploaded files

In the form handler pipeline, once a file has been imported with Import Quarantine Files we can use that file through {{place_holders}} in subsequent stages of the form pipeline. These enable use of URLs to the file and the file ID. Please refer to the {{place_holders}} documentation page for details.

An option of the Import Quarantine Files handler is to choose which file property is actually mapped into the input name, and hence saved with any record of the form submission. This facilitates use of different file properties at different steps of the pipeline. For example, you would usually want to save just the file ID with the form record, but use a secure URL when sending an email to the person submitting the form or to any integrated third party destination.

You don't even need to Import Quarantine Files. Files can be used directly from quarantine without completing the import, as long as the use is completed before the quarantine files expire or are explicitly cleared by Clear Quarantine Files. For example, a file uploaded and quarantined could be embedded into an email and then cleared so no copy is retained on the web server.

If you subsequently need to display uploaded files, consider using Omni Gallery to display files based on folders or filesets.

Additional Pages

Reform the way you add new input controls

If you need a specialized template or a custom input element, you can design new templates  or new block types for form elements as you would any block type.

Blocks are easy for third party addition or extension. Block templates and are the first thing any Concrete CMS developer learns to code. They are one of the easiest things to code. The underlying mechanisms are well established and reliable.

Reform what you can do with form data

Form handlers are built about the same extensible plugin system as many of my other addons (Universal Content Puller, Omni Gallery, Extreme Clean ...).

The whole system is aimed at easy extension within Form Reform, by third party addons, by agencies and by site building developers.

Handlers can be easily added to do whatever you want with the form data.

Reform where you can save form data

Saving form data with Form Reform is simply a handler in the processing pipeline. You can save to multiple locations or just one location.

If you need to save data elsewhere, such as to a dedicated table, a table provided through another addon, to another database, send it to an API, forward it to another server, or anywhere you can imagine, you can adapt or develop a form handler to do so.

The complexity of the code depends on where you are saving or sending the data, but wrapping that into a form handler plugin for Form Reform is straight forward.

The Form Reform handler plugin system is designed for easy extension.

Form Reform

Reform the way forms are built. Build a form out of blocks. Take control of how form submissions are processed and how the submitted data is stored. Easy to extend. Easy to reconfigure. Tangible data. Easy to add your own integrations.

Form Reform Display

List and display form submissions from Form Reform.

Form Reform UTM

Not just Form Reform and not just UTM! Capture and hold incoming UTM (or other) tags and make the tag values available to Form Reform and/or Conditional Redirect as {{place_holders}}. You don't need Form Reform to use this.

Form Reform Dynamics

Form handlers for querying Microsoft Dynamics, forwarding and updating form data to Microsoft Dynamics.

Snapshot

A suite of advanced image capture and upload tools. Enhanced drag and drop file uploading. Make screengrabs from within Concrete CMS. Capture images directly from device webcams. Edit images before uploading.

Form Reform Attributes, Express and Users

Save submitted forms to Express objects and user attributes. Add and remove users from groups.

Form Reform Image Picker

Form Reform Image Picker provides an image picking input block for Form Reform. The Image Picker Input is preconfigured to connect to most Omni Gallery gallery and slider display widgets, the core gallery block, and thumbnail showing templates for the core page list block. Advanced settings allow the Image Picker Input to be configured to pick images from other galleries and sliders.

Form Reform Data Picker

Form Reform Data Picker provides data picking input blocks for Form Reform. The Table Picker Input is preconfigured to connect to Universal Content Puller table display widgets. Advanced settings allow the Table Picker Input to be configured to pick data from other HTML tables.

Form Reform Macros

Extends Form Reform with form handler macros. Provides a new dashboard page at System & Settings > Form Reform > Form Reform Macros to manage macros, and form handlers to run macros.

Form Reform Developer

A growing suite of resources to assist those developing blocks, handlers and more complex forms for Form Reform.

Learn with a simple form

While you may have plans to implement some much more complex forms using Form Reform, we strongly recommend you start with a simple form such as our contact form example in order to review the basic principles of using Form Reform before you move onto anything bigger.

  1. Start by submitting the form at Getting Started - Your First Form a few times, even making some deliberate mistakes.
  2. Watch our Getting Started with Form Reform video to see how the form is built.
  3. Read through the rest of Getting Started - Your First Form for more details of how this form is built.
  4. Create a test page on your site to build your own version of Getting Started - Your First Form and experiment.
  5. Develop your test page with some of the concepts introduced by our further examples and experiment with some of the other form inputs.