You are looking at historical revision 18661 of this page. It may differ significantly from its current revision.

chickadee

chickadee is a web interface to chicken-doc.

Interface

[procedure] (chickadee-start-server)

Start the Chickadee server. Server configuration is done via parameters and, as spiffy is used as the backend webserver, all of its configuration options also apply.

Configuration

[parameter] chickadee-uri

Main access URI to Chickadee for users, as a URI object.

Defaults to (uri-reference "/chickadee"), so that the node foreign types is accessible at /chickadee/foreign/types.

[parameter] cdoc-uri

Internal URI for Chickadee, used to perform path and identifier lookup and searches.

Although you can choose to make cdoc-uri a child of chickadee-uri, keep in mind it may conflict with an existing node name.

Defaults to (uri-reference "/cdoc").

[parameter] incremental-search-uri

URI used to provide incremental search capability. This URI is arbitrary, but is typically a child of cdoc-uri. Due to AJAX limitations it must inhabit the same domain name as chickadee-uri.

Defaults to (uri-reference "/cdoc/ajax/prefix").

[parameter] chickadee-css-files

List of URIs to CSS files for Chickadee.

Defaults to (list (uri-reference "/cdoc/chickadee.css").

[parameter] chickadee-js-files

List of URIs to Javascript files for Chickadee.

Defaults to (list (uri-reference "/cdoc/chickadee.js").

[parameter] maximum-match-results

Maximum number of match results to return for a match query. Default: 250.

[parameter] maximum-match-signatures

Maximum number of signatures to return for a match query, up to maximum-match-results. Default: 100. Obtaining signatures may increase disk load in the current implementation.

[parameter] incremental-search

Number of incremental search results to display; 0 or #f to disable. Defaults to 0.

[parameter] incremental-search-delay

Time in milliseconds to delay incremental search requests. Defaults to 50, which seems reasonable for WAN or LAN use. 20 will give even better interactive response on a fast network and CPU.

[parameter] cache-nodes-for

Time in milliseconds to inform browsers that node pages should be cached for. Defaults to 300. If #f, no caching is done.

[parameter] cache-static-content-for

Time in milliseconds to inform browsers that static content such as CSS and Javascript should be cached for.

[parameter] last-modified

Base time used for node last-modified calculations, in seconds.

Chickadee uses the overall repository modification time (updated whenever a reindex is done) to determine when a node was last modified. Browsers with a vaild cached copy will receive a "304 Not Modified" response.

However, the value of last-modified will also be considered; the modification time is taken as the maximum of the two values. This is done because changes to program logic may change the rendering of the page even when the repository has not changed. For example, set last-modified to (current-seconds) to simply invalidate all pages when the server is restarted.

Defaults to 0.

[parameter] ajax-log

AJAX access log pathname. Separate from the usual access-log because this is potentially disk and CPU intensive. Set to #f to disable.

Debugging

[parameter] %chickadee:debug-incremental-search-latency

Simulate network latency of N milliseconds for incremental search. Allows you to test estimated interactive response across the Internet on a local system.

Examples

An example local configuration.

;; chickadee-driver.scm
(use chickadee spiffy uri-common)
(define uri uri-reference)
(root-path "./root")
(debug-log (current-error-port))
(server-port 8080)
(access-log "access.log")
(max-connections 8)
(ajax-log "/tmp/ajax.log")
(cdoc-uri (uri "/cdoc"))
(chickadee-uri (uri "/chickadee"))
(incremental-search-uri (uri "/cdoc/ajax/prefix"))
(chickadee-css-files (list (uri "/cdoc/chickadee.css")))
(chickadee-js-files
 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
       (uri "/cdoc/jquery.metadata.2.1.min.js")
       (uri "/cdoc/chickadee-jquery.js")))
(maximum-match-results 250)
(maximum-match-signatures 100)
(incremental-search 15)
(incremental-search-delay 50)
(cache-nodes-for 300)
(cache-static-content-for 1800)
(last-modified (current-seconds))
(chickadee-start-server)

Configuration of primary chickadee server running on 3e8.org behind an nginx caching proxy.

;; chickadee-driver-3e8.scm
(use chickadee spiffy uri-common)
(define uri uri-reference)
(root-path "./root")
(debug-log (current-error-port))
(access-log "access.log")
(error-log "error.log")
(server-port 8383)
(max-connections 8)
(ajax-log #f)
(cdoc-uri (uri "/cdoc"))
(chickadee-uri (uri "/chickadee"))
(incremental-search-uri (uri "/cdoc/ajax/prefix"))
(chickadee-css-files (list (uri "/cdoc/chickadee.css?5")))
(chickadee-js-files
 (list (uri "http://code.jquery.com/jquery-1.4.2.min.js")
       (uri "/cdoc/jquery.metadata.2.1.min.js")
       (uri "/cdoc/chickadee-jquery.js?2")))
(maximum-match-results 250)
(maximum-match-signatures 100)
(incremental-search 15)
(incremental-search-delay 50)
(cache-nodes-for 600)
(cache-static-content-for 1800)
(last-modified (current-seconds))
(chickadee-start-server)

Both of these configurations are available in the SVN and git repositories.

Installation

Installation is unfortunately still manual. Installing the egg does not currently install any static CSS, JS or image files (this is a bug). Instead, download the egg contents to obtain them along with the example configurations. Running install.sh will then install them into ./root/cdoc which is their default configured location.

For example:

$ chicken-install -r chickadee
$ cd chickadee
$ chicken-install -n        # -n optional; skips global install
$ sh install.sh
$ csi -script chickadee-driver.scm

will start a server on port 8080 using your global chicken-doc repository.

git repository

The official code is part of the Chicken SVN repository, but the author's git repository is available at http://3e8.org/pub/git/chickadee.git/.

Author

Jim Ursetto

Version history

0.9.0

Initial release.

License

Copyright (c) 2010 Jim Ursetto. BSD-licensed.