Uncategorized

Vanilla Extract

March 16, 2011   ·   By   ·   Comments Off   ·   Posted in Uncategorized

When I was thinking about the best option for community support for Dexy, I decided to take the forum route rather than the mailing list option. After much searching, I chose Vanilla Forums which was open source and seemed pleasant to interact with and sanely written. You can visit the Dexy forum at discuss.dexy.it.

Recently, since I had a question to answer and wanted to be able to do so using Dexy, I sat down to implement Dexy integration with Vanilla. As a result I developed two filters, one called ‘vanilla’ for starting a new discussion, and one called ‘vanillacomment’ for commenting on an existing discussion (i.e. answering a question).

Asking or answering questions is a natural use case for Dexy, as it involves explaining code. With Dexy you can easily include your example code in your question or reply, and also show how the code looks when run, which is great for explaining things and is also a great way to make sure you don’t have typos or other mistakes in your post. Hopefully it will also reinforce the practice to include a self-contained example when asking a question. Of course it’s totally optional to use Dexy, you can still ask or answer questions the old fashioned way!

To see what Dexy-generated Vanilla forum discussions look like check out this and this. If you want to try it out, then feel free to register and post to vanillasandbox.dexy.it. This is just a sandbox so contents will be deleted periodically. Of course if you want to ask (or answer) a Dexy question this works on the real Dexy forum too.

Setting Up Vanilla

If you want to enable Dexy integration with your own installation of Vanilla then you will need to install and activate the JSON API addon. (In fact you will need the latest version from github which contains a tweak.) If you want to have syntax highlighing for source code then you will need to modify the theme you are using to add a stylesheet for your syntax highlighter. (If you are using Pygments then here is how to generate a stylesheet.)

Using the Vanilla Filter

The authentication mechanism, for now, depends on you obtaining a login cookie from your browser. (If anyone knows PHP then writing a Vanilla authentication plugin to allow creating proper API keys would be very welcome.) Log in to the vanilla site you wish to access, then copy the text of the cookie named Vanilla. On Firefox 3 this is done by going into Tools → Page Info and clicking the View Cookies button on the Security tab.

You will want to use this cookie text to create a file named vanilla-config.json which should look like this:

{
"site" : "http://vanillasandbox.dexy.it/",
"user-cookie" : "1-1300456761%7C8cd51…"
}

If this cookie changes, you will need to update this config file. You will need separate config files for each forum you wish to post to. For now Dexy expects to find this config file in your Dexy project root, so this suggests having a separate Dexy project for each forum you wish to participate in.

For the moment, I don’t have support for ‘draft’ discussions/comments so you will want to write your content locally and then post it to vanilla when it’s ready. You can always revise it after posting it.

To start a new discussion, you need to create a discuss.json file like this

{"Name": "Posting to Vanilla API"}

which should be passed through the dummy ‘dexy’ filter and be passed as an input to the file which has the content you wish to post to the forum, for example, assuming you want to post the contents of “discuss.html” to the forum, your .dexy file might include:

"discuss.html|jinja|vanilla" : {
  "inputs" : ["discuss.json|dexy"]
}

After you have posted your new discussion, Dexy will add the DiscussionID to your discuss.json config file, so if you run Dexy again the existing discussion will be updated. You can also specify the DiscussionID of an existing discussion yourself.

{"DiscussionID": 1, "Name": "Posting to Vanilla API"}

To comment on an existing discussion, you use the ‘vanillacomment’ filter, and you need to specify the DiscussionID which the comment relates to in a file called comment.json, for example:

{"DiscussionID": 1}

Again, the CommentID will be added after it has been created, or you can specify it yourself if you want to modify an existing comment:

{"CommentID": "1", "DiscussionID": 1}

Again, this JSON file should be passed through the dummy ‘dexy’ filter and passed as an input to the file containing the comment text, e.g. your .dexy file might include:

"comment.html|jinja|vanillacomment" : {
  "inputs" : ["comment.json|dexy"]
}

Here is the .dexy file I actually used:

{
  "discuss.html|jinja|vanilla" : {
    "allinputs" : true
  },
  "comment.html|jinja|vanillacomment" : {
    "inputs" : ["comment.json|dexy", "discuss.html|pyg"]
  },
  "*.json|dexy" : {},
  "*.py|pyg" : {}
}

As an example, I have posted the original python script I wrote to connect with the Vanilla API. You can see this here.

I can think of a number of features I want to add to this to make the interface simpler and easier, so please check the filter documentation for updates in case the interface has changed. Happy posting!