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

[Guido van Rossum]

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

Modified Files:
	Tutorial.html 
Log Message:
Got rid of all the outdated material.  Still to do is the description
of the approval view.


=== Packages/JobBoardEx/Tutorial.html 1.12 => 1.13 ===
 
     <p><li>Providing a configuration file (<a
-    href="JobList.zcml">JobList.zcml</a>) to give Zope the recipe of
-    how all these things fit together, and modifying Zope's master
+    href="configure.zcml">configure.zcml</a>) to give Zope the recipe
+    of how all these things fit together, and modifying Zope's master
     product configuration file (products.zcml) to let it include our
     configuration file.</li>
 
@@ -235,55 +235,142 @@
 </pre>
 
 
-<hr><b>XXX The rest is historical fiction</b>
+<h2>Job Workflow</h2>
 
-<h4>Editing a Job with JobEditView</h4>
+<p>Employers need to be able to submit jobs to the job board.  The
+"work flow" for submitting a job is as follows.  First the employer
+submits the text for the job; we provide a conventional HTML form for
+editing the text, a preview page where you can see how your job will
+be rendered, and an action that enters the job in the JobList.
+
+<p>Initially a job has the PendingApproval state, which means that it
+is excluded from the default view (so job seekers won't see unapproved
+jobs).  Jobs in this state only show up on a special "approval" view,
+accessible only to site managers.  Once a job is approved, its state
+changes to Approved, and it shows up in the default view.
+
+<p>There are all sorts of possible enhancements to this work flow,
+where e.g. a site mananger could bounce a job back to the submitter
+with a request to change certain things, or a site manager could edit
+a job.  Adding these is left as an exercise.
+
+
+<h2>Submitting New Jobs</h2>
+
+<p>Most of the action for submitting and previewing a new job is in
+the page templates <a href="JobCreateView.pt">JobCreateView.pt</a> and
+<a href="JobPreviewView.pt">JobPreviewView.pt</a>, but unlike the
+default view for Job and JobList, there is also Python code involved,
+in the class <a href="JobCreateView.py">JobCreateView.py</a>.
+
+
+<h4>The JobCreateView class</h4>
+
+<p>This class has three attributes: the two forms, named form and
+form2, and a method action().  The argument list of the action()
+method deserves some attention: the four arguments are named for the
+corresponding fields in the request form.  When form sends its
+contents to the action() method using an HTTP request, Zope magically
+extracts the form field values from the request and passes them to the
+corresponding arguments.  In our example, all arguments have a default
+value of '', meaning that it's okay for a form field to be missing.
+If no default value is given to a method's argument, that means that
+the corresponding form field must be filled in; if it is not, Zope
+will issue an error and the method will not be called.  (This isn't
+generally sufficient for validation, of course; the action() method
+would be the place to put your validation code.)
+
+<p>The JobCreateView class is derived from the BrowserView class.
+This is a convenience class supplied by Zope that provides a
+constructor.  This constructor sets self.request to the request
+structure (an object that answers questions related to the HTTP
+request), and sets self.context to the "context object".  In our case,
+since the JobCreateView is a view on the JobList object, self.context
+is set to the JobList instance.  The essence of the action() method is
+in the two statements that create a new Job instance from the form
+fields, and calls the JobList's add() method to add it to the job
+list.  (The job id returned by add() is ignored here.)
+
+<p>Finally, the action() method must send a response to the browser.
+There are different ways to do that.  The example uses a simple
+redirection that sends the browser back to the job list.
+
+<p>A more realistic action() method should include validation code,
+e.g. checking that all fields are filled in, and perhaps attempting
+some syntactic checking on the submitter field (which should be a
+valid email address).
+
+
+<h4>Page Templates Used by JobCreateView</h4>
+
+<p>The page template <a href="JobCreateView.pt">JobCreateView.pt</a>
+contains the HTML form where employers edit the text for a job.  It's
+a straightforward HTML form that in fact contains no Page Template
+directives.  The action for this form is the next page template:
+
+<p>The page template <a href="JobCreateView.pt">JobCreateView.pt</a>
+shows a preview version of the job, before it is submitted.  You must
+click a button to submit it.  Here's how it works: in the top part of
+the page, the job data from the request form is rendered.  Page
+template directives reference the summary field in the request as
+"request/summary", and so on.  Below this, a form with hidden input
+fields and a visible Submit button is used to pass the field values
+from the request to the action() method.
 
