Add (customizable) captcha support

[software/blitiri.git] / config.py.sample

diff --git a/config.py.sample b/config.py.sample
index 1f2c4eac0f1f68f84eb7e8029aa3be3ee22b941d..c3b3653c845b40e75e9f93e7e4cf10a16516d933 100644 (file)
--- a/config.py.sample
+++ b/config.py.sample
@@ -36,4 +36,47 @@ author = "Hartmut Kegan"
 # Article encoding
 encoding = "utf8"
 
+# You can customize the captcha engine by providing a Captcha class with this
+# interface:
+# Constructor:
+#      Captcha(article) -> constructor, takes an article[1] as argument
+# Attributes:
+#      puzzle -> a string with the puzzle the user must solve to prove he is
+#                not a bot (can be raw HTML)
+#      help -> a string with extra instructions, shown only when the user
+#              failed to solve the puzzle
+# Methods:
+#      validate(form_data) -> based on the form data[2],  returns True if
+#                             the user has solved the puzzle uccessfully
+#                             (False otherwise).
+#
+# Note you must ensure that the puzzle attribute and validate() method can
+# "communicate" because they are executed in different requests. You can pass a
+# cookie or just calculate the answer based on the article's data, for example.
+#
+# Example: a captcha class to completely disable the captcha feature
+# class Captcha (object):
+#      def __init__(self, article):
+#              self.puzzle = ''
+#              self.help = ''
+#      def validate(form_data):
+#              return True
+# Remove the captcha input field from the form template, and that's it!
+#
+# [1] article is an object with all the article's information:
+#      path -> string
+#      created -> datetime
+#      updated -> datetime
+#      uuid -> string (unique ID)
+#      title -> string
+#      author -> string
+#      tags -> list of strings
+#      raw_contents -> string in rst format
+#      comments -> list of Comment objects (not too relevant here)
+# [2] form_data is an object with the form fields (all strings):
+#      author, author_error
+#      link, link_error
+#      catpcha, captcha_error
+#      body, body_error
+#      action, method