[Checkins] SVN: z3c.caching/trunk/ Make cache rules dotted names so that they can be namespaced properly. This is not strictly enforced here, but *is* enforced in the plone.app.caching UI.

[Martin Aspeli]

Log message for revision 107744:
  Make cache rules dotted names so that they can be namespaced properly. This is not strictly enforced here, but *is* enforced in the plone.app.caching UI.

Changed:
  U   z3c.caching/trunk/README.txt
  U   z3c.caching/trunk/src/z3c/caching/interfaces.py

-=-
Modified: z3c.caching/trunk/README.txt
===================================================================
--- z3c.caching/trunk/README.txt	2010-01-06 15:17:06 UTC (rev 107743)
+++ z3c.caching/trunk/README.txt	2010-01-06 15:48:25 UTC (rev 107744)
@@ -29,8 +29,8 @@
 Usage
 =====
 
-You can register rulesets using either zcml or direct python. If you
-use zcml you can use the ``cache:ruleset`` directive::
+You can register rulesets using either ZCML or directly in python. If you
+use ZCML you can use the ``<cache:ruleset />`` directive::
 
   <configure
       xmlns="http://namespaces.zope.org/zope"
@@ -38,14 +38,14 @@
       xmlns:cache="http://namespaces.zope.org/cache"/>
     
     <cache:rulesetType
-        name="plone-content-types"
+        name="plone.contentTypes"
         title="Plone content types"
         description="Non-folderish content types"
         />
     
     <cache:ruleset
         for=".frontpage.FrontpageView"
-        ruleset="plone-content-types"
+        ruleset="plone.contentTypes"
         />
 
     <browser:page
@@ -58,8 +58,13 @@
   </configure>
 
 This example sets up a browser view called ``frontpage_view`` and
-associates it with the ``plone-content-types`` ruleset.
+associates it with the ``plone.contentTypes`` ruleset.
 
+**NOTE:** Ruleset names should be *dotted names*. That is, they should consist
+only of upper or lowercase letters, digits, underscores and/or periods (dots).
+The idea is that this forms a namespace similar to namespaces created by
+packages and modules in Python.
+
 You can specify either a class or an interface in the ``for`` attribute. As
 with an adapter registration, a more specific registration can be used to
 override a more generic one.
@@ -73,7 +78,7 @@
    from z3c.caching.registry import register
    from frontpage import FrontpageView
 
-   register(FrontpageView, "plone-content-types")
+   register(FrontpageView, "plone.contentTypes")
 
 To find the ruleset for an object use the ``lookup()`` method::
 
@@ -83,7 +88,7 @@
 To declare the ruleset type metadata, use the ``declareType`` method::
 
    from z3c.caching.registry import declareType
-   declareType = declareType(name="plone-content-types", \
+   declareType = declareType(name="plone.contentTypes", \
                              title=u"Plone content types", \
                              description=u"Non-folderish content types")
 

Modified: z3c.caching/trunk/src/z3c/caching/interfaces.py
===================================================================
--- z3c.caching/trunk/src/z3c/caching/interfaces.py	2010-01-06 15:17:06 UTC (rev 107743)
+++ z3c.caching/trunk/src/z3c/caching/interfaces.py	2010-01-06 15:48:25 UTC (rev 107744)
@@ -5,7 +5,8 @@
     
     def register(obj, rule):
         """Mark objects that are implementers of `obj` to use the caching 
-        rule `rule`.
+        rule `rule`. The name should be a dotted name, consisting only of
+        upper or lowercase letters, digits, and/or periods.
         """
     
     def unregister(obj):
@@ -29,7 +30,9 @@
     
     def declareType(name, type, description):
         """Declare a new ruleset type. This will put a new `IRulesetType`
-        into the list of objects returned by `enumerate`.
+        into the list of objects returned by `enumerate`. The name should be
+        a dotted name, consisting only of upper or lowercase letters, digits,
+        and/or periods.
         """
     
     def enumerateTypes():
@@ -49,7 +52,7 @@
     The title and description are used for UI support.
     """
     
-    name        = schema.ASCIILine(title=u"Ruleset name")
+    name        = schema.DottedName(title=u"Ruleset name")
     title       = schema.TextLine(title=u"Title")
     description = schema.TextLine(title=u"Description", required=False)