[CMF-checkins] SVN: CMF/trunk/docs/ToolsAreUtilities.stx - a straggler

[Jens Vagelpohl]

Log message for revision 73036:
  - a straggler
  

Changed:
  A   CMF/trunk/docs/ToolsAreUtilities.stx

-=-
Added: CMF/trunk/docs/ToolsAreUtilities.stx
===================================================================
--- CMF/trunk/docs/ToolsAreUtilities.stx	2007-03-07 16:41:03 UTC (rev 73035)
+++ CMF/trunk/docs/ToolsAreUtilities.stx	2007-03-07 16:44:52 UTC (rev 73036)
@@ -0,0 +1,66 @@
+Tools Are Utilities
+
+  With the advent of CMF 2.1, tools are treated a bit different from before.
+  Whereas before they were simply looked up by their well-known ID, now they
+  are treated as (local) utilities for each site. This has consequences for
+  developers who either use existing tools or want to build new tools in their
+  code.
+
+  The following presents a few samples that can act as a guideline for code
+  changes.
+
+  - Looking up a tool from trusted code (Zope filesystem product or External
+    Method):
+
+    The old way::
+
+      from Products.CMFCore.utils import getToolByName
+      foo_tool = getToolByName(self, 'portal_foo')
+
+    The new way::
+
+      from zope.component import getUtility
+      from Products.Fooproduct.interfaces import IFooTool
+      foo_tool = getUtility(IFooTool)
+
+    This requires the tool to be registered as a utility for the given
+    interface. As you can see, tools are now looked up as utilities
+    implementing specific interfaces.
+
+  - Looking up a tool from untrusted code (Python Scripts):
+
+    The old way::
+
+      from Products.CMFCore.utils import getToolByName
+      foo_tool = getToolByName(context, 'portal_foo')
+
+    The new way::
+
+      from Products.CMFCore.utils import getToolByInterfaceName
+      foo_tool = getToolByInterfaceName('Products.Fooproduct.interfaces.IFooTool')
+
+    Since the functions from zope.component are not accessible to untrusted
+    code, a helper function 'getToolByInterfaceName' has been provided. Its
+    main argument is a string representing the dotted name of the interface
+    for which you are looking up the utility. Just as with getToolByName, you
+    may pass a 'default' argument to specify what is returned if the interface
+    or tool lookup fails.
+
+  If you have code for a CMF tool, consider changing your code so it contains
+  an explicit interface for your tool and register it as a utility for that
+  interface. This can be done conveniently using GenericSetup. Please see the
+  CMFCalendar or CMFUid packages as good examples for registering tools the
+  right way.
+
+  If your code has been in use before CMF 2.1 and you want to let other
+  developers know how to specifically modify their getToolByName calls, you
+  can use a simple registration mechanism that will be in place until CMF 2.3.
+  It will cause getToolByName to emit a deprecation message with specific
+  instructions for each registered tool ID. This mechanism is used for all
+  standard CMF tools already, all you would need to do in your code module
+  is the following::
+
+    from Products.CMFCore.utils import registerToolInterface
+    from Products.FooProduct.interfaces import IFooTool
+    registerToolInterface('portal_foo', IFooTool)
+


Property changes on: CMF/trunk/docs/ToolsAreUtilities.stx
___________________________________________________________________
Name: svn:eol-style
   + native