-<p>The JobEditView class, in association with the JobEditView.pt and
-JobPreviewView.pt page templates, defines the process of editing a
-Job.  This starts on the page produced by JobEditView.pt.
-
-<p>If you look
-at this code, you'll see relatively normal HTML with some extra "tal"
-information buried in the tag fields.  Leaving that aside for the time
-being, we're primarily interested in the form's "action" and the
-"submit" inputs (the buttons).  The "action" is set to "", which means
-(to the browser) "back to the object that created the page." In this case,
-that means the JobEditView object.  When you combine this fact with the
-"submit" inputs, for "Preview" and "Cancel," we produce the desired
-results.
-
-<p>The name for the preview button is "preview:method".  This
-tells Zope that when that button is pressed it should call a method
-named "preview," and since "action" is "", that indicates that Zope
-should call the preview method on the page's current object, a
-JobEditView.  So it calls JobEditView's preview() method, which you can
-see will produce another page, created with the expression
-PageTemplateFile('JobPreviewView.pt').  If instead you press the
-"cancel" button, the name associated with that button is
-"cancel:method" so the JobEditView cancel() method will be
-called.  Note that this is a regular def method.
-
-<p>The submit() method is called from the JobPreviewView.pt in the
-same way.  The same edit() and cancel() methods are also called from
-JobPreviewView.pt.
-
-<p>You can see that the view classes don't just display pages, but
-they also contain control logic that will respond to actions on those
-views.  If you are thinking in terms of model-view-controller, what you
-see here is only a partial fullfillment of that idea.  True, as much of
-the "controller" aspect as possible is built into the standard Zope
-code (and is thus "under the covers" from the perspective of our
+
+<h4>Configuration Directives</h4>
+
+<p>The JobCreateView class and its views are tied together with the
+following configuration code:
+
+<pre>
+&lt;browser:view for=".IJobList."
+              factory=".JobCreateView."
+              permission="Zope.ManageContent"
+              >
+
+  &lt;browser:page name="createForm.html"  attribute="form" />
+  &lt;browser:page name="previewForm.html" attribute="form2" />
+  &lt;browser:page name="create"           attribute="action" />
+
+&lt;/browser:view>
+</pre>
+
+<p>This tells Zope that there is a view on objects that implement the
+IJobList interface whose factory class is the JobCreateView class.
+This view defines three different pages.  For each page, a page
+subdirective gives the name of the view (as seen by the browser) and
+the attribute of the JobCreateView class that implements this view.
+
+
+<h4>Remarks</h4>
+
+<p>For simplicity, this example cheats a little.  The user will
+normally want to flip back and forth between the edit form and the
+preview page.  Rather than providing a separate button labeled "Edit",
+we start the preview page with the admonition to use the browser's
+"Back" button to re-edit the data.  But it is certainly possible to
+set things up so that the preview form has a button back to the edit
+form.  A common approach to this would be to have buttons labeled Next
+and Previous at the bottom of each page, in the style of Microsoft
+"wizards".
+
+<p>You can see that the views don't just display pages, they also
+contain control logic that will respond to actions on those views.  If
+you are thinking in terms of model-view-controller, what you see here
+is only a partial fullfillment of that idea.  True, as much of the
+"controller" aspect as possible is built into the standard Zope code
+(and is thus "under the covers" from the perspective of our
 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
-include the control code, such as the cancel() and submit() methods,
-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 class, because doing so leads you down the Visual Basic path,
-which inevitably produces applications that are problematic to
-maintain and that don't scale well.
+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
+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
+class, because doing so leads you down the Visual Basic path, which
+inevitably produces applications that are problematic to maintain and
+that don't scale well.
 
 
 <h2>Page Templates</h2>