This article will cover implementing the website widget into your workflow and requirements. We will go from the simplest to most complex options. The widget allows a much more trustworthy and streamlined experience for your clients or customers to send you files.
The widget becomes particularly useful when your site already has some information about your customers or the upload details you expect (your order or job number for example).
We will implement a hypothetical film competition submission form but the concept will apply to any needs.
Simple embed
The simplest option is to simply use the widget on its own to capture information you need along with the files uploaded. The widget will capture a name, email (required), a subject line (required) and long form description. In this case for a film competition you can use our Widget Editor to make the labels more appropriate. The result looks like this:
See the Pen aMgayx by Stuart (@digitalpigeon) on CodePen.
Pros
|
Cons
|
Simple embed - Pre-populating fields
All the fields can be pre-populated when setting up the widget. When a field is pre-populated it is hidden from the user. This can be useful when you already have some information like your visitor's name and email address. The following data attributes can be added to the simple embed snippet:
data-name="value"
- The uploader's name field (max = 200)
data-email="value"
- The uploader's email field (max = 400)
data-summary="value"
- The summary/subject field (min = 2, max = 200)
data-message="value"
- The message field (max = 10000)
The example below shows pre-populating the user's name and email:
See the Pen xBoyJq by Stuart (@digitalpigeon) on CodePen.
Pros
|
Cons
|
Advanced API - Linking additional form information
With the advanced widget snippet and some Javascript you can implement a multistep process that can capture and validate more information from your own form.
The example below will show a 2 step process that uses Javascript to pre-populate the widget fields from your own form fields (this is for the sake of a self contained working demo). You could also, for example, have a 2 page setup where your form values are captured with a POST to your server and then you pre-populate those value into the widget on the next page, like the previous example.
First we setup a form that captures all the desired information. It will have all the expected validation to ensure the exact information you want is captured:
See the Pen aMgQzy by Stuart (@digitalpigeon) on CodePen.
Now that we have a form we need to do something with the information so we'll add some Javascript to take the form information and show the widget. We need to use the advanced widget snippet from the Widget Editor to use the Javascript API.
See the Pen qvzLEv by Stuart (@digitalpigeon) on CodePen.
Pros
|
Cons
|
Advanced API - Linking files from your own system
Expanding on the implementation the above we can also use the API's 'oncomplete' function to take some details about the upload and submit them to your own server for linking your information to an upload in Digital Pigeon:
See the Pen oOgKBp by Stuart (@digitalpigeon) on CodePen.
Pros
|
Cons
|
Javascript upload complete event
The function is called with two parameters, the first contains useful information about the upload:{
"id": "007aa9a0-71a9-11e7-b0c0-6a16537fbb7e", //Our upload id, useful to link from your own system
"initiator": {
"name": "Joe Submitter", //The uploader's name if entered, null otherwise
"address": "joe@indiefilmmaker.co", //The uploader's email address
}
"summary": "The Pigeon Diaries", //The subject field entered
"body": "Director: Jane Director\nGenre: Documentary", //The message field entered
...
"estimatedFileCount": 2, //The number of files uploaded
"estimatedSize": 11034396, //The total size of the upload in bytes
...
}
The second parameter contains further details about the files uploaded:
{
"fileTree": {
"filesLength": 2, //Number of files uploaded
"size": 11034396, //The total size of all files in bytes
"files": [ //Files in the root folder
0: {
"id": "007aa9a0-71a9-11e7-b0c0-6a16537fbb7e", //the file id, useful to link from your own system
"name": "The-Pigeon-Diaries.mp4", //The file name
"size": 617514, //The file's size in bytes
"contentType": "video/mp4", //The file's MIME type
"modified": 1512452882795, //The file's last modified date in milliseconds since Epoch
...
},
1: { ... }
],
"folders": [ //Subfolders in the root folder
0: {
"filesLength": 2, //Number of files uploaded
"size": 43961103, //The total size of all files in bytes
"files": [ //Files in this folder
0: {
"id": "ba7aa9a0-71a9-11e7-b0c0-6a16537f-78b4", //the file id, useful to link from your own system
"name": "Subtitles.srt", //The file name
"size": 751461, //The file's size in bytes
"contentType": "text/plain", //The file's MIME type
"modified": 1512482795528, //The file's last modified date in milliseconds since Epoch
...
},
1: { ... }
],
"folders": [ ... ] //Subfolders in this folder
...
},
1: { ... }
],
...
}
}
Error handling
An error occurring after the upload has completed but which would prevent the oncomplete function from executing correctly will now show an alert with the text explaining an issue has occurred. The text includes an error code and the error message derived from the source error. Error code '0' denotes an issue in the oncomplete function provided by you the developer, and error code '1' or above denotes an issue within Digital Pigeon.
Comments
0 comments
Please sign in to leave a comment.