The Beginner’s Guide to Writing Sketch Plugins Part 1 — Getting Started – Medium

The Beginner’s Guide to Writing Sketch Plugins Part 1 — Getting Started So you want to start writing Sketch plugins, but have no idea where to start? Well keep reading because this article is for you! If you’re like me, trying to find basic concepts out there is not easy. There’s tons of examples of existing plugins, but it’s hard to know where to begin. So to help, I’ve compiled all the information I’ve found into one easy location. This is definitely not an advanced guide to writing plugins, as I’m not a

Source: The Beginner’s Guide to Writing Sketch Plugins Part 1 — Getting Started – Medium

 

The Beginner’s Guide to Writing Sketch Plugins Part 1 — Getting Started

So you want to start writing Sketch plugins, but have no idea where to start? Well keep reading because this article is for you!

If you’re like me, trying to find basic concepts out there is not easy. There’s tons of examples of existing plugins, but it’s hard to know where to begin. So to help, I’ve compiled all the information I’ve found into one easy location.

This is definitely not an advanced guide to writing plugins, as I’m not a developer. I’m a UI/UX Designer that happens to code pretty decently (so I think). Real developers might cry openly when they see my code, but I think I code in a way that is understandable to beginners.

If you’re an engineer looking for more advanced examples, there’s a wealth of information here: http://james.ooo/sketch-plugin-development and at the official Sketch developer site: http://developer.sketchapp.com/

Why Write a Plugin?

Plugins are perfect for automating repetitive tasks, they make work and production much easier. Chances are there’s already a plugin for what you need to do, so be sure to search first before attempting to write your own, because most likely someone else has done it better. But if your process of creating UI is unique (like for me, designing UI for games in Unity) you’ll most likely need a custom solution.

Getting Started

Before you start writing a line of code, start by getting all your software and bookmarks set up.

  1. If you don’t already have one, download a text editor. (I useTextmate out of habit, but there a lot of great text editors out there like Sublime) Edit: I’ve discovered Atom, and it’s better!
  2. Next, open your Console for debugging, and add it to your Dock, you’ll be using this a lot.

3. The Console is used by your machine for ALL debugging, so create a new Sketch System Query Log filter by: File > New System Query Log

Copy these settings and press Ok.

You should now see a Sketch filter in the left hand column.

4. Bookmark your Sketch Plugins folder for quick access by adding it to your Favorites in your Finder window.

You’ll be accessing this folder a lot too, and having it hidden in your Library makes it a bit annoying to navigate to.

/Library/Application support/com.bohemiancoding.sketch3/Plugins

And now you’re ready to write your first plugin!

Creating a Plugin in 10 Easy Steps

Sketch plugins are basically folders with the .sketchplugin extension, which makes it easier to share with other users.

For this demo, we’ll make a basic script to get the name of a Page. You don’t need to know how to code to get this working, but it does help if you understand some basic concepts. In posts to come, I will be documenting the various scripts I’ve been using to get specific data from Sketch and customize it. But for this demo, I’ll just be using this one.

Sketch plugins are written in CocoaScript, which is a mixture of Objective-C/Cocoa and JavaScript. I’m pretty familiar with Javascript, so picking it up wasn’t too difficult. I won’t say I’m fluent in it by any means, but I seem to be able to hack my way around it with some basic knowledge of JavaScript.

With that in mind, let’s get started!

  1. Start by creating a new folder in your Sketch Plugins folder and call it MyPlugin.sketchplugin

(Once you add the .sketchplugin extension, double clicking it will try to install the plugin instead of opening the folder. To open it, Right-Click the plugin and choose Show Package Contents)

2. Inside that folder, create a folder called Contents

3. Inside Contents, create a folder called Sketch

Your final plugin folder structure should look like this:

Inside the Sketch folder is where you’ll start to create your plugin, which at the minimum consists of 2 files, a manifest and a script.

The manifest describes the plugin and can add things like keyboard shortcuts or additional scripts, they are always named manifest.json

The script is where the actual plugin code will go and is referenced in the manifest. The names can be customized to however you like as long as they match in both files.

4. In your text editor, create a new file called manifest.json and save it to MyPlugin.sketchplugin > Contents > Sketch

5. Copy and paste this code into manifest.json, and save.

{
 “name” : “My Plugin”,
 “identifier” : “my.plugin”,
 “version” : “1.0”,
 “description” : “My First Sketch Plugin”,
 “authorEmail” : “your@email.com”,
 “author” : “Your Name”,
 
 “commands” : [
 {
 “script” : “MyScript.js”,
 “handler” : “onRun”,
 “shortcut” : “command shift y”,
 “name” : “Get Page Names”,
 “identifier” : “my.plugin.pagenames”
 }
 ],
}

You should now see MyPlugin in your Sketch plugins menu. You can change the name of the plugin, or the shortcut and it will reflect in the Plugins menu in Sketch. For shortcuts, it’s important you choose one that isn’t already assigned to an existing application or plugin shortcut, or it won’t show up.

Now let’s create MyScript.js, which the manifest refers to and loads when selected. Make sure this name matches your manifest file!

6. Go back to your text editor and create a new file named MyScript.js and also save it into the MyPlugin.sketchplugin > Contents > Sketch folder

7. Copy and paste this code into the MyScript.js

var onRun = function(context) {
 
 //reference the Sketch Document
 var doc = context.document;
 
 //reference all the pages in the document in an array
 var pages = [doc pages];
 
 //loop through the pages of the document
 for (var i = 0; i < pages.count(); i++){
 
 //reference each page
 var page = pages[i];
 
 //get the name of the page
 var pageName = [page name];
 
 //show the page name in the console
 log(pageName);
 }
}

I’ll better explain this script in some follow up posts along with additional snippets. But for now, the comments explain what each line does.

8. Go to Sketch and open a new file, if you don’t already have one open

9. From the Plugins menu, select MyPlugin > Get Page Names

10. Go to your console and at the bottom of the log you should see the page name.

Try changing the page name in the Sketch file and re-running the plugin. The log should show the new name. Add an other page and rename it then run the plugin, the console will now show both page names.

And That’s It!

There’s obviously a lot more you can do with plugins, but this is really just to get you started. I’ve only been using Sketch for a few weeks and I’m already impressed with it’s customization and power. Hopefully this helps other people who have encountered the same issues I had getting started, as the Plugin community only gets better with more people contributing.

You can download this plugin example here. Feel free to contact me for any questions: Twitter, Facebook, Email.

Continue to Part 2