VoodooPad and TextMate

VoodooPad's new HTML-savvy application-specific URLs are a great way to retrace your steps in TextMate.

I keep my worklog in VoodooPad. I do most of my code editing in TextMate. When I'm trying to understand a new chunk of code, I often need to jump around through the code base.

It's hard to keep track of where I've been, so I can back out of a code path once I understand what it does. Until now I've just jotted down pathnames and line numbers in my worklog, so I could manually retrace my steps.

Puzzle Pieces

• VoodooPad URLs. They let you inject HTML content — including hyperlinks — into an open VoodooPad document.
• TextMate URLs of the form txmt://open?url=file://pathname&line=lineNum;column=colNum. Open one of these URLs and TextMate will open a window showing the specified line (and column, if specified) of the specified file.
• Textmate commands and key equivalents.
  TextMate lets you define custom commands and trigger them with keyboard shortcuts that you specify.

Put these all together and what do you get?

Scenario

• Select some code of interest in TextMate
• Type your keyboard shortcut
• A hyperlink pointing to the selected code is inserted into your VoodooPad document

Later, when you want to get back to that chunk of code, just click on the hyperlink in VoodooPad. TextMate will open the document and jump to the line of code referenced by the hyperlink.

Granted, you're probably going to edit that code someday; and then your bookmarks will break. But this is a handy way to leave a trail of breadcrumbs while you're trying to decipher a new body of code.

Code

Here's a Python script which implements this "Bookmark in VoodooPad" capability in TextMate. You can use it by opening TextMate's Bundle Editor (Bundles -> Bundle Editor -> Show Bundle Editor), creating a New Command using the tool menu at the bottom left of the Bundle Editor window, and pasting it into the resulting Command(s) text area:

#!/usr/bin/env python2.6
import os, datetime, urllib, subprocess

escape = urllib.quote

# What Textmate location are we bookmarking?
path = os.environ["TM_FILEPATH"]
lineNum = os.environ["TM_LINE_NUMBER"]
_tmURLTemplate = """txmt://open?url=file://{path}&line={lineNum}"""
tmURL = _tmURLTemplate.format(path=path, lineNum=lineNum)

# Which VoodooPad worklog page should we add it to?
vpPageName = escape(datetime.date.today().strftime("%Y-%m-%d"))

# What text should Voodoopad show for the link?
currLine = os.environ.get("TM_SELECTED_TEXT", os.environ["TM_CURRENT_LINE"])

# How should the HTML be formatted?
_vpHTMLTemplate = '''<a style="font:12px helvetica" href="{tmURL}">{currLine}</a>'''
vpMarkup = _vpHTMLTemplate.format(tmURL=tmURL, currLine=currLine)

# What URL do we open to inject the HTML into VoodooPad?
_vpURLTemplate = """voodoopad:html={vpMarkup}&page={vpPageName}"""
vpURL = _vpURLTemplate.format(vpMarkup=escape(vpMarkup), vpPageName=escape(vpPageName))

subprocess.check_call(["open", vpURL])

Specify a key equivalent such as ⌘-T (Command-T) and you're off to the races.

VoodooPad bookmarklets now support HTML

VoodooPad bookmarklets are very useful. But they let you paste only plaintext from your web browser into your document — until now.

VoodooPad Application URLs

VoodooPad understands application-specific URLs of the form voodoopad:description=encoded_text&page=name_of_VoodooPad_document_page. When you open one of these URLs, VoodooPad inserts the encoded text into the indicated page of the current VP document.

You can open voodoopad: URLs from other applications, such as a web browser. That's what's so cool about VP bookmarklets -- they let you quickly select some text in your web browser and paste it into a VP document, along with other information such as the URL where the text originated.

The only problem is, the description parameter can contain only plain text. So if you've selected part of a web page that contains hyperlinks, those hyperlinks won't come along for the ride.

New Feature

Gus Mueller, VoodooPad's creator, recently released a new build. It adds a new html parameter to VoodooPad URLs. Now you can select part of a web page and transfer it as HTML into your VoodooPad document.

Gus summarized the new feature thus:

The format of the bookmarklet is like so:
voodoopad:page=junk&html=<b>hello</b>%20world!

Here's expanded code for a JavaScript bookmarklet which takes advantage of the new parameter. It works in both Safari and Firefox 3.0.x:

javascript: function pad(v) {
    var res=String(v);while(res.length<2) {
        res='0'+res;
    }
    return res;
};
var d=new Date();
var page=(String(d.getFullYear())+'-'+
          pad(d.getMonth()+1)+'-'+ pad(d.getDate()));
function selHTML() {
    var wr=document.createElement('div');
    var c=window.getSelection().getRangeAt(0).cloneContents();
    wr.appendChild(c);
    return wr.innerHTML;
};
location.href='voodoopad:html='+encodeURIComponent('<div style="font:12px helvetica">'+location.href+'<br/>"""<br/>'+selHTML()+'<br/>"""</div><br/>')+'&page='+page;

Worth noting: in this snippet the html content is wrapped up in a div which has an explicit font specification. The bookmarklet is transferring a chunk of HTML, but that chunk doesn't include any of the CSS from the original web page. So if you don't specify a style for the wrapper div, VoodooPad will use its own default style for the current VP page. (I think that's something like Times Roman 10px.)

VoodooPad Bookmarklets

VoodooPad bookmarklets make it easy to log search results.

I keep a worklog in VoodooPad. Notes for each day are stored in a page with a name of the form 'yyyy-mm-dd'.

When I'm searching for info on the web, I like to include relevant results in my worklog. I tend to record results in this format, to make it easier to find the results again in future:

http://url.of.interest/:
"""
Excerpt
"""

It's tedious to format these excerpts. At least two visits to the browser application are needed:

1. Copy the URL
2. Copy the text of interest

Luckily VoodooPad supports application-specific URLs, and you can create JavaScript bookmarklets to open such a URL, with the URL and any selected text for the page you're currently viewing.

Here's an almost human-readable example of a bookmarklet which adds an excerpt from the current web page, formatted as above, to the current worklog page in VoodooPad.

javascript:
var d = new Date();
var padded = function(v) {
    var res = v.toString();
    while (res.length < 2) {
        res = '0' + res;
    }
    return res;
};
var page = [
    String(d.getFullYear()), 
    padded(d.getMonth() + 1),
    padded(d.getDate())
].join("-");
location.href = ('voodoopad:description=' + 
                 encodeURIComponent(location.href + '\n"""\n' + 
                                    window.getSelection().toString() + 
                                    '\n"""\n') +
                 '&page=' + page);

Here's the same bookmarklet formatted for inclusion in your browser's menubar:

javascript:var%20d=new%20Date();var%20padded=function(v)%20{%20var%20res%20=%20v.toString();while%20(res.length%20<%202)%20{res%20=%20'0'%20+%20res;}%20return%20res;};var%20page%20=%20[String(d.getFullYear()),%20padded(d.getMonth()%20+%201),%20padded(d.getDate())].join('-');location.href='voodoopad:description='+encodeURIComponent(location.href+'\n"""\n'+window.getSelection().toString()+'\n"""\n')+'&page='+page;