Mercurial > hg > commentator

comparison README.txt @ 0:1c95a3fa76c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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