Actions

Summary

In the Flux Application Architecture, almost every user action is translated into an Action object and fired globally. Stores in the app observe these actions and perform business logic. This loose coupling means that your packages can observe actions and perform additional logic, or fire actions which the rest of the app will handle.

In Reflux, each {Action} is an independent object that acts as an event emitter. You can listen to an Action, or invoke it as a function to fire it.

Action Scopes

Nylas Mail is a multi-window application. The scope of an Action dictates how it propogates between windows.

  • Global: These actions can be listened to from any window and fired from any window. The action is sent from the originating window to all other windows via IPC, so they should be used with care. Firing this action from anywhere will cause all listeners in all windows to fire.
  • Main Window: You can fire these actions in any window. They'll be sent to the main window and triggered there.
  • Window: These actions only trigger listeners in the window they're fired in.

Firing Actions

Actions.postNotification({message: "Archived Thread", type: 'success'})

Actions.queueTask(new ChangeStarredTask(thread: @_thread, starred: true))

Listening for Actions

If you're using Reflux to create your own Store, you can use the listenTo convenience method to listen for an Action. If you're creating your own class that is not a Store, you can still use the listen method provided by Reflux:

setup: ->
  @unlisten = Actions.didPassivelyReceiveNewModels.listen(@onNewMailReceived, @)

onNewMailReceived: (data) ->
  console.log("You've got mail!", data)

teardown: ->
  @unlisten()

Class Properties

didPassivelyReceiveNewModels

Fired when the Nylas API Connector receives new data from the API.

Scope: Global

Receives an Object of Arrays of Models, for example:

{
        'thread': [<Thread>, <Thread>]
        'contact': [<Contact>]
      }

logout

Log out the current user. Closes the main application window and takes the user back to the sign-in window.

Scope: Global

queueTask

Queue a Task object to the TaskQueue.

Scope: Work Window

dequeueAllTasks

Dequeue all Tasks from the TaskQueue. Use with care.

Scope: Work Window

dequeueMatchingTask

Dequeue a Task matching the description provided.

Scope: Work Window

retryInitialSync

Retry the initial sync

Scope: Work Window

showDeveloperConsole

Show the developer console for the current window.

Scope: Window

registerPreferencesTab

Register a preferences tab, usually applied in Preferences window

Scope: Window

clearDeveloperConsole

Clear the developer console for the current window.

Scope: Window

selectAccountId

Select the provided account ID in the current window.

Scope: Window

selectRootSheet

Select the provided sheet in the current window. This action changes the top level sheet.

Scope: Window

Actions.selectRootSheet(WorkspaceStore.Sheet.Threads)

toggleWorkspaceLocationHidden

Toggle whether a particular column is visible. Call this action with one of the Sheet location constants:

Actions.toggleWorkspaceLocationHidden(WorkspaceStore.Location.MessageListSidebar)

setCursorPosition

Focus the keyboard on an item in a collection. This action moves the keyboard focus element in lists and other components, but does not change the focused DOM element.

Scope: Window

Actions.setCursorPosition(collection: 'thread', item: <Thread>)

setFocus

Focus on an item in a collection. This action changes the selection in lists and other components, but does not change the focused DOM element.

Scope: Window

Actions.setFocus(collection: 'thread', item: <Thread>)

focusMailView

Focus the interface on a specific {Category}.

Scope: Window

Actions.focusMailView(<Category>)

toggleMessageIdExpanded

If the message with the provided id is currently beign displayed in the thread view, this action toggles whether it's full content or snippet is shown.

Scope: Window

message = <Message>
      Actions.toggleMessageIdExpanded(message.id)

composeReply

Create a new reply to the provided threadId and messageId. Note that this action does not focus on the thread, so you may not be able to see the new draft unless you also call setFocus.

Scope: Window

# Compose a reply to the last message in the thread
      Actions.composeReply({threadId: '123'})
      
      # Compose a reply to a specific message in the thread
      Actions.composeReply({threadId: '123', messageId: '123'})

composeForward

Create a new draft for forwarding the provided threadId and messageId. See composeReply for parameters and behavior.

Scope: Window

composeReplyAll

Create a new draft and "reply all" to the provided threadId and messageId. See composeReply for parameters and behavior.

Scope: Window

composePopoutDraft

Pop out the draft with the provided ID so the user can edit it in another window.

Scope: Window

messageId = '123'
      Actions.composePopoutDraft(messageId)

composeNewBlankDraft

Open a new composer window for creating a new draft from scratch.

Scope: Window

Actions.composeNewBlankDraft()

sendDraft

Send the draft with the given ID. This Action is handled by the DraftStore, which finalizes the DraftChangeSet and allows DraftStoreExtensions to display warnings and do post-processing. To change send behavior, you should consider using one of these objects rather than listening for the {sendDraft} action.

Scope: Window

Actions.sendDraft('123')

destroyDraft

Destroys the draft with the given ID. This Action is handled by the DraftStore, and does not display any confirmation UI.

Scope: Window

archive

Archive the currently focused Thread.

Scope: Window

archiveSelection

Archives the Thread objects currently selected in the app's main thread list.

Scope: Window

searchQueryChanged

Updates the search query in the app's main search bar with the provided query text.

Scope: Window

Actions.searchQueryChanged("New Search Query")

searchQueryCommitted

Submits a search with the provided query text. Unlike searchQueryChanged, this action immediately performs a search.

Scope: Window

Actions.searchQueryCommitted("New Search Query")

RSVPEvent

Submits the user's response to an RSVP event.

Scope: Window

postNotification

Fire to display an in-window notification to the user in the app's standard notification interface.

Scope: Window

# A simple notification
      Actions.postNotification({message: "Archived Thread", type: 'success'})
      
      # A sticky notification with actions
      NOTIF_ACTION_YES = 'YES'
      NOTIF_ACTION_NO = 'NO'
      
      Actions.postNotification
        type: 'info',
        sticky: true
        message: "Thanks for trying out Nylas Mail! Would you like to make it your default mail client?",
        icon: 'fa-inbox',
        actions: [{
          label: 'Yes'
          id: NOTIF_ACTION_YES
        },{
          label: 'Not Now'
          id: NOTIF_ACTION_NO
        }]

notificationActionTaken

Listen to this action to handle user interaction with notifications you published via postNotification.

Scope: Window

@_unlisten = Actions.notificationActionTaken.listen(@_onActionTaken, @)
      
      _onActionTaken: ({notification, action}) ->
        if action.id is NOTIF_ACTION_YES
          # perform action

removeFile

Remove a file from a draft.

Scope: Window

Actions.removeFile
        file: fileObject
        messageClientId: draftClientId

popSheet

Pop the current sheet off the Sheet stack maintained by the WorkspaceStore. This action has no effect if the window is currently showing a root sheet.

Scope: Window

pushSheet

Push a sheet of a specific type onto the Sheet stack maintained by the WorkspaceStore. Note that sheets have no state. To show a specific thread, you should push a Thread sheet and call setFocus to select the thread.

Scope: Window

WorkspaceStore.defineSheet 'Thread', {},
          list: ['MessageList', 'MessageListSidebar']
      
      ...
      
      @pushSheet(WorkspaceStore.Sheet.Thread)