[Zope-CVS] CVS: Packages/JobBoardEx - Tutorial.html:1.14

[Guido van Rossum]

Update of /cvs-repository/Packages/JobBoardEx
In directory cvs.zope.org:/tmp/cvs-serv27602

Modified Files:
	Tutorial.html 
Log Message:
Describe the approval form.


=== Packages/JobBoardEx/Tutorial.html 1.13 => 1.14 ===
     These classes perform the actual "business logic" for your
     application, but they don't control the views (they don't have
-    anything to do with views - if you asked them about thier views,
+    anything to do with views; if you asked them about their views,
     they wouldn't know what you were talking about).</li>
 
     <p><li>Creating one or more Zope Page Template files (.pt files),
@@ -364,7 +364,7 @@
 application), and the goal is to just tell Zope how to do the
 controlling for you.  But it's inevitable that you must put
 <i>some</i> control code in your system, and it turns out that control
-code is typically highly coupled with view code - so it's cleaner to
+code is typically highly coupled with view code; so it's cleaner to
 include the control code, such as the action() method, in the view
 class.  Thus we end up with more of a view/controller.  The trick is
 not to give into the temptation to put all your logic in the view
@@ -373,6 +373,71 @@
 that don't scale well.
 
 
+<h2>Approving Submitted Jobs</h2>
+
+<p>The last step in the workflow is the approval form.  This form is
+only accessible for site managers.  Let's start with the configuration
+code for a change:
+
+<pre>
+&lt;browser:view for=".IJobList."
+              factory=".ApproveJobsView."
+              permission="Zope.ManageContent"
+              >
+
+  &lt;browser:page name="approveForm.html" attribute="form" />
+  &lt;browser:page name="approve"          attribute="action" />
+
+&lt;/browser:view>
+</pre>
+
+<p>This tells us there's a class ApproveJobsView in the <a
+href="ApproveJobsView.py">ApproveJobsView.py</a> module, which
+represents a view for objects implementing the IJobList interface.
+The permission attribute tells us that the form is only accessible to
+site managers (who are presumably the only people with the permission
+Zope.ManageContent).
+
+<p>The view has two attributes representing different pages of the
+view: one named form which the browser accesses as approveForm.html,
+and one named action which the browser accesses as approve.  Looking
+at the code, we see the same pattern as for JobCreateView: the form is
+a page template named <a href="ApproveJobs.pt">ApproveJobs.pt</a>, and
+action is a method.
+
+<p>The page template used here contains a loop over all the job ids
+returned by the JobList method getPendingIds; this returns the ids of
+all jobs that are pending approval (let's hope there aren't thousands
+of these :-).  For each job id, a group of three radio buttons is
+rendered, followed by the job summary.  Page template substitutions
+are used to set the name attribute of the radio buttons to the job id.
+The value of the first radio button in each group is not specified;
+the HTML specification defines that if this button is checked (which
+it is by default) the value defaults to "on".  The other two radio
+buttons in the group specify "approve" and "discard" as their values,
+and this is what is sent to Zope when they are checked.  (Being radio
+buttons, at most one button in each group can be selected at any time;
+different groups are independent from each other.)
+
+<p>When the Submit button at the bottom of the page is pressed, the
+selected value for each group of radio buttons is sent to to the
+action() method of the AppriveJobsView class.  (The browser sends it
+to the "approve" view, which is mapped to the "action" button by the
+configuration code above.)  The action() method iterates over the keys
+of the form (which are of course the field names), ignoring keys that
+aren't the job id for an existing job.  Then for each valid job id,
+the value from the form is inspected, and the appropriate action is
+taken: to approve a job, its approve() method is called; to discard a
+job, it is deleted from the job list.  If the action code isn't either
+'approve' or 'discard', nothing is done to the job, and it remains in
+the PendingApproval state.
+
+<p>Finally, the action() method directs the browser back to the view
+named approveForm.html.  As an aside, note that this means we can't
+just change the name of that form in the configuration file; we'd have
+to change it in the code of the action() method too.
+
+
 <h2>Page Templates</h2>
 
 <p>In the previous section there was a bit of introduction to page
@@ -382,13 +447,5 @@
 
 <p>...
 
-
-<h2>Tying it all together with the configuration file</h2>
-
-<p>Finally, we need to tell Zope what's what with all these classes -
-how they are supposed to interact with each other and what permissions
-to allow.
-
-<p>...
 
 </body>