Selectors

How do I make a selector?

Selectors are what connect user interactions with the generation and saving of Annotation objects. A selector is generally composed as follows:

export default function Selector({...options})
  return {
    conditions: function(e) {
      //required
      //conditions that need to be true for the selection interaction to begin and continue
      //Should return a boolean
    },
    onSelectionStart: function(e) {
      //optional
      //Handler that will fire when the selection begins
    }
    onSelectionChange: function(e) {
      //optional
      //Fires as new events come in (some may or my not be relevant to the selection)
    },
    onSelectionEnd: function(e) {
      //optional (but you almost always have)
      //either cancel the selection
    }
  }
}

How do they work?

Whenever the "condition" method returns true, a selector is considered to be active. The first time this occurs, the onSelectionStart method is fired. As additional events come in, the onSelectionChange method is called, such that the selector can update its visuals to correspond with the user's actions. Finally, when the condition is no longer true, the onSelectionEnd method is called, and the developer should appropriately generate and begin the process for saving an Annotation.

To accomplish this, SiphonTools automatically tracks a number of user generated events, including mouse events, key events, touch, etc. Internally, the current state of these interactions are recorded into a "state" object (specifically, as defined below), and then passed into a selector as the e (or "Event") parameter.

let selectionState = {
  mouseDown: false,
  mouseUp: false,
  mousePosition: false,
  currentKey: false,
  previousKey: false,
  pointerDown: false,
  pointerUp: false,
  pointerPosition: false
}

While the mouse is down, the mouseDown property will be set with the most recent mouseDown data and mouseUp will be set to false. When it's moved, mousePosition will be set and updated, and when lifted up, mouseDown will be set to false and the mouseUp property will be set with that event data.

Most importantly, when any of these interactions occur, any of the registered Selectors with SiphonTools (through the initializeSelectors method) will be checked against this current state. Whenever an event occurs, SiphonTools will constantly check if any selectors are true, and send them the appropriate updates.

Provided Selectors

SiphonTools has a number of fairly general-purpose selectors that you can use with just a little configuration:

• ClickElementSelector({selector, onClick}) - Takes in a CSS Selector and then an onClick handler. When an element matching the selector has a click event dispatched to it, the "onClick" method will be called.
• DoubleTapSelector({key, afterTap, delta = 500}) - When a key is pressed twice within the delta period, the afterTap handler will be called.
• ElementSelector({onComplete}) - A user can hold down the shift key, and then select different HTML elements, similar to the Chrome inspector. When the shift key is released, the onComplete handler is called, with the elements selected as the 1st param, and the boxes showing which elements were selected as the 2nd.
• HighlightSelector({onTrigger}) - The onTrigger method when the user completes a text selection interaction using the in-built browser selection mechanism. The method is passed the selection range, and the current SiphonTools selection state
• HoverElementSelector({selector, displayOverlay, hideOverlay}) - When the user hovers over an element that matches the provided CSS Selector, the displayOverlay method is called. This is passed the matching element, as well as the current SiphonTools selection state. When a user is no longer hovering over a matching element, the hideOverlay method is called with the matching element, as well as the current SiphonTools selection state.
• SnippetSelector({onTrigger}) - With this selector, a user can draw a rectangle on the current page by holding down the Alt or Meta key, clicking on the page and then moving their mouse to the end point for the box. When they are finished drawing the box (by releasing the mouse button while still holding don the Alt or Meta Key), the onTrigger method is called with the "box" element passed to it, along with the current SiphonTools selection state.