docs » UniversalArchive

Handle "archive current item" for multiple applications using the same hotkey

Download: https://github.com/Hammerspoon/Spoons/raw/master/Spoons/UniversalArchive.spoon.zip

Using this Spoon enables you to use a single hotkey to archive an item in multiple applications. Out of the box the following applications are supported: Evernote, Mail, Spark and Outlook. You can easily register handlers for new applications (or override the built-in ones) using the registerApplication() method. If you write a new handler and feel others could benefit from it, please submit a pull request!

Handlers can also provide support for archiving to multiple locations, and you can bind different hotkeys for each destination. At the moment only Evernote supports this. See the documentation for bindHotkeys() for the details on how to specify multiple-destination filing hotkeys.

API Overview

API Documentation

Variables

archive_notifications
Signature UniversalArchive.archive_notifications
Type Variable
Description

Boolean indicating whether a notification should be produced when an item is archived. Defaults to "true".

Source Source/UniversalArchive.spoon/init.lua line 46
evernote_archive_notebook
Signature UniversalArchive.evernote_archive_notebook
Type Variable
Description

Name of the Notebook to use for archiving in Evernote. Defaults to "Archive"

Source Source/UniversalArchive.spoon/init.lua line 36
evernote_delay_before_typing
Signature UniversalArchive.evernote_delay_before_typing
Type Variable
Description

A short pause to make typing into Evernote more reliable

Notes
  • In Evernote, archive is done by selectin "Move note" and then simulating typing of the notebook name. A short pause in between makes it more reliable for Evernote to recognize the notebook name correctly.
  • This variable controls how much to wait, in seconds.
  • Do not change this unless you know what you are doing
Source Source/UniversalArchive.spoon/init.lua line 51
logger
Signature UniversalArchive.logger
Type Variable
Description

Logger object used within the Spoon. Can be accessed to set the default log level for the messages coming from the Spoon.

Source Source/UniversalArchive.spoon/init.lua line 31
outlook_archive_folder
Signature UniversalArchive.outlook_archive_folder
Type Variable
Description

Name of the mailbox to use for archiving in Outlook. You must move a message manually to that mailbox at least once so that it appears in the "Message" -> "Move..." submenu. Defaults to "Archive"

Source Source/UniversalArchive.spoon/init.lua line 41

Methods

bindHotkeys
Signature UniversalArchive:bindHotkeys(mapping)
Type Method
Description

Binds hotkeys for UniversalArchive

Parameters
  • mapping - A table containing hotkey modifier/key details for the following items:
    • archive - hotkey for trigger the universalArchive() method, to archive the current item on the current application.
    • <app>_<dest> - if an application handler supports multiple destinations, you can specify hotkeys for specific destinations using this format. For example, to assign a hotkey that files the current note in Evernote to the "MyProject" notebook using Ctrl-Alt-Cmd-M, you would specify Evernote_MyProject = { { "ctrl", "alt", "cmd" }, "m" } as one of the elements of mapping. Keep in mind that the application name must appear exactly as the system sees it (including upper/lowercase), and that if either the application or the destination name contain spaces or other non-alphanumeric characters, you need to use the Lua table notation. For example: ["Evernote_Some Long Notebook Name"] = { keybinding }. At the moment only the Evernote handler supports multiple destinations.
Returns
Source Source/UniversalArchive.spoon/init.lua line 183
evernoteArchive
Signature UniversalArchive:evernoteArchive(where)
Type Method
Description

Archive current note in Evernote.

Parameters
  • where - destination notebook. Defaults to the value of UniversalArchive.evernote_archive_notebook.
Returns
Source Source/UniversalArchive.spoon/init.lua line 61
mailArchive
Signature UniversalArchive:mailArchive()
Type Method
Description

Archive current message in Mail using the built-in Archive functionality

Parameters
  • none
Returns
Source Source/UniversalArchive.spoon/init.lua line 85
outlookArchive
Signature UniversalArchive:outlookArchive()
Type Method
Description

Archive current message in Outlook using one of two methods:

Parameters
  • none
Returns
Notes
  • If the "Message -> Archive" menu item exists, it is used (this has been added in recent versions of Outlook)
  • Otherwise, the message gets manually moved to the folder specified in UniversalArchive.outlook_archive_folder. The folder has to appear in the Message -> Move submenu for this to work. Since this submenu only lists the last few destination folders, you have to move a message by hand the first time (or periodically if you don't archive very often).
Source Source/UniversalArchive.spoon/init.lua line 121
registerApplication
Signature UniversalArchive:registerApplication(appname, fn)
Type Method
Description

Register a handler function for an application.

Parameters
  • appname - string containing the name of the application. If the application already has a handler, it will be replaced with the new one.
  • fn - handler function (to remove the handler for an application, use nil). The function receives the following arguments:
    • self - the UniversalArchive object, so the handler can make use of all the object methods and variables.
    • where - optional "destination" for the archive operation. Handlers must provide a default destination when where == nil. Destination doesn't make sense for all applications, so the implementation of this is optional and depending on the handler.
Returns
Source Source/UniversalArchive.spoon/init.lua line 166
sparkArchive
Signature UniversalArchive:sparkArchive()
Type Method
Description

Archive current message in Spark using the built-in Archive functionality

Parameters
  • none
Returns
Source Source/UniversalArchive.spoon/init.lua line 103
universalArchive
Signature UniversalArchive:universalArchive(where)
Type Method
Description

Main entry point for archiving an item.

Parameters
  • None
Returns
Notes
  • If a handler function is defined for the current application, it is called with the UniversalArchive object as its first argument, and the archive destination (if provided) as the second.
  • Handlers must have a "default destination" that gets used when no destination is provided. Not all handlers support specifying a destination. New handlers can be registered using the registerApplication() method.
Source Source/UniversalArchive.spoon/init.lua line 143