[Checkins] SVN: megrok.z3cform.base/trunk/ Added README.txt doctest. Preparing release.

[Souheil CHELFOUH]

Log message for revision 105175:
  Added README.txt doctest. Preparing release.
  

Changed:
  U   megrok.z3cform.base/trunk/docs/HISTORY.txt
  U   megrok.z3cform.base/trunk/src/megrok/z3cform/base/README.txt
  U   megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/__init__.py
  A   megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/test_readme.py

-=-
Modified: megrok.z3cform.base/trunk/docs/HISTORY.txt
===================================================================
--- megrok.z3cform.base/trunk/docs/HISTORY.txt	2009-10-20 17:41:15 UTC (rev 105174)
+++ megrok.z3cform.base/trunk/docs/HISTORY.txt	2009-10-20 18:27:08 UTC (rev 105175)
@@ -1,7 +1,7 @@
 Changelog
 =========
 
-0.1 (xxxx-xx-xx)
+0.1 (2009-10-20)
 ----------------
 
 * Initial release

Modified: megrok.z3cform.base/trunk/src/megrok/z3cform/base/README.txt
===================================================================
--- megrok.z3cform.base/trunk/src/megrok/z3cform/base/README.txt	2009-10-20 17:41:15 UTC (rev 105174)
+++ megrok.z3cform.base/trunk/src/megrok/z3cform/base/README.txt	2009-10-20 18:27:08 UTC (rev 105175)
@@ -1,4 +1,108 @@
-Introduction
-============
+===================
+megrok.z3cform.base
+===================
 
+`megrok.z3cform.base` is a not-so-thick layer above `z3c.form`. It
+provides a `Grok` way to register your forms and your widgets. In
+addition, the package has a collection of base forms, useable
+out-of-the box with `megrok.layout`.
 
+The customization of the forms is also eased by the use of
+`megrok.pagetemplate`, allowing you to override a template easily.
+
+
+Form registration
+=================
+
+Models
+------
+
+We set up some models to serve as a form context::
+
+  >>> import grokcore.component as grok
+  >>> from zope import interface, schema
+
+  >>> class IMammoth(interface.Interface):
+  ...    name = schema.TextLine(title=u"Name")
+  ...    age = schema.Int(title=u"Age")
+
+  >>> class Mammoth(grok.Context):
+  ...    grok.implements(IMammoth)
+  ...    name = schema.fieldproperty.FieldProperty(IMammoth['name'])
+  ...    age = schema.fieldproperty.FieldProperty(IMammoth['age'])
+
+We declare the Form. It's very similar to a grok.View::
+
+  >>> import megrok.z3cform.base as z3cform
+
+  >>> class TestForm(z3cform.Form):
+  ...    grok.context(Mammoth)
+
+
+Grokking and querying
+---------------------
+
+We let Grok register the component::
+
+  >>> grok.testing.grok_component('form', TestForm)
+  True
+
+Now, we can query it normally::
+
+  >>> from zope.publisher.browser import TestRequest
+  >>> request = TestRequest()
+  >>> manfred = Mammoth()
+
+  >>> from zope.component import getMultiAdapter
+  >>> myform = getMultiAdapter((manfred, request), name="testform")
+
+  >>> myform
+  <TestForm object at ...>
+  >>> print myform()
+  <form action="http://127.0.0.1" method="post"
+          enctype="multipart/form-data" class="form-testform">
+  ...
+
+
+Layout integration
+------------------
+
+`megrok.z3cform.base` is integrated, out-of-the-box with
+`megrok.layout`, providing base classes to ease the layout integration
+in your project.
+
+Let's have a quick overview. We create a layout::
+
+  >>> import megrok.layout
+
+  >>> class MyLayout(megrok.layout.Layout):
+  ...     grok.context(IMammoth)
+  ...     def render(self):
+  ...        return 'The layout content is: %s' % self.view.content()
+
+We declare a Page Form. A Page Form is a form that will show up inside
+a layout::
+
+  >>> class PageForm(z3cform.PageForm):
+  ...    grok.context(Mammoth)
+
+We register the components with Grok::
+
+  >>> grok.testing.grok_component('page', PageForm)
+  True
+  >>> grok.testing.grok_component('layout', MyLayout)
+  True
+
+Now, while rendering the form, we have it embedded in the Layout::
+
+  >>> pageform = getMultiAdapter((manfred, request), name="pageform")
+  >>> print pageform()
+  The layout content is: <form action="http://127.0.0.1" method="post"
+        enctype="multipart/form-data" class="form-pageform">
+  ...
+
+
+.. attention:
+
+  This is only a tiny presentation of the package features. Please,
+  read the tests for a global overview.

Modified: megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/__init__.py
===================================================================
--- megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/__init__.py	2009-10-20 17:41:15 UTC (rev 105174)
+++ megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/__init__.py	2009-10-20 18:27:08 UTC (rev 105175)
@@ -1,11 +1,6 @@
 import os.path                                                                  
-import megrok.z3cform.base
 from zope.app.testing.functional import ZCMLLayer
 
-ftesting_zcml = os.path.join(
-    os.path.dirname(__file__),
-    'ftesting.zcml'
-    )
-FunctionalLayer = ZCMLLayer(ftesting_zcml, __name__, 'FunctionalLayer',
-                            allow_teardown=True)
-
+ftesting_zcml = os.path.join(os.path.dirname(__file__), 'ftesting.zcml')
+FunctionalLayer = ZCMLLayer(
+    ftesting_zcml, __name__, 'FunctionalLayer', allow_teardown=True)

Added: megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/test_readme.py
===================================================================
--- megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/test_readme.py	                        (rev 0)
+++ megrok.z3cform.base/trunk/src/megrok/z3cform/base/tests/test_readme.py	2009-10-20 18:27:08 UTC (rev 105175)
@@ -0,0 +1,15 @@
+import unittest
+from zope.testing import doctest
+from zope.app.testing import functional
+from megrok.z3cform.base.tests import FunctionalLayer
+
+
+def test_suite():
+    readme = functional.FunctionalDocFileSuite(
+        '../README.txt',
+        optionflags=(doctest.ELLIPSIS + doctest.NORMALIZE_WHITESPACE),
+        )
+    readme.layer = FunctionalLayer
+    suite = unittest.TestSuite()
+    suite.addTest(readme)
+    return suite