Mercurial > hg > commentator
comparison README.txt @ 0:1c95a3fa76c1
initial commit of commentator
author | k0s <k0scist@gmail.com> |
---|---|
date | Sun, 24 Jan 2010 17:39:05 -0500 |
parents | |
children | 872f98a484d2 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:1c95a3fa76c1 |
---|---|
1 commentator | |
2 =========== | |
3 | |
4 WSGI commenting middleware | |
5 | |
6 To use | |
7 ------ | |
8 | |
9 Make a factory wrapping your app in the commentator middleware. | |
10 Currently, commentator only pickles comments. To the constructor of | |
11 Commentator, pass a database (the path to the pickle) and a pattern. | |
12 The pattern is in the form of | |
13 | |
14 <URL pattern>#<xpath pattern> -> URL | |
15 | |
16 The URL pattern is a | |
17 `python regular expression <ttp://docs.python.org/library/re.html>`_ | |
18 to match against the request's PATH_INFO. | |
19 | |
20 The xpath pattern is where you want to place the comments on the | |
21 page. See http://www.w3schools.com/XPath/ for more about xpath | |
22 expressions. | |
23 | |
24 The URL is a | |
25 `python string template <http://docs.python.org/library/string.html>`_ | |
26 that is substituted for groups in the URL regular expression and | |
27 element attributes in the found nodes. The element attributes are | |
28 referenced by name (``${id}``, ``${class}``, etc) and the groups are | |
29 referenced by number (``${1}``, ...). | |
30 | |
31 | |
32 Example | |
33 ------- | |
34 | |
35 A reference implementation is illustrated in the commentator.ini | |
36 file. This uses the pattern: | |
37 | |
38 ``commentator.pattern = (.*)#.//div[@id='comment_on_this'] -> ${1}`` | |
39 | |
40 What this pattern says is | |
41 | |
42 * comment on every PATH_INFO ``(.*)`` | |
43 * append the rendered content template to ``div[@id='comment_on_this']`` | |
44 * reference the PATH_INFO as the canonical URL ``${1}`` | |
45 | |
46 To comment on every HTML page at the end of the body, you would use | |
47 | |
48 ``commentator.pattern = (.*)#.//body -> ${1}`` | |
49 | |
50 A more complex example is in the ``.ini`` file, commented out, for use with | |
51 `bitsyblog <http://k0s.org/hg/bitsyblog>`_ : | |
52 | |
53 ``commentator.pattern = /blog/.*#.//div[@class='blog-entry'] -> /blog/${id}`` | |
54 | |
55 This pattern says: | |
56 | |
57 * comment on all paths under blog | |
58 * put the comments at the end of each ``div[@class='blog-entry']`` | |
59 * get the URI from the ``div``'s id, not from the ``PATH_INFO`` | |
60 | |
61 | |
62 TODO | |
63 ---- | |
64 | |
65 This is very alpha. I'd be happy to work more on this if anyone wants | |
66 it. A few outstanding issues: | |
67 | |
68 * fix weird lxml issue where you have to put .// for elements | |
69 * allow commenting on multiple resources (multiple patterns per instance) | |
70 * locking pickle files | |
71 * fix couch....not sure what's wrong | |
72 * allow use of CSS classes, not just xpath | |
73 | |
74 -- | |
75 | |
76 http://k0s.org |