docs/plugin-api.md (2944 bytes)
1 # General Use 2 3 1. A lisp file should be created in coleslaw's ```plugins``` directory or the local `plugins` directory of the blog. 4 2. Any necessary lisp libraries not loaded by coleslaw should be included like so: 5 6 ```(eval-when (:compile-toplevel :load-toplevel) (ql:quickload '(foo bar)))``` 7 8 3. A package should be created for the plugin code like so: 9 10 ```(defpackage :coleslaw-$NAME (:use :cl) (:export #:enable) ...)``` 11 12 where $NAME is the pathname-name of the lisp file. (eg. `:coleslaw-disqus` for `disqus.lisp`) 13 4. An enable function should be present even if it's a no-op. Any work to enable the plugin is done there. 14 15 16 # Extension Points 17 18 * **New functionality via JS**, for example the Disqus and Mathjax plugins. 19 In this case, the plugin's `enable` function should call 20 [`add-injection`](http://redlinernotes.com/docs/coleslaw.html#add-injection_func) 21 with an injection and a keyword. The injection is a function that takes a 22 *Document* and returns a string to insert in the page or nil. 23 The keyword specifies whether the injected text goes in the HEAD or BODY element. The 24 [Disqus plugin](http://github.com/redline6561/coleslaw/blob/master/plugins/disqus.lisp) 25 is a good example of this. 26 27 * **New markup formats**, for example the 28 [ReStructuredText plugin](http://github.com/redline6561/coleslaw/blob/master/plugins/rst.lisp), 29 can be created by definining an appropriate `render-text` 30 method. The method takes `text` and `format` arguments and is 31 [EQL-specialized](http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html#defmethod) 32 on the format. Format should be a keyword matching the file 33 extension (or `pathname-type`) of the markup format. 34 (eg. `:rst` for ReStructuredText) 35 36 * **New hosting options**, for example the 37 [Amazon S3 plugin](http://github.com/redline6561/coleslaw/blob/master/plugins/s3.lisp), 38 can be created by definining a `deploy :after` method. The method 39 takes a staging directory, likely uninteresting in the `:after` 40 stage. But by importing `*config*` from the coleslaw package and 41 getting its deploy location with `(deploy-dir *config*)` a number of 42 interesting options become possible. 43 44 * **New content types**, for example the 45 [static page content type](http://github.com/redline6561/coleslaw/blob/master/plugins/static-pages.lisp), 46 can be created by definining a subclass of CONTENT along with a 47 template, and `render`, `page-url`, and `publish` methods. 48 The PAGE content type cheats a bit by reusing the existing POST template. 49 50 * **New service integrations**, for example crossposting to 51 twitter/facebook/tumblr/livejournal/etc, is also possible by 52 adding an :after hook to the deploy method. The hook can iterate 53 over the results of the `get-updated-files` to crosspost any new content. 54 The [Twitter plugin](https://github.com/redline6561/coleslaw/blob/master/plugins/twitter.lisp) 55 is a good example of this.