[Checkins] SVN: grokcore.viewlet/trunk/README.txt Write a base version of the README file.
Sylvain Viollon
sylvain at infrae.com
Mon Oct 27 18:16:14 EDT 2008
Log message for revision 92638:
Write a base version of the README file.
Changed:
U grokcore.viewlet/trunk/README.txt
-=-
Modified: grokcore.viewlet/trunk/README.txt
===================================================================
--- grokcore.viewlet/trunk/README.txt 2008-10-27 21:46:48 UTC (rev 92637)
+++ grokcore.viewlet/trunk/README.txt 2008-10-27 22:16:14 UTC (rev 92638)
@@ -1,5 +1,128 @@
-grokcore.viewlet
-================
+This package provides support to write and register Zope Viewlets
+directly in Python (without ZCML). It's designed to be used with
+`grokcore.view`_ which let you write and register Zope Views.
-Grok-like configuration for Zope viewlets.
+.. contents::
+Setting up ``grokcore.viewlet``
+===============================
+
+This package is set up like the `grokcore.component`_
+package. Please refer to its documentation for more details. The
+additional ZCML lines you will need are::
+
+ <include package="grokcore.viewlet" file="meta.zcml" />
+ <include package="grokcore.viewlet" />
+
+Put the first line somewhere near the top of your root ZCML file.
+
+Examples
+========
+
+First we need a view to call our viewlet manager::
+
+ from grokcore import viewlet
+
+ class Index(viewlet.View):
+ pass
+
+ index = viewlet.Page Template("""
+ <body>
+ <head>Test</head>
+ <body>
+ <div tail:content="structure provider:content">
+ </div>
+ </body>
+ """)
+
+After that we could define only a manager which display something::
+
+ class Content(viewlet.ViewletManager):
+ viewlet.View(Index)
+
+ def render(self):
+ return u'<h1>Hello World</h1>'
+
+
+Or a completely different example::
+
+ class AdvancedContent(viewlet.ViewletManager):
+ viewlet.name('content')
+ viewlet.view(Index)
+
+And some viewlets for that one::
+
+ class StaticData(viewlet.Viewlet):
+ viewlet.view(Index)
+ viewlet.viewletmanager(AdvancedContent)
+
+ def render(self):
+ return u'<p> Data from %s</p>' self.context.id
+
+Or::
+
+ class SecretData(viewlet.Viewlet):
+ viewlet.view(Index)
+ viewlet.viewletmanager(AdvancedContent)
+ viewlet.require('agent.secret')
+
+ secretdata = viewlet.PageTemplate("""
+ <p>Nothing to see here.</p>
+ """)
+
+The way templates are binded to components works exactly the way than
+in `grokcore.view`_, for more information refer to its
+documentation.
+
+API Overview
+============
+
+Base classes
+------------
+
+``ViewletManager``
+ Define a new viewlet manager. You can either provide a render
+ method, a template, which can or not use registered viewlets.
+
+ If you define a template, ``view`` is added as a reference to the
+ current view for which the manager is rendering in the template's
+ namespace. It is available as well as an attribute on the manager
+ object.
+
+``Viewlet``
+ Define a new viewlet. You can either provide a template or a render
+ method on it. Like in views, you can define an update method to
+ process needed data.
+
+ Like for manager, ``view`` is added to the template namespace if
+ used. ``viewletmanager`` is defined as well as a reference to the
+ manager in the template's namespace and as an attribute on the
+ viewlet object.
+
+Directives
+----------
+
+You can use directives from `grokcore.view`_ to register your
+viewlet or viewlet manager: ``name``, ``context``, ``layer`` and
+``require`` (for security on a viewlet).
+
+To that is added:
+
+``view``
+ Select for which view is registered a viewlet or a viewlet manager.
+
+``viewletmanager``
+ Select for which viewlet manager is registered a viewlet.
+
+``order``
+ Define a rendering order for viewlets in a viewlet manager. This
+ should be a number, the smaller order render first, bigger last.
+
+
+Additionally, the ``grokcore.viewlet`` package exposes the
+`grokcore.component`_, `grokcore.security`_ and `grokcore.view`_ APIs.
+
+.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component
+.. _grokcore.viewlet: http://pypi.python.org/pypi/grokcore.viewlet
+.. _grokcore.security: http://pypi.python.org/pypi/grokcore.security
+.. _grokcore.view: http://pypi.python.org/pypi/grokcore.view
More information about the Checkins
mailing list