My Org Elisp webservice

originally published in September 2014

During the last months I spent a lot of time using Emacs, growing more and more fond of it. The main responsible for that is certainly org-mode, one of Emacs' killer applications. I progressively switched to org-mode for almost everything: taking notes, todo lists and agenda, keeping a journal, and so on.

One missing part of my setup, compared to what I've been using earlier, is the capability to take notes with my mobile phone. There's MobileOrg, but so far my attempts to obtain a working setup have failed. I eventually decided to write my own very simple version.

I have basic needs: just a form that allows me to enter the description of a task I need to perform. I want this scrap of text to be appended in a special org file that I can later manage when I'm at my desk, moving it in the org file where it belongs.

My initial intention was to write (probably in Perl) a very simple web app showing an input box to the user, then just appends what the user wrote to a particular file (let's say mobile-notes.org). This particular file would then be synced with other machines using Dropbox, which is already running -as Emacs does- on my remote servers.

It could certainly work, but I wanted something more, for example being able to apply tags or todo keywords directly, using the configuration I wrote for org-mode. I need a way to make Emacs talk to the outer world, precisely a way to pass informations to a web application. Being Emacs, the question is not "Can I do it?", but "How can I do it?".

It turns out, as I expected, that Emacs has a web server package that I can exploit for my needs: Elnode.

I started for a personal need, but I'm sharing it in case someone can actually find it useful. Moreover, as it's my first Emacs Lisp project (I knew that point was bound to happen) I can't rule out the possibility I'm violating some best practices: comments and critiques are most welcome!

First, a little bit of configuration:

(defvar moew:org-dir "/home/larsen/Dropbox/org")
(defvar moew:org-filename "mobile-notes.org")
(defvar moew:port 8002)

And a utility function to return the absolute filename for the Org file where the app saves the new items.

(defun moew:org-complete-filename ()
  (format "%s/%s" moew:org-dir moew:org-filename))

Here comes the interesting part, the definition for the dispatch table that maps URIs to function names. httpcon is the name of a variable containing a data structure with the HTTP connection details. Here is used so that elnode-hostpath-dispatcher can read the path.

(defun moew:main-handler (httpcon)
  (elnode-hostpath-dispatcher
     httpcon
     `(("^.*//form"     . moew:form)
       ("^.*//keywords" . moew:keywords)
       ("^.*//save"     . moew:save))))

moew:form simply serve a static html file (you can find the complete source in the github project for moew).

(defun moew:form (httpcon)
  (elnode-http-start httpcon 200 '("Content-type" . "text/html"))
  (elnode-send-file httpcon "form.html"))

moew:keywords is slightly more interesting. It serves (in JSON, thanks to json-encode, a function in the json package) a representation of the particular org-todo-keywords sequence.

(defun moew:keywords (httpcon)
  (elnode-send-json httpcon
                    (json-encode (cdr (car org-todo-keywords)))))

And the most important function. I use elnode-http-param on httpcon to fetch the params coming from the form, then I pass them to the function that produces the actual line that is appended (append-to-file) to the org file configured before. Eventually, a respose message is sent to the client.

(defun moew:save (httpcon)
  (let ((todo-item-body (elnode-http-param httpcon "text"))
        (todo-item-keyword (elnode-http-param httpcon "keyword")))
    (append-to-file 
     (moew:todo-item-complete-text todo-item-keyword todo-item-body)
     nil (moew:org-complete-filename))
    (elnode-send-json httpcon (json-encode "ok"))))