[Zope3-checkins] SVN: Zope3/branches/roger-contentprovider/src/zope/portlet/ First steps towards developing a portlet state handler

[Helmut Merz]

Log message for revision 38971:
  First steps towards developing a portlet state handler

Changed:
  U   Zope3/branches/roger-contentprovider/src/zope/portlet/browser/__init__.py
  U   Zope3/branches/roger-contentprovider/src/zope/portlet/interfaces.py
  A   Zope3/branches/roger-contentprovider/src/zope/portlet/statehandler.txt
  U   Zope3/branches/roger-contentprovider/src/zope/portlet/tests/test_doc.py

-=-
Modified: Zope3/branches/roger-contentprovider/src/zope/portlet/browser/__init__.py
===================================================================
--- Zope3/branches/roger-contentprovider/src/zope/portlet/browser/__init__.py	2005-10-08 16:44:29 UTC (rev 38970)
+++ Zope3/branches/roger-contentprovider/src/zope/portlet/browser/__init__.py	2005-10-08 16:55:43 UTC (rev 38971)
@@ -13,5 +13,5 @@
 ##############################################################################
 """Protlet views
 
-$Id:$
+$Id$
 """

Modified: Zope3/branches/roger-contentprovider/src/zope/portlet/interfaces.py
===================================================================
--- Zope3/branches/roger-contentprovider/src/zope/portlet/interfaces.py	2005-10-08 16:44:29 UTC (rev 38970)
+++ Zope3/branches/roger-contentprovider/src/zope/portlet/interfaces.py	2005-10-08 16:55:43 UTC (rev 38971)
@@ -28,6 +28,25 @@
        may be be changed on user interaction.
     """
 
+
 class IPortletManager(zope.interface.Interface):
     """A portlet manager provides one or more portlets.
     """
+
+
+class IStateHandler(zope.interface.Interface):
+    """An adapter responsible for storing the states of portlets.
+    """
+
+    def setState(state, name):
+        """Set the state of the portlet; the name parameter is the name
+           of the portlet in the portlet manager.
+        """
+
+    def getState(name):
+        """Return the state of the portlet; the name parameter is the name
+           of the portlet in the portlet manager.
+        """
+
+
+        
\ No newline at end of file

Added: Zope3/branches/roger-contentprovider/src/zope/portlet/statehandler.txt
===================================================================
--- Zope3/branches/roger-contentprovider/src/zope/portlet/statehandler.txt	2005-10-08 16:44:29 UTC (rev 38970)
+++ Zope3/branches/roger-contentprovider/src/zope/portlet/statehandler.txt	2005-10-08 16:55:43 UTC (rev 38971)
@@ -0,0 +1,70 @@
+=====================
+Portlet Statehandlers
+=====================
+
+A state handler is an adapter to portlets that is responsible
+for keeping track of the portlets' states.
+
+It depends on the implementation of the state handler where and how
+the state is stored.
+
+
+Getting Started
+---------------
+
+  >>> from zope.app.testing import ztapi
+  >>> from zope.app import zapi
+  >>> from zope.interface import implements
+  >>> from zope.interface import providedBy
+  
+  >>> from zope.portlet.interfaces import IStateHandler
+  >>> from zope.portlet.interfaces import IPortlet
+
+Let's start with a simple dummy state handler that stores the state
+transiently in itself.
+  
+  >>> class SimpleStateHandler(object):
+  ...     implements(IStateHandler)
+  ...
+  ...     def __init__(self, context):
+  ...         self.context = context
+  ...         self.states = {}
+  ...
+  ...     def setState(self, state, name):
+  ...         cpType = list(providedBy(self.context))[0]
+  ...         cpTypeName = cpType.__module__ + '.' + cpType.__name__
+  ...         self.states[cpTypeName + '/' + name] = state
+  ...
+  ...     def getState(self, name):
+  ...         cpType = list(providedBy(self.context))[0]
+  ...         cpTypeName = cpType.__module__ + '.' + cpType.__name__
+  ...         return self.states[cpTypeName + '/' + name]
+
+We register the state handler as an adapter.
+
+  >>> ztapi.provideAdapter(IPortlet, IStateHandler, SimpleStateHandler)
+
+In addition we need a portlet that wants to store its state in the state
+handler. We provide the portlet with an interface thats specifies itself
+content provider type.
+
+  >>> class ISpecialPortlet(IPortlet):
+  ...     pass
+
+  >>> class Portlet(object):
+  ...     implements(ISpecialPortlet)
+
+  >>> portlet = Portlet()
+
+Now we can retrieve a state handler and store the state for the portlet;
+note that we have to provide the name of the portlet in the portlet manager.
+
+  >>> handler = zapi.getAdapter(portlet, IStateHandler)
+  >>> handler.setState('visible', name='dummy.portlet')
+
+Now we can retrieve the state again:
+
+  >>> handler.getState(name='dummy.portlet')
+  'visible'
+  
+  
\ No newline at end of file


Property changes on: Zope3/branches/roger-contentprovider/src/zope/portlet/statehandler.txt
___________________________________________________________________
Name: svn:keywords
   + Id
Name: svn:eol-style
   + native

Modified: Zope3/branches/roger-contentprovider/src/zope/portlet/tests/test_doc.py
===================================================================
--- Zope3/branches/roger-contentprovider/src/zope/portlet/tests/test_doc.py	2005-10-08 16:44:29 UTC (rev 38970)
+++ Zope3/branches/roger-contentprovider/src/zope/portlet/tests/test_doc.py	2005-10-08 16:55:43 UTC (rev 38971)
@@ -74,6 +74,10 @@
 #                      setUp=setUp, tearDown=tearDown,
 #                      optionflags=doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS,
 #                      ),
+         DocFileSuite('../statehandler.txt',
+                      setUp=setUp, tearDown=tearDown,
+                      optionflags=doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS,
+                      ),
         ))
 
 if __name__ == '__main__':