title: How to manually generate notifications to a Google Doc collaborator?
body: <p><strong>Simple Use Case</strong>:
  Jane and Sue are collaboratively improvising a story in a Google Doc. Each adds at most a couple of sentences at a time and clicks an icon that notifies the other it's her turn. </p>
  
  <p><strong>Requirements:</strong> Ideally, the notification is apparent but unobtrusive as the collaborators may be doing other tasks in between contributions to the story. A solution that sends an email or text message is not desirable since the collaboration could generate hundreds of such messages and no one wants a more cluttered inbox. A good solution might pop up an alert or change the color of an icon in the browser.</p>
  
  <p>Note also that this is not the same as notifying of a change in the file since the Google Doc AutoSave will happily save an incomplete sentence if the writer stops to think about the wording of the next phrase. The notifications need to be controlled by the writer. </p>
  
  <p>I would accept a solution specific to Chrome and/or OS X but the more general the better.</p>
  
  <p><strong>Edit:</strong>
  It looks as though using the Chrome Extensions API in conjunction with the Google Docs API is a feasible approach.  Below is a CoffeeScript pseudocode mockup of the application logic I'd like to create. As my current experience with either of these API's is limited, I'd appreciate feedback on whether the necessary capability exists in these API's. (Note: the function names in my pseudocode are not intended to match the names of any API calls. They simply identify what I want to do.)</p>
  
  <p>In the code below, the term 'stickholder' refers to the idea of a Native American talking stick, a token that entitles its current holder to speak to the group. In this case, the stickholder is the id of the collaborator whose turn it is to make the next contribution.</p>
  
      
  
  <pre><code>$(extension_icon).on "click", clickHandler
  $(extension).on "changed_doc", changeHandler
  
  clickHandler = () -&gt;
    adoc = getActiveBrowserPage()
    if isEditableGDoc adoc
      # Add to locally stored doc list
      # (if it's not there already)
      addToMonitoredDocList adoc
      # Check stick holder and adjust extension state.
      stickholder = getStickHolder adoc
      if isMe stickholder
        # Relinquish the stick
        setStickHolder adoc, ""
        setExtensionState adoc,  "notmyturn"
      else if stickholder == ''
        # Stick is available. Takeit.
        setStickHolder adoc, myId()
        setExtensionState adoc, "myturn"
      else
        # Stick is held by another collaborator.
        setExtensionState adoc,  "notmyturn"
    else
      # Not an editable doc, show the stickholders
      # for all the docs I'm monitoring.
      showMonitoredDocInfo()
  
  changeHandler = (adoc) -&gt;
    # Called when a monitored doc is changed
    stickholder = getStickHolder adoc
    if stickholder == ''
      # Another collaborator has relinquished it
      # Let me know it's available
      setExtensionState adoc, "possiblymyturn"
  
  getActiveBrowserPage () -&gt;
    # TODO Use Chrome Extension API to return URL
    # of active tab.
    return null
  
  isEditableGDoc = (adoc) -&gt;
    # TODO Use Chrome Extension API and GDocs API
    # to find out if this is a GDoc to which
    # I have editing rights. Return true or false.
    return null
  
  addToMonitoredDocList = (adoc) -&gt;
    # TODO Use Extension and GDoc API's tp
    # set up a change notification listener
    # for this doc and add the doc url to a locally
    # stored list for persistence.
    return null
  
  
  getStickHolder = (adoc) -&gt;
    if hasMetaDataKey adoc, "StickHolder"
      return getMetaDataValue adoc, "StickHolder"
    else
      setMetaData adoc, "StickHolder", ''
      return ''
  
  isMe = (stickholder) -&gt;
    return stickholder = myID()
  
  myID = () -&gt;
    # TODO Use Extension API to get my UserID
    return null
  
  setExtensionState = (adoc, statestring) -&gt;
    states = ["myturn", "notmyturn", "possiblymyturn"]
    assert statestring in states, "#{statestring} is not a valid state"
    # TODO get present state from local storage,
    # compare to new state,
    # alert me if adoc haa changed availability.
    # save new state to local storage.
    return null
  
  
  hasMetaDataKey = (adoc, keystring) -&gt;
    # TODO Use GDoc API to check existence of
    # keystring in doc's metadata (aka Properties)
    # returns true or false
    return null
  
  getMetaDataValue = (adoc, keystring) -&gt;
    # TODO Use GDoc API to return value of doc metadata
    # associated with keystring
    return null
  
  showMonitoredDocInfo = () -&gt;
    # TODO Use Storage API to fetch list of all docs being monitored.
    # For each doc, look up current stickholder and present it to me
    # as a menu or page from which I can choose to claim an available doc.
    return null
  
  assert = (bool, msg) -&gt;
    if not bool
      throw new Error "Assertion Failed: " + msg
  </code></pre>