Mailspring/docs/ComposerExtensions.md
Ben Gotow 466bca813b fix(syncback): Bidirectional transforms, ready-to-send saved state
Summary:
This diff replaces "finalizeSessionBeforeSending" with a
plugin hook that is bidirectional and allows us to put the draft in
the "ready to send" state every time we save it, and restore it to
the "ready to edit" state every time a draft session is created to
edit it.

This diff also significantly restructures the draft tasks:

1. SyncbackDraftUploadsTask:
   - ensures that `uploads` are converted to `files` and that any
     existing files on the draft are part of the correct account.

1. SyncbackDraftTask:
   - saves the draft, nothing else.

3. SendDraftTask
   - sends the draft, nothing else.
   - deletes the entire uploads directory for the draft

Test Plan: WIP

Reviewers: juan, evan

Reviewed By: evan

Differential Revision: https://phab.nylas.com/D2753
2016-03-16 19:27:12 -07:00

1.6 KiB

Title Section Order
Extending the Composer Guides 6

The composer lies at the heart of N1, and many improvements to the mail experience require deep integration with the composer. To enable these sort of plugins, the {DraftStore} exposes an extension API.

This API allows your package to:

  • Display warning messages before a draft is sent. (ie: "Are you sure you want to send this without attaching a file?")

  • Intercept keyboard and mouse events to the composer's text editor.

  • Transform the draft and make additional changes before it is sent.

To create your own composer extensions, subclass {ComposerExtension} and override the methods your extension needs.

In the sample packages repository, templates is an example of a package which uses a ComposerExtension to enhance the composer experience.

Example

This extension displays a warning before sending a draft that contains the names of competitors' products. If the user proceeds to send the draft containing the words, it appends a disclaimer.

{ComposerExtension} = require 'nylas-exports'

class ProductsExtension extends ComposerExtension

   @warningsForSending: ({draft}) ->
      words = ['acme', 'anvil', 'tunnel', 'rocket', 'dynamite']
      body = draft.body.toLowercase()
      for word in words
        if body.indexOf(word) > 0
        	return ["with the word '#{word}'?"]
	  return []

   @applyTransformsToDraft: ({draft}) ->
    if @warningsForSending({draft})
      updated = draft.clone()
      updated.body += "<br>This email \
       	contains competitor's product names \
      	or trademarks used in context."
      return updated
    return draft