The simple guide to getting user input for your Sketch plugin – Part I

When we were working on our Sketch Confetti plugin, I noticed how hard it was to find good documentation to help us build something as basic as a dialog window for the plugin. The lack of documentation hit me the hardest when I was building a dialog window. The idea was to create a dialog window with plugin options that would be shown when the user ran the plugin. However, I lost a lot of time to find out how I could build the dialog window that I had in mind. I had to dig into the code of other Sketch plugins to get a basic idea of how dialog windows work in Sketch. If you are reading this, you are probably in the same position I was when I spent hours online looking for a way to build Sketch dialog windows. You’re lucky though, your struggle ends here.

I’ve documented my findings and simplified the proces of creating a dialog window for your Sketch plugin. As this article turned out quite lengthy, we decided to split it up in 2 parts. Enjoy part 1 and stay tuned for part 2 in the near future.

Table of Contents

The Dialog Developer Toolkit

• Javascript
• Cocoascript
• Apple’s AppKit Framework

Simple Dialog Windows

• Display a message
• Get some input

Advanced Dialog Windows

• Setting up the dialog window
• Positioning elements (labels, input fields, images … ) on the dialog window
• Creating labels
• Creating inputs
• — TextInput
• — Dropdown
• — Checkbox
• — Radio Button
• Display the dialog
• … (part 2)

What we’ll need

JavaScript
That’s right, this familiar face in world of programming languages joined the party! You’ll be able to use all your JavaScript skills to build awesome Sketch plugins.

CocoaScript
Sketch defines CocoaScript as “a bridge that lets you use Objective-C/Cocoa code from an external script written in JavaScript. The bridge takes care of the translation between JavaScript and Cocoa”. When using CocoaScript, we can simply use JavaScript and also access Apple’s Cocoa framework, which opens a ton of possibilities.

AppKit
You can use Apple’s AppKit framework to create a dialog window just the way you like. The possibilities are quite limitless. It may feel a little daunting when trying to build a dialog window for your Sketch plugin when you are not familiair with AppKit (or even with Cocoascript in general). However, fear not. A basic Javascript skillset is enough to create a luxurious dialog window when you follow this guide.

Simple Dialog Windows

Not every plugin needs an advanced dialog window. Sometimes, a basic input or message just might do the trick. If you’re looking for some simple way of getting basic input from the user and displaying output to the user via a message, you’ll find the answers you need below.

Display a message

Get some input

So far so good, but things get more tricky when your plugin requires an advanced dialog window (with multiple types of input fields).

Advanced Dialog Windows

When you require (or offer) the user to change the settings of your plugin, it might be a good idea to group all these options in a single dialog window. You don’t want to frustrate the user by spamming them with a series of dialog windows. In the following section, we’ll be making a more advanced dialog window for your Sketch plugin.

You don’t want to frustrate the user by spamming them with a series of dialog windows

Setting up the dialog window

You might want to make a function (mine is called createWindow() ) where you place all the code you’ll use to build your dialog and the input types.

Positioning elements (labels, input fields, images … ) on the dialog window

You can design your dialog just the way you like. You can use labels, input fields, images … However, you can’t just throw all these items on the dialog willy nilly. You want to position the items on the screen in a logical structured manner. To do this, we have to first understand how items can be positioned on a dialog.

To position elements (like labels, textfields, buttons …) we’ll be using AppKits NSMakeRect.

Creating labels

Add some text to your dialog by using labels

Labels are a great (and simple) way to display some text on your dialog window, wherever you’d like.

Creating inputs

Although labels are nice, they are just that; static labels. Eventually, you’ll want to get input from the user (text input, a selected option from a dropdown … ) and process this input. In this section of the article, we’ll tackle how you can create inputs and display them on the form, ready to receive input from the user.

Note: in the following code examples, the variables for the inputs will be declared locally. In a real world project, you’d want to declare them globally so you can call them in other functions. A snippet of the complete code (with globally declared variables) is available at part 2

TextInput

If we only want to get some text from the user, a simple dialog window with a single input field (check it out at the top of this article) might be enough. But if we want more control over our fields (or if we want multiple inputs displayed in the same window), we’ll need for a more advanced dialog window. We’ll use an input of type NSTextField to create our input fields.

Dropdown

A dropdown is a great way to make a user select an option out of a predefined (large) list of options

If we want our user to select an option from a predefined dropdown list, we can use a NSPopUpButton

A dropdown is a great way to make the user select an option out of a predefined (large) list of options

Checkbox

Checkboxes make a great way to toggle options

A checkbox is actually a type of button, so the input type we’ll be using is NSSwitchButton.

Radio Button

Radio Buttons are a great way to make u user choose exactly one option

Although a radio button kinda looks like a checkbox, the code behind is a bit more advanced. To craft a radio button we have to create an instance of NSButton with a button type of NSRadioButton. However, radio buttons are used to select 1 option out of a selection so we have to group radio buttons in order for them to make sense.

You would expect that we would make a radio button for every option and position that radio button on the dialog, but the actual flow will be quite different. Instead, we are going to define a NSMatrix that will contain our cells (aka radio buttons). By placing these radio buttons in a NSMatrix, the radio buttons will be able to ‘work together’. This means that the user can never select more than 1 radio button, just like how radio buttons are supposed to work.

Displaying the dialog

We just initialized a dialog window inside the function createWindows(), so to display the dialog, we simply have to call this window. If you’d want to open the dialog when the user clicks a menu item, you could refer to this second function in your manifest.json file. If you’re getting confused you can find the whole piece of code at the bottom of this article.

I have created a function getUserInput() that calls the dialog and also handles the response. Don’t worry about this though, we’ll figure out how to do that in part 2 of the series.

Function to call the dialog

Coming up in part 2

Congratulations, you now have a nice looking custom dialog window for your Sketch plugin. We’re not done yet, though. The dialog window may look finished, but unless we find a way to get and process the data provided by our user, the dialog is completely pointless. Fortunately, we’ll show you exactly how to do this in part 2 of the series. See you guys then!

You can now make this!