[Checkins] SVN: grok/trunk/doc/tutorial_outline.txt Sketch out the tutorial.

[Martijn Faassen]

Log message for revision 73405:
  Sketch out the tutorial.
  

Changed:
  A   grok/trunk/doc/tutorial_outline.txt

-=-
Added: grok/trunk/doc/tutorial_outline.txt
===================================================================
--- grok/trunk/doc/tutorial_outline.txt	2007-03-20 23:57:19 UTC (rev 73404)
+++ grok/trunk/doc/tutorial_outline.txt	2007-03-20 23:57:43 UTC (rev 73405)
@@ -0,0 +1,230 @@
+================
+Tutorial outline
+================
+
+This is not the tutorial itself, but a sketch of what the tutorial
+could look like. This hopefully inspires people to contribute to the
+tutorial. The structure of the tutorial is very much use-case driven
+and about getting things done. This means we tend to discuss the
+component architecture itself very late.
+
+Note that while I've indicated the overal aim of sections in chapters,
+that doesn't mean a chapter is absolutely decicated to a single
+topic. If for instance in the course of explaining search it becomes
+important to override traversal, it can be discussed right there.
+
+Main tutorial
+=============
+
+Getting started with Grok
+-------------------------
+
+This section aims to get a beginner up and running with Grok, using
+grokproject. It doesn't really go into any code yet, except to
+describe what grokproject creates.
+
+  * Setting up grokproject
+
+  * Creating a grok project
+
+  * Starting up Zope
+
+  * An empty Grok project
+
+Showing pages
+-------------
+
+We get beginners up to speed with writing view logic in Grok. This is
+basically the first thing beginners want - just get some HTML on the
+screen. Basic templating, supplementing templating with view-level
+methods, and various basic interaction patterns. Models are still out
+of scope. Armed with this knowledge people should already be able to
+write simple web applications with Grok, if at least they don't have
+to worry much about storing data.
+
+  * Publishing a simple web page
+
+  * A second view
+
+  * Making our page dynamic
+
+  * Static resources for our web page
+
+  * Using view methods
+
+  * Generating HTML from Python
+
+  * Completely Python-driven views
+
+  * Doing some calculation before viewing a page
+
+  * Reading URL parameters
+
+  * Simple forms
+
+Models
+------
+
+Once we know how to show things, we need to go into what we're
+actually showing: the model. This involves view/model separation,
+dealing with the ZODB and persistence, and constructing applications
+from models and containers. 
+
+Note that we also include some more advanced view use cases which only
+tend to become relevant with more complicated applications (such as
+redirection).
+
+  * A view for a model
+ 
+  * Storing data
+ 
+  * Redirection
+
+  * Showing the value in the form
+
+  * The rules of persistence
+ 
+  * Containers
+
+Forms
+-----
+
+Now that we've seen the form and storage basics, we go a step further
+and show the power of automatic form generation from schemas.
+
+Building on the patterns we've seen before, we develop a simple CRUD
+application with an overview screen and add and edit forms. This will
+also include at least a glance at interfaces in the context of
+schemas.
+
+Search
+------
+
+We have a way for a user to enter information. Now we need to build an
+application that does something with it. We extend our CRUD
+application with indexing and search, using the catalog.
+
+By now the application should also be advanced enough to explain
+overriding traversal, for instance to enable simple 'tag' based
+browsing mechanism based on search.
+
+This will also lead into a brief introduction of utility lookup and
+sites.
+
+XXX setting up the catalog is easy now, but it can be automated a bit
+    further still in Grok.
+
+XXX We probably need hurry.query. This needs some work on the Grok end
+    to expose this nicely.
+
+Custom widgets
+--------------
+
+The defaults are never enough when it comes to web forms. This is a
+nice point to introduce making your own custom form widgets.
+
+We will also show how you can use AJAX with Grok so you can give your
+widget some dynamic behavior.
+
+XXX we need to make it easy to make widgets in Grok.
+
+XXX this needs work on the Grok end to at least expose JSON, and perhaps
+     we need to ship with a 'recommended' Javascript library.
+
+Security
+--------
+
+Explain how Grok allows you to protect your views. In the course of
+this we also need to explain a bit about Zope 3's user authentication
+system, as we need users to test this with.
+
+XXX We need to flesh out user authentication issues in Grok.
+
+Extending our application
+-------------------------
+
+We show one of Zope 3's main strengths: we create a separate codebase
+in a completely separate project that extends the first. Then we
+demonstrate many extension patterns Zope 3 offers:
+
+  * creating an extension project (using buildout and SVN externals?)
+
+  * a new look for old models (skins)
+
+  * the benefit of interfaces
+
+  * events
+
+  * adapters
+
+Appendices
+==========
+
+While these topics may not presuppose a lot of knowledge, we probably
+do not want to scatter all of this through the tutorial itself so as
+not to distract from the main story (though we may change our minds if
+it seems to come out naturally).
+
+Explicit configuration
+----------------------
+
+Should give an introduction on the principles of Grok: explicit
+configuration using directives, with defaults so you can leave them
+off if you follow the grok patterns.
+
+I'm not sure yet whether this can be part of the main flow of the
+text. We at the very least will refer to this at some point in the
+text though, and we need to refer people to this for more information.
+
+The Component Architecture
+--------------------------
+
+Explain how many bits and pieces we've seen so far are actually
+aspects of the component architecture.
+
+Automatic testing
+-----------------
+
+A brief introduction to automatic testing. Introduce how to unit test
+and functional test with doctests.
+
+XXX We probably need to do some development work on a test grokker.
+
+XMLRPC 
+------
+
+Show how to do XMLRPC with Grok.
+
+Extending grok
+--------------
+
+Grok can be extended using Grokkers. Explain how to do it here.
+
+Development issues
+------------------
+
+We describe best practices on how to manage your code when developing
+with Grok. This touches topics like setup.py, buildout, and also
+version control systems.
+
+ * Pulling in new dependencies from the Cheeseshop.
+
+ * Putting your project into SVN
+
+ * Uploading your project to the Python Cheeseshop
+
+Items I'm not sure where to place yet
+=====================================
+
+These items will need to find a place in the main narrative or the
+appendices. They're listed here so we don't forget about them:
+
+  * Constructing urls with view.url()
+
+  * base classes
+
+  * Events
+
+  * Showing error pages.
+
+  * Discussion on viewlets/portlets.