The Beginner’s Guide to Writing Sketch Plugins Part 5 — The MSLayer Class

Now that we have seen some working real world examples of what classes in Sketch can do, we can begin to examine them even further. In this article we’ll focus on the MSLayer class, and then begin to cover all the classes that inherit this.

The MSLayer class is the base class of all layers in Sketch, and all other layer types are subclasses and inherit everything that comes with it. Anything you add to your document is essentially a layer — a page, artboard, group, shape, text, image, and more. All of these are subclasses of the MSLayer Class and they can do everything the MSLayer class can do, plus more.

To understand the terminology better, there are two types accessible data within a class:

  1. Attributes — a named property of an object (like it’s height, width or name)
  2. Methods — functions attached to classes, usually used to change attributes (like change it’s height, width or name)

The documentation on the developer site already does a pretty good job of defining the base classes attributes and methods. So I won’t reiterate too much of it. But instead, I’ll show the easiest ways to view a layer’s attributes and how to use it’s methods in the real world.

Getting a layer’s attributes

In the previous article, we looked at two ways to get to a layer’s data: by looping through the selection array, and by nesting for loops in the page document array.

Let’s assume you’ve used the selection array to get a variable named layer like this:

Knowing that all layers are subclasses of the base class MSLayer, means that we can get the same attributes from any type of layer regardless of it’s specificity, and then store them in variables for future access.

Some attributes are actually instances of other classes and have their own attributes and methods based on those classes. For those, I’ll show a couple examples of how you can go even deeper with the data, but for a more detailed description follow the link to the documentation (or wait until my next articles).

Here are a few attributes you can access in the MSLayer class:

Class (type of layer):

var layerClass = layer.class();

Frame (size and position, relative to it’s artboard, instance of an MSRect):

var layerFrame = layer.frame();
var layerWidth = layerFrame.width();
var layerHeight = layerFrame.height();
var layerXpos = layerFrame.x();
var layerYpos = layerFrame.y();

Style (borders, fills, shadows, inner shadows, instance of MSStyle):

var layerStyle = layer.style();
//get the fill colors array
var layerFills = layer.style().fills();
//get each fill color
for(var z = 0; z < layerFills.count(); z++){
var fillColor = layerFills[z].colorGeneric();
}

Name:

var layerName = layer.name();

Visibility:

var layerIsVisible = layer.isVisible();

Locked Status:

var layerIsLocked = layer.isLocked();

Flipped Status (horizontal or vertical):

//horizontal
var layerIsFlippedHorizontal = layer.isFlippedHorizontal();
//vertical
var layerIsFlippedVertical = layer.isFlippedVertical();

Rotation:

var layerRotation = layer.rotation();

Parent Group (either a page, artboard, or group):

var layerParent = layer.parentGroup();

Selected Status:

var layerIsSelected = layer.isSelected();

Absolute Rect (global size and position within the entire document, instance of an MSAbsoluteRect):

var layerAbsoluteRect = layer.absoluteRect();
var layerAbsoluteWidth = layerAbsoluteRect.width();
var layerAbsoluteHeight = layerAbsoluteRect.height();
var layerAbsoluteXpos = layerAbsoluteRect.x();
var layerAbsoluteYpos = layerAbsoluteRect.y();

CSSAttributeString:

var layerCSSAttributeString = layer.CSSAttributeString();

CSSAttributes:

var layerCSSAttributes = layer.CSSAttributes();

There are a few more in the documentation, but those are the ones I normally use. I kind of pick and choose what I want based on the needs of the script. But if you really wanted to store all of these attributes in variables at once, you could do something like this:

Then you can use the Console to log any of the variables you want to see:

log(“Layer Rotation: “ + layerRotation);

Using methods

Now that we can get a layer’s attributes, we can use methods to set them. The MSLayer class has a few accessible methods that allow you to change specific attributes of any layer. Their names are pretty self explanatory to what they do.

setName

var newLayerName = "New Layer Name";
layer.setName(newLayerName);

setIsVisible

//show layer
layer.setIsVisible(true);
//hide layer
layer.setIsVisible(false);
//toggle
layer.setIsVisible(!layer.isVisible())

setIsLocked

//lock layer
layer.setIsLocked(true);
//unlock layer
layer.setIsLocked(false);
//toggle
layer.setIsLocked(!layer.isLocked());

setRotation

var newLayerRotation = 180;
layer.setRotation(newLayerRotation);

setIsFlippedHorizontal

