Howto "how to extend the comment form" added to documentation.

svn path=/plone.app.discussion/trunk/; revision=50068

docs/source/howtos/howto_extend_the_comment_form.txt

@@ -0,0 +1,140 @@
+Comment Form
+============
+
+This document explains how to extend the plone.app.discussion comment form with
+additional fields in an add-on product.
+
+.. seealso::
+    * See the github collective for the source code of this howto:
+      https://github.com/collective/collective.example.commentextender/
+
+.. note::
+
+  This howto applies only to plone.app.discussion >= 2.0.4 and >= 1.1.1. Prior
+  versions will not store the extended fields on the comment.
+
+First, create a new plone package::
+
+    $ paster create -t plone my.commentextender
+
+Go to the main directory of the package (my.commentextender/my/commentextender)
+and create a new file commentextender.py containing the ICommentExtenderFields 
+interface definition with an additional "website" field, a persistent
+CommentExtenderFields class to actually store the "website" value, a 
+CommentExtenderFactory to create the CommentExtenderFields, and CommentExtender
+class to actually extend the default comment form with the field:: 
+
+    from persistent import Persistent
+    
+    from z3c.form.field import Fields
+    
+    from zope import interface
+    from zope import schema
+    
+    from zope.annotation import factory
+    from zope.component import adapts
+    from zope.interface import Interface
+    from zope.publisher.interfaces.browser import IDefaultBrowserLayer
+    
+    from plone.z3cform.fieldsets import extensible
+    
+    from plone.app.discussion.browser.comments import CommentForm
+    from plone.app.discussion.comment import Comment
+    
+    # Interface to define the fields we want to add to the comment form.
+    class ICommentExtenderFields(Interface):
+        website = schema.TextLine(title=u"Website", required=False)
+    
+    # Persistent class that implements the ICommentExtenderFields interface
+    class CommentExtenderFields(Persistent):
+        interface.implements(ICommentExtenderFields)
+        adapts(Comment)
+        website = u""
+    
+    # CommentExtenderFields factory
+    CommentExtenderFactory = factory(CommentExtenderFields)
+    
+    # Extending the comment form with the fields defined in the 
+    # ICommentExtenderFields interface. 
+    class CommentExtender(extensible.FormExtender):
+        adapts(Interface, IDefaultBrowserLayer, CommentForm)
+    
+        fields = Fields(ICommentExtenderFields)
+    
+        def __init__(self, context, request, form):
+            self.context = context
+            self.request = request
+            self.form = form
+    
+        def update(self):
+            # Add the fields defined in ICommentExtenderFields to the form.
+            self.add(ICommentExtenderFields, prefix="")
+            # Move the website field to the top of the comment form.
+            self.move('website', before='text', prefix="")
+
+.. seealso::
+
+  * See the plone.z3cform pypi page for more documentation about how to add,
+    hide, and reorder fields: 
+    http://pypi.python.org/pypi/plone.z3cform#fieldsets-and-form-extenders
+
+Now register the CommentExtenderFactory and CommentExtender Classes we just 
+created by adding the following lines to your configure.zcml::
+
+    <adapter
+      factory=".commentextender.CommentExtenderFactory"
+      provides=".commentextender.ICommentExtenderFields" />
+    
+    <adapter
+      factory=".commentextender.CommentExtender"
+      provides="plone.z3cform.fieldsets.interfaces.IFormExtender" />
+
+Create a new Plone instance, globally allow commenting, allow commenting on a
+content object and you will see a comment form with an additional "website"
+field.
+
+Since we do not only want to store the "website" value on the comments, but also
+to show these values for existing comments, we have to override the comments
+viewlet. The easiest way to do this is to use z3c.jbot.
+
+First, add z3c.jbot to the setup.py of the my.commentextender package::
+
+      install_requires=[
+          ...
+          'z3c.jbot',          
+      ],
+
+Next, create a new directory called "overrides" inside the my.commentextender
+package and register it together with z3c.jbot in your configure.zcml::
+
+    <configure
+        ...
+        xmlns:browser="http://namespaces.zope.org/browser">
+    
+      ...
+      
+      <include package="z3c.jbot" file="meta.zcml" />
+    
+      <browser:jbot
+        directory="overrides" />
+    
+    </configure>
+    
+Copy plone.app.discussion/plone/app/discussion/browser/comments.pt to the 
+overrides directory we just created and rename comments.pt to 
+plone.app.discussion.browser.comments.pt.
+
+You can now add code to show the website attribute to the documentByLine::
+
+    <div class="documentByLine" i18n:domain="plone.app.discussion">
+        ...
+        <div class="commentWebsite"
+             tal:condition="reply/website|nothing">
+           <a href=""
+              tal:attributes="href reply/website"
+              tal:content="reply/website"></a>
+        </div>
+    </div>
+
+
+

docs/source/howtos/index.txt

@@ -0,0 +1,4 @@
+.. toctree::
+   :maxdepth: 2
+
+   howto_extend_the_comment_form.txt

docs/source/index.txt

@@ -17,8 +17,10 @@ Contents:
    architecture.txt
    design.txt
    workflow.txt
+   comments.txt
    captcha.txt
    email-notification.txt
+   howtos/index.txt
    api.txt
    
 .. include:: ../../CHANGES.txt