[Checkins] SVN: five.grok/trunk/src/five/grok/README.txt - Structure README in section,

[Sylvain Viollon]

Log message for revision 91561:
  
  - Structure README in section,
  
  - Add forms examples.
  
  

Changed:
  U   five.grok/trunk/src/five/grok/README.txt

-=-
Modified: five.grok/trunk/src/five/grok/README.txt
===================================================================
--- five.grok/trunk/src/five/grok/README.txt	2008-09-27 14:13:36 UTC (rev 91560)
+++ five.grok/trunk/src/five/grok/README.txt	2008-09-27 15:45:41 UTC (rev 91561)
@@ -4,7 +4,8 @@
 Overview
 --------
 
-This package is meant to provide all the grok functionalities into Zope 2.
+This package is meant to provide all the grok functionalities into
+Zope 2.
 
 How-to
 ------
@@ -64,6 +65,10 @@
     ...             cavesInfos.append(caveInfo)
     ...         return cavesInfos
 
+
+Views
+`````
+
 The example above uses a filesystem template. We can also use inline
 templates, like this:
 
@@ -73,7 +78,7 @@
 
     <<< inlinegrokvillage = grok.PageTemplate(u'Village: <b tal:content="here/id"></b>')
 
-Or, we could specify the render() method explicitly:
+Or, we could specify the ``render()`` method explicitly:
 
     <<< class Cave(SimpleFolder):
     ...
@@ -88,6 +93,10 @@
     ...                                 (self.context.id,
     ...                                  self.context.numberOfCaveWomen())
 
+Let's create an add view, and a new content ``CaveWoman``. You can
+provide some actual code in the ``update()`` method which is called
+before ``render()``::
+
     <<< class AddCaveWoman(grok.View):
     ...     grok.context(Cave)
     ...     grok.name(u'cave-woman-add')
@@ -101,7 +110,20 @@
     ...         self.context._setObject(id, CaveWoman(name, age, hairType,
     ...                                               size, weight))
 
+A ``CaveWoman`` is defined using an interface::
+
+    <<< from zope.interface import Interface
+    <<< from zope import schema
+
+    <<< class ICaveWoman(Interface):
+    ...     name = schema.TextLine(title=u"Name")
+    ...     age = schema.Int(title=u"Age")
+    ...     hairType = schema.TextLine(title=u"Hair Type")
+    ...     size = schema.Int(title=u"Size")
+    ...     weight = schema.Int(title=u"Weight")
+
     <<< class CaveWoman(grok.Model):
+    ...     grok.implements(ICaveWoman)
     ...
     ...     def __init__(self, name, age, hairType, size,
     ...                  weight):
@@ -111,8 +133,49 @@
     ...         self.size = size
     ...         self.weight = weight
 
-    <<< from zope.interface import Interface
 
+Forms
+`````
+
+We are going to define a display form for a ``CaveWoman``, it's going
+to be the default view::
+
+    <<< class Index(grok.DisplayForm):
+    ...     grok.context(CaveWoman)
+
+And the same way an edition form::
+
+    <<< class Edit(grok.EditForm):
+    ...     grok.context(CaveWoman)
+
+
+We can even create custom forms::
+
+    <<< class ISearchWoman(Interface):
+    ...     name = schema.TextLine(title=u"Woman to search")
+
+    <<< class Search(grok.Form):
+    ...     grok.context(Cave)
+    ...
+    ...     form_fields = grok.Fields(ISearchWoman)
+    ...
+    ...     def update(self):
+    ...         # Default search results
+    ...         self.results = []
+    ...
+    ...     @grok.action(u"Search")
+    ...     def search(self, name):
+    ...         # Stupid not efficient search
+    ...         for cave in self.context.objectValues():
+    ...             if cave.id.startswith(name):
+    ...                 self.results.append(cave)
+
+Adapters
+````````
+
+Now, we can create an adapter for our new ``CaveWoman`` content which
+is going to give information her facebook profile::
+
     <<< class ICaveWomanSummarizer(Interface):
     ...
     ...     def info():
@@ -129,6 +192,13 @@
     ...                 'weight': self.context.weight,
     ...                 'size': self.context.size}
 
+
+Global utility
+``````````````
+
+We can create a local utility. When a ``CaveWoman`` is added, we can
+lookup our utility and use it::
+
     <<< from zope.app.container.interfaces import IObjectAddedEvent
     <<< from zope.component import getUtility
 
@@ -170,6 +240,12 @@
     ...  * Weight: %(weight)s
     ...  * Size: %(size)s""" % profile.info()
 
+
+Test
+````
+
+And finally we can test all created components::
+
     >>> from zope.component import queryMultiAdapter
 
     >>> martijnCave = village.addCave('martijn-cave')
@@ -241,4 +317,4 @@
     <BLANKLINE>
     
     >>> print queryMultiAdapter((village, request), name='inline')()
-    Village: <b>amsterdam</b>
\ No newline at end of file
+    Village: <b>amsterdam</b>