From steve at cat-box.net  Wed May  8 16:34:48 2002
From: steve at cat-box.net (Steve Alexander)
Date: Sun Aug 10 16:40:36 2008
Subject: [Zope-book] CVS: Docs/ZopeComponentArchitecture/PythonProgrammerTutorial/Chapter1/Step1 - Contact.zcml:1.6 README.txt:1.9 products.zcml:1.2
Message-ID: <200205082034.g48KYmH05729@cvs.baymountain.com>

Update of /cvs-repository/Docs/ZopeComponentArchitecture/PythonProgrammerTutorial/Chapter1/Step1
In directory cvs.zope.org:/tmp/cvs-serv5720

Modified Files:
	Contact.zcml README.txt products.zcml 
Log Message:
bringing step 1 up to date with the way zope 3 looks today.



=== Docs/ZopeComponentArchitecture/PythonProgrammerTutorial/Chapter1/Step1/Contact.zcml 1.5 => 1.6 ===
 >
 
-<security:permission permission_id="Manage Contacts" title="Manage Contacts"/>
+<security:permission permission_id=".Contact.ManageContacts"
+                     title="Manage Contacts"/>
 
-<zmi:provideClass name="Zope.Contact."
-                  permission_id="Manage Contacts"
-                  title="Contact"
+<zmi:factoryFromClass name="ZopeProducts.Contact."
+                      class=".Contact."
+                      permission_id="Manage Contacts"
+                      title="Contact"
 />
 
 </zopeConfigure>


=== Docs/ZopeComponentArchitecture/PythonProgrammerTutorial/Chapter1/Step1/README.txt 1.8 => 1.9 ===
   usable in Zope.
 
