[CMF-checkins] SVN: CMF/trunk/docs/ToolsAreUtilities.stx - a
straggler
Jens Vagelpohl
jens at dataflake.org
Wed Mar 7 11:44:53 EST 2007
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
More information about the CMF-checkins
mailing list