//flip horizontal
layer.setIsFlippedHorizontal(true);
//reset
layer.setIsFlippedHorizontal(false);
//toggle
layer.setIsFlippedHorizontal(!layer.isFlippedHorizontal());

setIsFlippedVertical

//flip vertical
layer.setIsFlippedVertical(true);
//reset
layer.setIsFlippedVertical(false);
//toggle
layer.setIsFlippedVertical(!layer.isFlippedVertical());

setIsSelected

//select
layer.setIsSelected(true);
//deselect
layer.setIsSelected(false);
//toggle
layer.setIsSelected(!layer.isSelected());

duplicate

layer.duplicate();

Now you can start to see the different types of plugins you can create by just getting a layer’s attribute and then setting it.

For example, if you wanted to unlock all layers, you’d first check if it’s locked, then you can unlock it:

Or if you wanted to add a prefix to a layer name:

And much more, the options are really endless!

Attribute methods

The attributes that are instances of other classes, like frame and style, also have methods of their own.

For example, to change the width of a layer to 100, you would use setWidth on the frame variable:

Or if you wanted to add a fill to a layer you would use addStylePartOfType(0) on the style variable:

Finding the Layer Subclass Type

Those are all the things you can do with any MSLayer, but what if you wanted something specific to it’s type? Like for example, if you wanted to read the String of text from a text field, you’d need to know if it’s a text field first or your code will throw an error if no String exists.

Not all subclasses are listed in the documentation, but since we can find out a layer’s class from the class attribute, we can easily figure this out. And to make this even easier, I wrote a plugin to do it!

  • Download and install the Show Layer Type Plugin here
  • Then download and open this Sketch file to follow along.

In the Sketch file, you’ll see an artboard with a few different types of layers on it — 2 lines, a symbol, 2 text fields, and a rectangle.

Select all of the layers and run the Show Layer Type Plugin. In the console you’ll see this output.

8/28/16 9:07:18.993 AM Show Layer Type (Sketch Plugin)[46515]: Background is a: MSShapeGroup
8/28/16 9:07:18.997 AM Show Layer Type (Sketch Plugin)[46515]: Line is a: MSShapeGroup
8/28/16 9:07:18.999 AM Show Layer Type (Sketch Plugin)[46515]: Author is a: MSTextLayer
8/28/16 9:07:18.999 AM Show Layer Type (Sketch Plugin)[46515]: Icon is a: MSBitmapLayer
8/28/16 9:07:19.000 AM Show Layer Type (Sketch Plugin)[46515]: Oval is a: MSSymbolInstance
8/28/16 9:07:19.001 AM Show Layer Type (Sketch Plugin)[46515]: Title is a: MSTextLayer
8/28/16 9:07:19.002 AM Show Layer Type (Sketch Plugin)[46515]: Line is a: MSShapeGroup

If you go to your Symbols page and select a symbol, run the plugin again and you’ll see this:

8/28/16 9:10:08.600 AM Show Layer Type (Sketch Plugin)[46515]: Oval is a: MSSymbolMaster

If you select an artboard and run the plugin you’ll see this:

8/28/16 9:10:48.226 AM Show Layer Type (Sketch Plugin)[46515]: Artboard 1 is a: MSArtboardGroup

If you take all the layers on the artboard and group them, then run the plugin you’ll get this:

8/28/16 9:11:24.234 AM Show Layer Type (Sketch Plugin)[46515]: Group is a: MSLayerGroup

And there you go! All the layer subclass types pretty much. There are probably more, but these are the ones I’ve found so far (I’ve linked the ones that are documented).

MSShapeGroup
MSBitmapLayer
MSTextLayer
MSSymbolInstance
MSSymbolMaster
MSArtboardGroup
MSLayerGroup

Now we can start to differentiate our code depending on what the layer class is by using if/else statements.

Each of these subclasses have a lot more attributes and methods to access, which we’ll cover in the next article. So take a look at the documentation of the layer subclasses to get a head start!

Conclusion

To summarize, in this article, we learned how to:

  • View a layer’s attributes
  • Change attributes on a layer with methods
  • Access an attribute’s own attributes and methods
  • How to view a layer’s class type and differentiate between them through code

Coming up next, I’ll be writing a more detailed breakdown on the specific layer class types, and of course more script examples! Good luck with writing your own plugins, and I’d love to see anything you guys have done so far.

Feel free to contact me with feedback or suggestions for the next articles: Twitter, Facebook, or Email.

Continue to Part 6