[Feedback Wanted] New Events API

markh

I've recently joined Sketch to work on the plugin API.

The Actions API was originally designed as a way to trigger actions in Sketch as well as a way to listen for changes. There have been some issues with it so we are working on a replacement that just focuses on events i.e. when something happens in Sketch, plugins will be notified. We are currently working on notifying plugins when changes to the document occur and we would like to get your feedback on it.

In your plugin you will have a onDocumentChanged function where you can get access to changeSet. You can query this to get the layers/properties that have changed or the layers that have been created or deleted. Unlike actions, objects will be wrapped JavaScript objects rather than native Sketch objects. The function will be executed at a reasonable interval i.e. if you drag a layer, it will be called when you have finished dragging the layer rather than continuously as you drag the layer. We plan on supporting most of the properties currently in the JavaScript API. For example if you move or resize a layer the changed property will be frame or if you change the color of the first fill, the property will be style.fills[0].color.

Here is an example of what the code might look like:

function onDocumentChanged(context) {
  const changeSet = context.eventContext.changeSet

  /*
  Get the layers/properties that have changed. Optionally filtered by properties and layers

  changeSet.getChangedLayers(options)
  
  options: Object, optional
    properties: array of strings
    layers: array of Layers or strings (layer IDs)
  
  Returns:
  [
    {
      layer: Layer,
      properties: {
        frame: {
          prevValue: Rectangle,
          value: Rectangle
        }
      }
    }
  ]
  */
  
  // Examples
  let changedLayers = changeSet.getChangedLayers()
  changedLayers = changeSet.getChangedLayers({ properties: ['frame'] })
  changedLayers = changeSet.getChangedLayers({ properties: ['frame', 'hidden'], layers: [layer1] })
  changedLayers = changeSet.getChangedLayers({ properties: ['frame'], layers: [layer1.id, layer2.id] })

  /*
  Get the layers that have been created or deleted

  changeSet.createdLayers
  changeSet.deletedLayers
  
  Returns an array of Layers
  */

  // Examples
  let createdLayers = changeSet.createdLayers
  let deletedLayers = changeSet.deletedLayers
}

You will also be able to do the same for other objects like text and layer styles:

let changedSharedStyles = changeSet.getChangedTextStyles()
let createdSharedStyles = changeSet.createdTextStyles
let deletedSharedStyles = changeSet.deletedTextStyles

Let me know what you think and also let me know if think there is a use-case you had in mind that the above doesn't cover.

kevgski

Very interesting! I like the fact that it is using the wrapped JS objects. Seems like with this approach there is no concept of willChange / didChange (kind of like property observers). Often times, its useful to trigger something that will about to happen as well as after it happened. It also isn’t clear to me wether you would be able to get the old parameters in addition to the changed ones. (Also, congrats on the new gig! 🎉)

markh

kevgski

It also isn’t clear to me wether you would be able to get the old parameters in addition to the changed ones.

I don't quite understand what you mean by "old parameters". For the changed properties you will be able to get the old value and the current value so you can do things like work out whether a value has increased or decreased.

kevgski

markh

For the changed properties you will be able to get the old value and the current value so you can do things like work out whether a value has increased or decreased.

Ah gotcha. Wasn’t clear to me that would be the case but now I see prevValue and value in the example 👍

Is there a way you can filter the layers only if their previous value was something or if the new value is something?

changedLayers = changeSet.getChangedLayers({properties: ['frame’][‘prevValue’] = {x:0,y:0,width:100,height:100}})

markh

kevgski

Is there a way you can filter the layers only if their previous value was something or if the new value is something?

You can only filter by properties and/or layers. You could filter the returned array like this:

const changedLayers = changeSet.getChangedLayers({properties: ['frame’]}).filter(changedLayer => {
    const prevValue = changedLayer.properties.prevValue
    return prevValue.x === 0 && prevValue.y === 0 && prevValue.width === 100 && prevValue.height === 100
})

WCByrne

This looks like it will be a great improvement over actions! Being able to get everything via a single action feels much cleaner than having many different actions.

Would this include layer/text styles as well?

markh

WCByrne

Being able to get everything via a single action feels much cleaner than having many different actions.

The above is just for the DocumentChanged event. There will be a few other events like SelectionChanged and DocumentOpened but the number of events will be reduced compared to actions.

Would this include layer/text styles as well?

Yes, there will be methods to access changed/created/deleted text/layer styles, just like layers.

huw

I don't mind this idea, provided that the old Actions API is still available for more complex interactions with Sketch's backend.

While you're at it — it would be really useful to have a 'ColorPicked' action (including which library the color was from) and a 'SymbolInserted' action. Currently have to use hacks to work those ones out.

rnmp

Hi, late in the convo but I have a sort of related request. Can you guys add an action event for whenever a user switches between documents? I have a plugin that displays a panel with information related to the current document, and right now I'm relying on selectionChanged but as you can imagine, that option is very limited.

markh

rnmp

Can you guys add an action event for whenever a user switches between documents?

That would be a useful event alright. I'll add it to the proposed list of events.

rnmp

Another useful event would be "windowResized" to use to reposition a panel. Definitely lower priority tho.

vikaspachdha

+1. Also, is there any plan to add an event when the activeDocument changes?

christianklotz

I agree, window resize, active document changes etc. are very important but are linked much more to the Sketch runtime and application state.

In contrast, the API presented here focuses on document changes and works no matter how these changes were triggered, i.e. through menus, canvas or undo. It would be interesting to know how your opinion on non-document-change APIs/events however.

danielthall

Something I've been trying to find a way to do is run some scripts just before updating a library. A prime use case I have for this is if I have a Symbol Master that has a symbol with a text override change, I'll lose my overrides. I have a workaround for this today, but I'd love to be able to listen for a library update event, get the symbols that will be changing, run some script, proceed with the update, then run some other script once it is done.

jwdallas

This looks really awesome. Just want to tack on request for an event that fires before document save. Unless I'm reading this wrong, I don't think the new API will support that case.

The usecase for this is plugins that apply formatting to the document on save. Currently we only have a DocumentSaved action which means the document effectively has to save twice (once to trigger the plugin, then again after the plugin modified the document). This requires plugins of this sort to maintain a bunch of otherwise unnecessary diffing logic to make sure it doesn't change the document if it doesn't have to (which would result in an infinite loop).

der-lukas

This looks great - would this also trigger events when changing a property of a textLayer? Currently I am not able to know if a textlayer has been changed unless I unselect and reselect it again...

What's the ETA on this?

christianklotz

@jwandrews this API proposal covers document mutations only, however all of them. Lifecycle events such as a document being saved would be separate.

@der-lukas it would indeed, the change handler is intended to trigger on any document mutation. I can't share a definite ETA on this just yet but we're aware this would help a lot of people writing plugins 🙂

Lifeofmle

This event will be really helpful to detect style changes. Is there any known way of doing something like this with the current API?

Lifeofmle

This new event would be helpful because at the moment I'm using polling to detect changes to a layer. Would be happy to try this new API out when it is ready. Here is my plugin that polls https://github.com/lifeofmle/check-contrast