|
0
|
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
|
