Where is the documentation for context api?

aswinckr

I'm new to sketch developer and i'm trying to wrap my head around the documentation . I see the javascript api reference here (https://developer.sketch.com/reference/api/) and i'm able to access the document, layers and everything listed here. But I see a lot of context api related actions on this forum and tutorials which I dont find anywhere in the documentation . For example context.document.currentPage() - Where can i find currentPage in the documentation?

mathieudutour

The context is slowly being deprecated. There are only very few cases where you actually need it (that would be for some actions and in those case, the documentation of the action usually contains the documentation for the context).

context.document.currentPage() can be replaced by require('sketch').getSelectedDocument().selectedPage

kevgski

Totally understand your confusion (there are lots of new developers that share your confusion!).

A bit of `context`

The Actions api (https://developer.sketch.com/plugins/actions) is older and hence why many of the tutorials on the web refer to that. The Action API is different than the JS API. In particular the Action API is, "a way to let plugins react to events in the app” whereas the JS API is used for interacting with Sketch objects.

In the past, there was no JS API so in order to interact with Sketch objects you would need to use the Sketch Headers (https://github.com/abynim/Sketch-Headers) to access the underlying internal API. You can read a bit more about this here (https://developer.sketch.com/plugins/internal-api).

Nowadays, the JS API wraps the native Sketch model objects inside javascript objects so you don’t need to look at the headers. You can drop down to the native Sketch objects at any time however the JS API is fully supported by Bohemian between releases (ie they try not to change it, unlike the internal API which they can and do change whenever they need to).

In Practice

So now that we got that bit of context out of the way, how do you put this into practice? Well, you can use the JS API by its self. (Follow along in the script panel! Plugins > Run Script…)

JS API

To get the current document and the selected page with the JS API you can do this:

let sketch = require('sketch')
let document = sketch.getSelectedDocument()
let page = document.selectedPage

Be sure to log each of those objects and check out their structure.

Action API & Native Objects

You can also use the Action API. context is available in the script panel as well.

console.log(context)

This will return a dictionary of useful objects. Probably the most useful of the bunch are document and selection.

let nativeDocument = context.document
console.log(nativeDocument)
// <MSDocument: 0x7fd0615f0a10>

You’ll see it returns this MSDocument object. All native sketch objects start with MS (I remember reading why in the past by I forget). To know where currentPage() is coming from you will need to look at those sketch headers that I mentioned earlier.

The method currentPage on MSDocument can be found here https://github.com/abynim/Sketch-Headers/blob/master/Headers/MSDocument.h#L56

So great now you have the currentPage

let nativeDocument = context.document
let nativePage = nativeDocument.currentPage()
console.log(nativePage)
// <MSPage: 0x7fd0615de890>

but now how do you interact with MSPage? Well, you look through the Sketch headers again 🙃. This process is really opaque and the methods on each of the objects can change from release to release so I don’t recommend this.

Bridging between the JS API and Native Sketch Objects

The JS API provides a handy way for taking a native Sketch Object and converting it to a JS object. You can do so with this

let sketch = require('sketch')
let nativeDocument = context.document

let wrappedDocument = sketch.fromNative(nativeDocument)
console.log(wrappedDocument)

Now this won’t work with all Native Sketch objects but it will work for the most common ones (the ones that the JS API has wrapped).

You can also go the other direction and get at native objects with this

let sketch = require('sketch')
let document = sketch.getSelectedDocument()

let nativeDocument = document.sketchObject
console.log(nativeDocument)

This info and more can be found in the JS API documentation here: https://developer.sketch.com/reference/api/#sketch-components

Using the Action API with the JS API

I rely on the Action API to trigger bits of code depending on what the user is doing. One common action to listen for is selectionChanged. You will need to register your plugin to “listen” for this action by setting it up in your plugin’s manifest.json file. I won’t go into the setup details for that (you can learn more about it here https://developer.sketch.com/plugins/actions#how-do-i-register-my-plugin-to-listen-for-an-action) and in the end you will have some function in your JS file like this.

export function onSelectionChanged(context) {
  // ### Extracting Context Information
  // Whenever sketch calls a handler in one of our plugins, it passes in a single context argument.
  // This dictionary is our connection with Sketch itself, and contains all the information that
  // we need to work out which document was open, perform whatever task we want to on it, and so on.
  //
  // When we're being called in response to an action occurring, the context will contain
  // an actionContext property with additional information about the action, so that's the first
  // thing that we want to retrieve:

  const action = context.actionContext

  // The context information for each action will be different. For the SelectionChanged action,
  // we are passed three interesting values: which document the selection has changed in,
  // what the old selection was, what the new selection is (or will be).

  // For our purposes, we can ignore the old selection, but we need the other two values.

  // let's wrap the native document
  const document = sketch.fromNative(action.document)
  // and transform the NSArray that is `newSelection` into a proper array
  const selection = toArray(action.newSelection)

This is code taken from one of the plugin examples (https://github.com/BohemianCoding/SketchAPI/blob/develop/examples/selection-changed/src/selection-changed.js#L20)

An alternative approach is to just ignore the context and just use the JS API. I tend to go this route whenever I don’t need anything specific from the context

let sketch = require('sketch')

export function onSelectionChanged() {
    let document = sketch.getSelectedDocument()
    // interact with the document at the time when this function is triggered
}

Tip:
To know what Action to listen for you can use the fantastic Sketch-dev-tools plugin (https://github.com/skpm/sketch-dev-tools)

Flip to the Actions tab and interact with sketch to see what Action is triggered when.

I realize its a bit of a long winded post about your issue but I hope that clarifies some things! If you are wanting to learn more about how to use the JS API I wrote an introduction here: https://medium.com/@kevingutowski/how-to-build-your-first-sketch-plugin-14c0e9e56bf0

aswinckr

kevgski Wow that's some crystal clear explanation. Thank you so much for all of this and your blog.

mathieudutour

👏👏👏

now that we got that bit of context out of the way

Nice pun 😁

kevgski

aswinckr Sure thing! I’m glad it helps! I realize in the gif I was searching for currentDocument and not currentPage. I’ll fix that in a bit.

aswinckr

Hi @kevgski . I have a couple of follow up questions. Sorry being a designer moving to code, I need to get a clear understanding of the fundamentals so later I can approach problems easier.

When you say Sketch Objects, these are files written in Objective C, right? If so how am I able to access the methods using the JS syntax ( dot operator )?
Why do we need to convert a Native Sketch Object and convert to a JS object? Do you have any examples of actions I can or cannot do with each of them ?

kevgski

aswinckr No worries! Happy to help clarify.

When you say Sketch Objects, these are files written in Objective C, right? If so how am I able to access the methods using the JS syntax ( dot operator )?

Native Sketch Objects are written in Objective-C. In general, if you are starting out you shouldn’t have to mess with these. In most cases, wrapping the native object to the JS one will do the trick. I talked about this a little bit earlier and to do this you can do something like this:

let sketch = require('sketch')

// Say you have some context - pull out the document from actionContext
const nativeDocument = context.document

// convert the native document to the js version
const jsDocument = sketch.fromNative(nativeDocument)

That being said, if you really want to just stick with native objects and methods you will use cocoascript (https://developer.sketch.com/plugins/cocoascript). Take a look at the syntax section there.

// say you have some context again
let nativeDocument = context.document

// instead of writing with objective-c brackets
let nativePage = [nativeDocument currentPage]

// you write
let nativePage = nativeDocument.currentPage()

Why do we need to convert a Native Sketch Object and convert to a JS object?

It's super important to understand that interacting with Native Sketch Objects is not the recommended approach. This is because with each release Sketch can change the these without any notice and your plugin will break. Sketch maintains the bridge between Native Sketch Objects and the JS API. So from release to release you will have a more stable plugin if you are using the Javascript API.
Working with native objects requires you to look at the sketch headers. There isn’t any documentation for how to interact with the underlying native sketch methods.
So why would you ever interact with a native object in the first place? The old Action API (a critical way to trigger pieces of code depending on various actions that a user can do in sketch) doesn’t return javascript objects. There is a new version of the Action API currently being developed so that you won’t have to worry about wrapping the native objects every time.

Do you have any examples of actions I can or cannot do with each of them?

Your question doesn’t quite make sense to me but I think I know what you are getting at. I’ll reiterate what the Action API lets you do. From the actions page (https://developer.sketch.com/plugins/actions)

“[It’s] a way to let plugins react to events in the app. Using it, plugin authors can write code that is executed when certain actions are triggered, like 'opening a document', 'saving', 'adding an artboard'…"

Check out the example earlier for onSelectionChanged.

Hope that helps!