.. index:: introduction, z3c.*, Philipp von Weitershausen Introduction ************ In the last nine months or so, not long after Philipp von Weitershausen published the second version of *Web Component Development with Zope 3*, Zope 3 underwent a massive change and restructuring. The application once known as Zope 3 split into a hundred peices in favor of "Zope 3 the framework". Each component of Zope became a separate package distributed via eggs with ever-complex dependency trees. Another big change for Zope in the past 9 months has been the creation of numerous community maintained packages which are not considered "zope core". These are the z3c.* packages. Written predominantly by rebelious Zope 3 hackers looking to make Zope even more powerful than before, the z3c.* packages quickly took center stage. Unfortunately for the rest of us, those who knew how to use the z3c.* packages were too busy being incredibly productive and successful that they never wrote any new books, tutorials, or easy to follow documentation. This document aims to assuage the woes of those still doing things the old way by providing a humble introduction to z3c.*. .. index:: Web Component Development with Zope 3, Philipp von Weitershausen Who Should (Not) Read this Tutorial =================================== This tutorial was primarily written for people who have already had some experience with Zope 3. The reader is assumed to have a certain level of understanding regarding basic zope paradigms: the component architecture, ZCML configuration, tal page templates, and of course python. Fortunately, there are already great books out there that cover these topics. If you haven't done so already, I highly recommend taking a look at Philipp von Weitershausen, book *Web Component Development with Zope 3*, and using it as a supplement to this tutorial. Baiju M has also written a great online book detailing the ins and outs of the component architecture, which you can find here: http://www.muthukadan.net/docs/zca.html Getting Started *************** .. index:: virtual environment, virtualenv.py, sandbox Setting Up a Virtual Environment ================================ Before we start working on our application, it is always a good idea to set up a python environment that is separate from the system python that came preinstalled with whatever linux distribution we are using (in my case, Ubuntu Gutsy). By creating a "virtual" python environment, we can easily avoid many problems associated with system python like broken packages, conflicting dependencies, etc. A virtual python environment can be easily created using the *virtualenv.py* script available from http://svn.colorstudy.com/virtualenv/trunk/virtualenv.py. For documentation about what this script does, check out the pypi page at http://pypi.python.org/pypi/virtualenv. Download this script to your home directory and create a new environment called sandbox:: $ wget http://svn.colorstudy.com/virtualenv/trunk/virtualenv.py ~/ $ python ~/virtualenv.py sandbox Alternatively, you can put this environment wherever you'd like and call it whatever you want. This folder now has a bin directory with a new python executable and easy_install script. It also comes with a bash script for placing your shell into the new environment so you do not have to type full path to run the environment's python. Run this with:: $ cd sandbox $ source bin/activate After this you can see that it worked:: (sandbox)$ which python /home/pcardune/sandbox/bin/python From this point on, anywhere you see a shell command to run, it is assumed you have the virtual environment activated. .. index:: zopeproject, Philipp von Weitershausen, easy_install Using zopeproject ================= It's helpful to start with a basic application skeleton so you don't have to worry about writing all intial configuartion from scratch. Fortunately, Philipp von Weitershausen has written an excellent tool called zopeproject_ for doing this. zopeproject can be installed using ``easy_install``. Simply type:: $ easy_install zopeproject Next we'll create a new project called zcontact. zopeproject creates all the basic configuration you'll need to be able to immediately start an empty zope application and log in with an administrative account. You will be asked for an intial username and password for the administrative account (which can be changed at any time) along with a location for installing the necessary components:: $ zopeproject zcontact Enter user (Name of an initial administrator user): manager Enter passwd (Password for the initial administrator user): zcontact Enter eggs_dir (Location where zc.buildout will look for and place packages) ['/home/pcardune/buildout-eggs']: eggs This step may take several minutes as a lot of code needs to be downloaded and some of it compiled. While you wait, I highly recommend glancing over the zopeproject_ documentation to get a better idea of what it is doing. .. index:: paster Starting the Server =================== With that finished, you can jump right in and start your nascent application which will run on port 8080 by default.:: $ cd zcontact $ ./bin/paster serve deploy.ini Starting server in PID 23818. serving on http://127.0.0.1:8080 You should now get an empty zope screen that looks like the one below: .. image:: images/screen1.png The ``deploy.ini`` file given to the ``./bin/paster`` command specifies options for running the server such as port settings. ``zopeproject`` also generates a ``debug.ini`` file that includes a WSGI filter for handling errors. If you ever run into errors, you can use the ``debug.ini`` configuration to inspect the code, as it is running, in your web browser! .. index:: security, role, grantAll Adjusting Security ================== To Keep Things Simple (Stupid) in this tutorial, we will adjust the permissions generated by ``zopeproject`` so we don't have to worry about them later. Add the following lines to the ``site.zcml`` file in the root directory of your application: .. code-block:: xml This gives completely anonymous users access to everything with no restrictions. .. index:: interface, implementation Creating a Simple Interface and Implementation ============================================== Before we can jump into the world of z3c.* packages, we'll have to have some object that we want to play with. Since ZContact is supposed to be a contact manager, let's start with a contact object. To Keep It Simple (Stupid), we will just have two fields, a first name and a last name. .. Note:: All source code lives in the ``zcontact/src/zcontact`` folder so that ``zcontact/src/zcontact/interfaces.py`` could be imported as ``import zcontact.interfaces``. The IContact Interface ---------------------- Open up ``interfaces.py`` and add the following: .. code-block:: python import zope.interface import zope.schema class IContact(zope.interface.Interface): """A simple contact.""" firstName = zope.schema.TextLine( title=u"First Name", required=True) lastName = zope.schema.TextLine( title=u"Last Name", required=True) The Contact Implementation -------------------------- Now we can make our quick implementation. Open up ``contact.py`` and add the following: .. code-block:: python import zope.interface from zope.schema.fieldproperty import FieldProperty import interfaces class Contact(object): """See ``zcontact.interfaces.IContact``.""" zope.interface.implements(interfaces.IContact) firstName = FieldProperty(interfaces.IContact['firstName']) lastName = FieldProperty(interfaces.IContact['lastName']) Security Registration for the Contact Class ------------------------------------------- We also need to register the ``Contact`` class in zcml and set permissions for accessing the attributes. Just add the following to the ``src/zcontact/configure.zcml`` file: .. code-block:: xml With that done, we can jump into views that use z3c.* components. .. Caution:: Don't forget, in the real world you would write unit tests for this code first, if only to ensure that the ``Contact`` class really does implement the ``IContact`` interface.