-  The first task is to create a 'Contact' package in the Zope package
-  (it's in Zope3/lib/python/Zope). Components are contained in Zope
-  file-based products [1], which are simply Python packages that are
-  initialized within the 'products.zcml' XML configuration file at the
-  root of the Zope3 software home.  A package is simply a directory
-  that has a Python '__init__' module. We'll create the directory and
-  add the file '__init__.py'. An empty file will do for our purposes.
+  The first task is to create a 'Contact' package in the ZopeProducts
+  packge.
 
+  Components are contained in Zope file-based products [1], which are
+  simply Python packages that are initialized within the 'products.zcml'
+  XML configuration file at the root of the Zope3 software home.  A
+  package is simply a directory that has a Python '__init__' module.
+  We'll create the directory and add the file '__init__.py'. An empty
+  file will do for our purposes.
+  
+  The ZopeProducts package is a convenient place to keep external
+  products that we want to use with Zope. However, this is only a
+  convention, and we could create a product in any package that is
+  on the PYTHONPATH.
+  
+  To create the ZopeProducts and Contact packages:
+  
+  * Choose a directory on your PYTHONPATH, or create a new directory
+    and add it to your PYTHONPATH.
+    
+  * Ensure that this directory contains an __init__.py file, to make it
+    into a python package.
+    
+  * Create within this directory a new directory called ZopeProducts.
+    Add an __init__.py file inside ZopeProducts to make it into a python
+    package.
+    
+  * Inside the ZopeProdcuts directory, create a Contact directory.
+    Add an __init__.py file inside the Contact directory.
+  
   We also create the file 'Contact.py' containing the class
   definition.  This class doesn't use *any* Zope-specific classes. The
   class provides methods for accessing and modifying the contact data.
@@ -29,54 +51,76 @@
   express configuration directives. The configuration file in this
   example includes two directives. The first directive,
   'security:permission', defines a permission that we'll use for the
-  Contact product.  The second directive, 'zmi:provideClass',
+  Contact product.  The second directive, 'zmi:factoryFromClass',
   registers our class. The class being registered is specified with
-  the 'name' attribute.  The 'permission_id' attribute is used to
+  the 'class' attribute.  The 'permission_id' attribute is used to
   specify a Zope permission needed for creating instances.  If a
   permission wasn't specified, then contacts could not be created
   through the web or through code managed through the web.  The
   "title" attribute is used to specify the ZMI title for the class in
-  the Add list.  Additional attributes can be used to provide
-  additional meta data; however, the meta-data is inferred from class
-  meta-data.
+  the Add list. The 'name' attribute is used as a unique id that can be
+  used to look up the factory for this class.
+  
+  Additional attributes can be used to provide additional meta data;
+  however, the meta-data is inferred from class meta-data.
 
   In the configuration file, the class was provided using the string
-  "Zope.Contact.". This bears some explanation. First, the string
-  "Zope.Contact." is an abbreviation of the string
-  "Zope.Contact.Contact.Contact", which is the full name of the
+  ".Contact.". This bears some explanation. First, the string
+  ".Contact." is an abbreviation of the string
+  "ZopeProducts.Contact.Contact.Contact", which is the full name of the
   class object. The full name is a combination of the class module
-  name, "Zope.Contact.Contact" and the class name, "Contact". A
+  name, "ZopeProducts.Contact.Contact" and the class name, "Contact". A
   full name can be abbreviated using the following rules:
 
-  - If the full name begins with "Zope.Products.", then the
-    "Zope.Products" prefix can be omitted. A leading dot implies the
-    'Zope.Products' package.  So, for example, ".Contact" implies
-    "Zope.Products.Contact"
+  - If the zcml file was included relative to a package, using the 'package'
+    attribute in the 'include' element, the leading dot means "relative
+    to the package the zcml file was found in".
+    This is true of the declarations in the Contact.zcml file.
+
+  - If the full name begins with "ZopeProducts.", then the
+    "ZopeProducts" prefix can be omitted. A leading dot implies the
+    'ZopeProducts' package.  So, for example, ".Contact" implies
+    the "ZopeProducts.Contact" package.
+    This is used in the include directive we'll be adding to the 
+    zope 3 products.zcml file.
+    The directorive <include package=".Contact" file="Contact.zcml"/>
+    could be expanded to
+    <include package="ZopeProducts.Contact" file="Contact.zcml"/>
+    More about this further down this document.
+
 
   - If the end of the name has repeating parts, as in
     ".Contact.Contact.Contact", then the repeated parts other than the
     first can be omitted.
 
   We could have used the same mechanism to specify the
-  permission_id. The value of the permission_id attribute should be
+  permission_id. (XXX I don't think this is true, because permission_ids
+  are not resolved. SteveA.)
+  
+  The value of the permission_id attribute should be
   either a name used in a 'security:permission' directive or the name
   of a permission defined in a module.
 
-  The 'zmi:provideClass' directive accomplishes two things:
+  The 'zmi:factoryFromClass' directive accomplishes two things:
 
   1. A factory component is created and registered using the
      class. This allows other application code to create instances::
 
        from ComponentArchitecture import createObject
 
-       contact=createObject(ob, '.Contact')
+       contact = createObject(ob, 'ZopeProducts.Contact.')
 
+     XXX this paragraph not correct any more.
      An identifier for the factory is generated from the registered
      class module and class name. In this case, the module is
      'Zope.Contact.Contact' and the class is
      'Contact'. Abbreviations are allowed, as in configuration
      files. A different identifier could have been provided in the
-     'zmi:provideClass' directive.
+     'zmi:factoryFromClass' directive.
+     XXX
+     
+     The identifier for the factory was given as the 'name' attribute
+     in the factoryFromClass directive.
 
      The first argument passed to 'createObject' affects where
      'createObject' searches for factories.
@@ -95,7 +139,11 @@
   Here's the entry we put in to the 'products.zcml' file in order to
   register the Contact class::
 
-    <include package="Zope.Contact" file="Contact.zcml"/>
+    <include package="ZopeProducts.Contact" file="Contact.zcml"/>
+
+  As described further above, we can abbreviate this to::
+  
+    <include package=".Contact" file="Contact.zcml"/>
 
   The products.zcml file provided in the Step1 directory should be
   copied to the Zope3 software home, or you can edit the existing


=== Docs/ZopeComponentArchitecture/PythonProgrammerTutorial/Chapter1/Step1/products.zcml 1.1 => 1.2 ===
 >
 <!-- add include directives for products here -->
-<include package="Zope.Contact" file="Contact.zcml"/>
+<include package=".Contact" file="Contact.zcml"/>
 
 </zopeConfigure>