[Zope3-checkins] CVS: Zope3/src/zope/app/services - README.txt:1.1.2.5

[Guido van Rossum]

Update of /cvs-repository/Zope3/src/zope/app/services
In directory cvs.zope.org:/tmp/cvs-serv30510

Modified Files:
      Tag: local-utility-branch
	README.txt 
Log Message:
(Mostly) finished the description of the three views for configuring
utilities.


=== Zope3/src/zope/app/services/README.txt 1.1.2.4 => 1.1.2.5 ===
--- Zope3/src/zope/app/services/README.txt:1.1.2.4	Tue Mar 18 16:10:04 2003
+++ Zope3/src/zope/app/services/README.txt	Tue Mar 18 16:58:42 2003
@@ -334,6 +334,7 @@
 
 - An "edit configuration" view to change a utility's configuration.
 
+
 The first view we create is the "Configurations" view for utility
 components.  This is very similar to the Configurations view for
 service components, and for several other components that are handled
@@ -364,6 +365,7 @@
 returns enough information to render the utility's interface, name,
 activity status, and URL.
 
+
 The second view we create is the add view for utility configurations.
 Here's the ZCML::
 
@@ -379,12 +381,24 @@
       fields="name interface componentPath permission status"
       />
 
+(XXX Maybe briefly explain each attribute, like we do below for
+<editform>?)
+
 Notice that there's no template!  The <addform> directive creates the
 form for us using a generic template, zope/app/browser/form/add.pt,
 and information about the specific fields to be displayed extracted
 from the schema.  We do specify a class name: the AddConfiguration
 class.  This class needs some explanation.
 
+The ``for=`` attribute says that this view applies to all objects that
+implement the ILocalUtility interface.  All utility components should
+implement this interface in order to be configurable as a utility.
+This interface extends IUseConfigurable, which is required so that a
+utility component can keep track of the back pointers to configuration
+objects that reference it, as was discussed above.  Utility components
+should also implement IAttributeAnnotatable, unless they want to
+provide a different way to store annotations.
+
 The <addform> directive uses the AddConfiguration class as a mix-in
 class.  It may override various methods to customize the add form; the
 set of methods that can be customized is given by the
@@ -438,44 +452,61 @@
 
 We also override beforeUpdateHook().  XXX I'll let Jim describe this.
 
-The third view we create is the edit view for utility configuration
-objects.  This is similar to the add view, although it XXX
-
-
-- XXX ILocalUtility: to be used as a utility; adds IUseConfigurable,
-  promises adaptable to IUseConfigurationm enables "Utility
-  Configuration" tab.
-
-
 
+The third view we create is the edit view for utility configuration
+objects.  This view looks similar to the add view, but its definition
+is simpler, because it isn't deviating quite as much from a standard
+edit view::
+
+  <editform
+      name="index.html"
+      menu="zmi_views" title="Edit"
+      schema="zope.app.interfaces.services.utility.IUtilityConfiguration"
+      label="Utility Configuration"
+      permission="zope.ManageServices"
+      fields="name interface componentPath permission status"
+      />
 
+This is a view on IUtilityConfiguration, which is typical for an edit
+view.  The good news is that it has no template *or* class!  The
+<editform> directive lets us specifiy all the customization we need:
 
+- ``name=``: The view name.  This is the last component of the URL for
+  the view.
 
-To do:
+- ``menu=``, ``title=``: Menu information: "zmi_views" means that this
+  view is one of the "tabs" for this type of object, the title
+  argument gives the text in the tab.
 
-  Need a UI for browsing registered utilities in the utility service.
+- ``schema=``: The interface used as the schema.  The field
+  definitions in this interface define which attributes are displayed
+  in the form, and how.
 
-  Configuration of objects in folders
+- ``label=``: The label, used as the title text in the view.
 
-    - Need the configuration object class that keeps track of:
+- ``permission=``: A permission needed to access the view.
 
-      o name
+- ``fields=``: A list of fields to be displayed in the form.  This is
+  used here to force the order in which the fields are displayed.  It
+  can also be used to display only a subset of the fields present in
+  the schema.
 
-      o interface
+And that's all there is to the edit view.  Some observable differences
+between the edit view and the add view:
 
-      o component path
+- The add view lets you specify the name or the interface; the edit
+  view displays these fields read-only.
 
-      o permission
+- When you submit the add view, you are redirected to the
+  configuration manager; the edit view takes you back to itself.
 
-    - Add view for the configuration
 
-    - Edit view for the configuration
 
-    - Summary view of the configuration in a configuration registry
+To do:
 
-    - Summary view of the configuration in a configuration manager
+  Describe the demo utility
 
-    - Configurations view
+  Need a UI for browsing registered utilities in the utility service.
 
   Configuration of module globals