I implemented the 'Dropzone' widget found on the public Mendix App Store into one of my applications this week and found the documentation rather light. Since it took me a few iterations to figure out how best to implement it, I thought I’d share what I learned and hopefully save some of you out there looking to implement it some effort.
The Dropzone widget can be used when you want a user to upload one or many files at once into your application. Unlike the standard File Manager widget built into every application, this widget creates a nice interface for the user to either click and select, or drag the pre-selected documents from their operating system’s file manager of choice onto the “dropzone”.
Once those documents appear within the Dropzone widget, the user must click on the ‘Upload’ button (or whatever you name it within the properties window) which executes a Microflow you design to create the File Document objects and store them. If that process is successful you’ll get a nice green check next to the document, and if it fails you’ll get a red ‘x’. This simple widget is effective at communicating to the user that the documents are in fact getting loaded and provides them a way to mass upload rather than one at a time.
Now that you’ve seen what the widget does for the user, let’s break down how to set it up.
First, go out to the App Store from within your application and search for ‘Dropzone’. It will appear and you can select to download it. Once finished it will notify you that it has been successfully imported into your application.
Before you just slap it on any page, however, there are a few things you need to consider in your design. First is the Domain Model. Most of the time you will create an entity in your application Module that is a generalization of the System.FileDocument entity and associate that with another entity that drives your data collection. In my example, I have an ‘Expense’ object associated with a ‘DocumentReceipt’ object, where ‘Expense’ drives my form and ‘DocumentReceipt’ is a generalization of System.FileDocument and captures images of receipts a person submits.
When using this widget, I created a Data View that passes in the Expense (in this instance I pass it to a popup window but it could exist on the main form as well). I then drop in the widget and setup the first tab in the properties as such:
The “Image Entity” in this case my ‘DocumentReceipt’ entity. Because of the association (many to one Expense) I can select ‘Expense’ through the “Association to Context”. That takes care of the first tab and the proper setup of the widget.
Next is the “Settings” tab. Here you can define how the dropzone appears to the user, such as height and width, file size maximum, and the caption on the button used to upload. That caption is all I changed for this example.
The next tab, ‘Events’, is the most important. Here you select the Microflow that will actually create and store these files that have been uploaded. Let’s look at what I did.
If you build a New Microflow while you are in the ‘Select’ window, it will automatically create a parameter of the FileDocument type you selected, which in my case was ‘DocumentReceipt’. You might get away with a simple commit here, or like me you might need to set additional associations or attributes. You will likely want to build in your own error handling as well to return a false Boolean. A ‘true’ will set that green check and a false will set a red ‘X’ next to the document within the dropzone to indicate to the user what was successfully created or wasn’t. (Note: it’s a good idea to add a message object to the user to describe why it failed if you can predict that path).
Technically, that is all that is needed. You users now have a slick way to upload documents into your app all at once. This widget can also be used the same way for Images if you are using the System.Image entity so you can leverage this feature for those files as well. While this is technically all that is needed, I will add that I then do a lot of Microflow work when the “Close” the page with a custom Microflow button that iterates through the newly added documents and makes changes elsewhere in the application, such as changing these documents to PDF’s, sending email alerts, and a host of other features.
Good luck using this widget. Thanks to Chris de Gelder at FlowFabric BV for its development as it has made for some very happy customers!