In Writing Destinations for Dropzone, I showed you how to create a single file destination for extending Dropzone. This tutorial will build upon that base to show what is new in Dropzone 3 and how to take advantage of it.
As before, all code will be in Ruby. If you do not know how to program in Ruby, I suggest studying The Fundamentals of Ruby first.
Overview
Dropzone 3 has lost the destination circles that was unique to the original program.
In Dropzone 3, all the actions are in the drop-down icon menu from the menu bar. What was called a destination in the old version is now an action. This preserves the idea that anything can be performed on the files or text dropped onto a given action.
Dropzone 3 also dropped the usage of a single file Ruby script for an action. Dropzone 3 now uses a Mac OS X special folder that hides it’s contents from the average user. An action can now contain other supporting files that will not get in the way of other actions.
Clicking on the + symbol in the upper left corner reveals all the Built-in Actions and any User Actions.
Click on the gear in the upper right corner to get to the Preferences, Debug Console, Reset Actions, and Help menus.
The Drop Bar at the top of the drop-down is a handy place to store files while gathering files together before dropping them on to an action. Dragging and dropping files here does not move them. It stores their locations.
The second level with the heading FOLDERS / APPS is a quick launch bar for any program or folder placed there. If a file is dragged on to a program icon, the program will launch with that file loaded.
The last level is the actions that are set up to use. There is no limit to the number of actions. Actions can be used more than once with each one having it’s own presets.
Creating an Action
Create a new action by selecting Develop Action in the + menu.
This will bring up the Develop Action dialog.
Fill in the dialog as above and press Create Action. The editor that the system has configured for Ruby scripts will open with the created action file. The action.rb file is the starting point of the action.
Using the editor to reveal the location of this file, you will find it in the directory ~/Library/Application Support/Dropzone 3/Actions. In this directory, a special directory named Unpack.dzbundle that contains the action.rb file and a default icon.png file. All files for the action have to be here. The icon.png file is the picture that Dropzone displays in the drop-down menu. Replace this with the one given in the download.
The default starting file gives a basic overview of the Dropzone 3 API. Remove everything but the header for this example.
1 |
# Dropzone Action Info# Name: Unpack# Description: This action unpack zip files in to a specified directory.# Handles: Files# Creator: Richard Guay# URL: https://customct.com# Events: Clicked, Dragged# KeyModifiers: Command, Option, Control, Shift# SkipConfig: No# RunsSandboxed: Yes# Version: 1.0# MinDropzoneVersion: 3.2
|
The header is mostly the same as the previous version. I'll go over the new and changed items. Please refer to Writing Destinations for Dropzone for items not covered.
Handles
This description is not new, but greatly simplified. The possible Handles is now Files, Text, or both separated with a comma. Before, it was the more technical term for the same thing. For this action, put Files only.
KeyModifiers
When set, Dropzone will set the environment variable for key modifiers held down during the drag and drop or click actions. Since this action does not need modifiers, delete that line.
SkipConfig
This header tells Dropzone if the action needs configured or not. This action needs this setting to be set to false.
Version
This header is to tell Dropzone what version it is. This is for easier updating.
MinDropzoneVersion
This header specifies the lowest Dropzone version the action needs.
After the MinDropzoneVersion, add:
1 |
# OptionsNIB: ChooseFolder# UniqueID: 234985238238452835
|
The OptionsNIB tells Dropzone a preconfigured options panel to use. The possible values are:
- Login
- ExtendedLogin
- APIKey
- UsernameAPIKey
- ChooseFolder
- ChooseApplication
This action will use the ChooseFolder option. This will ask the user to specify a target folder for unzipping the files. The action will receive the value in the path environment variable.
The UniqueID has to be some random number that will uniquely identify the action package. If the action is listed on the main site, this will help determine versioning information. When the action is modified, Dropzone will inform others that the new version is available and can update it directly from Dropzone.
Dragged Action
The dragged() function is ran when the user drags files on to the action in the drop down menu. The dragged() function for the unpack action is:
1 |
def dragged # # Turn on determinate mode. # $dz.determinate(true) # # Get the data values. # if ( (ENV['path'] != nil) && (Filedirectory?(ENV['path'])) ) # # get the defaults. # dir = ENV['path'] # # Process each image file. # total = $items.count # # Tell dropzone we are starting... # $dz.begin("Unpacking #{total}files...") # # Index over all of the givenimages. # for index in 0 ... total # # Convert the image file. # `/usr/bin/unzip -n "#{$itemsindex]}" -d "#{dir}" ` # # Delete the original file. # File.delete($items[index]) # # Tell Dropzone what percentageis done. # $dz.percent((((index + 1)*100)total).to_i) end else # # The user did not configure theaction. Tell them. # $dz.error("Unpack Action", "You didnot give a target directory!") end # # Tell the user that it is done. # $dz.finish("Finished Unpacking.") # # Finish out the dropzone protocol. If you want a url in the clipboard, pass it # here. If you just want to copy text to the clipboard, use $dz.text()instead. # Either $dz.url() or $dz.text() has to be the last thing in the dragged method. # $dz.url(false)end |
The dragged() function tells Dropzone if it is determinate or not by using the $dz.determinate() function. This action is determinate, so true needs to be passed. If an Internet request is in the action, it needs to be set to false.
The action determines if a proper configuration exists. The if statement determines that by seeing if the variable used to give the presets exists and is a valid directory. If it is not configured, it uses the $dz.error() function to pass an error message to the user and exits the program. There is also a $dz.warning() function that gives the same type of dialog to the user, but does not stop the action. There is also a $dz.fail() function that works the same as $dz.error(), but leaves a X on the icon to show that the process totally failed.
If the path information is there and fine, it continues with the action. It tells Dropzone that it is starting with $ds.begin() function. That takes a string that is also passed to the user. All of the files dropped on to the action have their directory addresses in the $items array.
The action will loop over every $items passed and calls the standard zip program to unzip the file in to the designated directory. After each file gets processed, it deletes the original file and increases the percentage done using the $dz.percent() function.
Once done with all the files, the action calls the $dz.finish() function with a proper message. The last function call of an action has to be the $dz.url() or the $dz.text() function. An url or text to copy in to the clipboard can be passed. Otherwise, pass false.
Clicked Action
The clicked() function gets called whenever the user clicks on the action. This action will get a new directory to unzip the archives. This is not needed, but shows how to use some of Dropzone 3’s new functions. The clicked() function is below:
1 |
def clicked # # The clicked handler should get the destination directory to use and # save it. # # # Request the width of the graphic. # dir =$dz.cocoa_dialog("fileselect --select-directories ‑‑select‑only-directories --title 'Unpack to Directory' ").split("\n") # # See if the user canceled out. Do not continue if they cancel. # if ((dir[0] != nil)&&(File.directory?(dir[0]))) # # Save the directory location. # $dz.save_value("path", dir[0]) else # # The user did not configure the action. Tell them. # $dz.error("Unpack Action", "You canceled out! You did not give a target directory!") end # # Tell the user that it is done. # $dz.finish("Unpack Directory: #{dir[0]}") # # Finish out the dropzone protocol. If you want a url in the clipboard, pass it # here. If you just want to copy text to the clipboard, use $dz.text() instead. # Either $dz.url() or $dz.text() has to be the last thing in the clicked method. # $dz.url(false)end |
The clicked() function requests a new directory from the user using the $dz.cocoa_dialog() function. This function takes the command line for the Cocoa Dialog program as the function’s parameter, passes it to Cocoa Dialog program, and returns the results of calling the Cocoa Dialog program.
The results are split up at the Enter character into an array of strings. It checks for a valid directory and that the user did not push the cancel button. If this fails, it uses $dz.error() function to tell the user and exit. Otherwise, it saves the directory in to Dropzone using the $dz.save_value() function. Anything saved with this function in an action is retrievable in the environment variables upon re-execution.
The function exits as the dragged() function did.
Other Functions
Dropzone 3 also has a temporary file folder function called $dz.temp_folder(). It returns the directory that is be use to create temporary files.
If you need to copy or move files, the Rsync.do_copy() function needs to be used.
Any Key Modifiers specified in the header are in the ENV['KEY_MODIFIERS'] environment variable.
Debugging
The new debug console is a great addition. To open the console, select it from the menu:
The console will already show all the output from the last action used.
The console shows all the VARIABLEs passed in the environment, the EVENT (clicked in this example), any Save_Values, and the final message given to the user.
When this line is added after the $dz.Save_Value() function,
1 |
`puts "The information given: " + dir[0]`
|
this debugging information will be viewable in the console:
The extra information is there in red. This gives a convenient way to debug action scripts.
Conclusion
In this tutorial, I showed you the differences in the new version of Dropzone and how to create your own action to unzip files to a user specified directory. Now that you know how to create actions, go make some and share them with everyone.
