In the previous chapter, we covered a lot of background information including how to install Python, Distribute, and PIP.
We introduced Buildout and at the end of the chapter, we saw our first Buildout configuration file.
In this chapter, we will create our first Plone site and learn how to customize its navigation and available content types.
In this chapter, you will learn:
More about Buildout
Adding a Plone site
Customizing navigation
Adding new content types
According to the index page on the Python Package Index (PyPI), (http://pypi.python.org/pypi/zc.buildout/1.5.0b2), Buildout is a:
"System for managing development buildouts"
Since its inception, Buildout has grown to become an elaborate system for building software for both development and production use. You can use it to install a single Python package or a complex application.
Buildout does very little by itself; additional functionality is provided by add-ons called recipes. And with over 200 recipes available from the PyPI, you can use it to do just about anything.
Buildout's configuration file format is based on the Windows INI-style definition, described here: http://en.wikipedia.org/wiki/INI_file.
If you read the Wikipedia entry here, you will notice INI-style files are
made up of parameters of the form name=value.
These parameters are separated by an equals sign (=), and can be grouped into
sections of the form [section].
With that in mind, let's now analyze the configuration file
01-background-python.cfg from the previous chapter.
[buildout] parts = python-buildout [python-buildout] recipe = infrae.subversion location = src urls = http://svn.plone.org/svn/collective/buildout/python/src/ python-buildout
A Buildout configuration file must define a buildout
section:
[buildout]
The buildout section must contain a
parts parameter. In the case of
01-background-python.cfg, we add the
python-buildout section to the parts
parameter:
parts = python-buildout
Parts provide a way to divide Buildout's work into logical units. Often, a recipe is used to do the actual work.
In the case of 01-background-python.cfg, we used
the infrae.subversion recipe
(http://pypi.python.org/pypi/infrae.subversion) to check out
the Python buildout from the collective repository
(http://svn.plone.org/svn/collective):
[python-buildout] recipe = infrae.subversion
Next, we specify that we want the checkout to occur in the
src directory (instead of the parts
directory, which is the default) by setting the location
parameter:
location = src
Finally, we set the value of the urls parameter to the
following:
urls = http://svn.plone.org/svn/collective/buildout/python/src/ python-buildout
This parameter's value takes two arguments, separated by a space. The
first argument is the source URL, that is the checkout; the second is the
target directory, that is where to put the checkout (within the
src directory).
To learn more about this recipe's configurable parameters, read the documentation available on the Python Package Index on http://pypi.python.org/pypi/infrae.subversion.
As you may recall, we used a "global" installation of Buildout to run the first buildout, as follows:
$ buildout c 01-background-python.cfg
This step performs a checkout of the Python buildout, and it works because
the buildout command is in our path.
Then we used that same "globally-installed" Buildout to run the Python buildout, as follows:
$ buildout c src/python-buildout/python24.cfg
Now that the Python buildout is complete, we can use the resultant Python 2.4 installation for whatever we like, including bootstrapping a Plone 3.3 buildout.
Further, we do not have to use the "global" Buildout anymore, because bootstrapping will install another version of Buildout within the Plone buildout we are about to create.
So from now on, we will run the buildout command as:
$ bin/buildout
In the examples given in this book, you will notice two files in the
buildout directory:
buildout.cfg02-site-basics-plonesite.cfg
The buildout.cfg file contains everything you need to
install Plone, assuming you have Python 2.4 installed (which you do, if you have
read Chapter 1).
It looks like this:
[buildout]
extends = http://dist.plone.org/release/3.3.5/versions.cfg
versions = versions
parts =
zope2
instance
[zope2]
recipe = plone.recipe.zope2install
url = ${versions:zope2-url}
[instance]
recipe = plone.recipe.zope2instance
zope2-location = ${zope2:location}
user = admin:admin
eggs = Plone
On the second line, you will notice an extends
parameter with the following value:
http://dist.plone.org/release/3.3.5/versions.cfg.
Here, we specify that our buildout should use the section and parameter
definitions from the versions.cfg file.
One of the core features of Buildout is to be able to extend functionality from one configuration file to another.
The versions.cfg defines a single section,
called versions, with many parameters:
[versions] # Buildout infrastructure plone.recipe.zope2install = 3.2 plone.recipe.zope2instance = 3.6 plone.recipe.zope2zeoserver = 1.4 setuptools = 0.6c11 zc.buildout = 1.4.3 zc.recipe.egg = 1.2.2 # Zope zope2-url = http://www.zope.org/Products/Zope/2.10.11/Zope-2.10.11-final.tgz # External dependencies Markdown = 1.7 PIL = 1.1.6 elementtree = 1.2.7-20070827-preview feedparser = 4.1 python-openid = 2.2.4 simplejson = 2.0.9 # Plone release Plone = 3.3.5 Products.ATContentTypes = 1.3.4 Products.ATReferenceBrowserWidget = 2.0.5 Products.AdvancedQuery = 3.0 Products.Archetypes = 1.5.15 …
For most of these, the parameter name is a package name, and the value is a release number.
Next, we set the versions parameter, to ensure
the versions section from
versions.cfg is used in our buildout:
versions = versions
In the zope2 section, we use the
plone.recipe.zope2install recipe to install Zope 2. We set the
value of the url parameter to
${versions:zope2-url}.
In doing so, we are using variable substitution, which is another one of Buildout's core features; you can read more about that feature on http://pypi.python.org/pypi/zc.buildout#variable-substitutions.
The important points are:
The
${}notation is used to specify a variableA variable consists of a section name and parameter name separated by a colon
So the ${versions:zope2-url} variable is replaced with
the value of the zope2-url parameter from the versions
section.
Next, in the instance section, we use the
plone.recipe.zope2instance recipe to install a Zope 2
instance.
A few years ago (around the mid-2000s), it was very common to download the Zope 2 tarball (http://www.zope.org/Products/Zope/2.10.11/Zope-2.10.11-final.tgz) and perform the following steps by hand:
Manually extract it and run
configure, make, andmake installto install Zope 2Manually create a Zope 2 instance with
mkzopeinstance.pyManually install old-style products into the Zope 2 instance
Productsdirectory
But a few things have supplanted this technique:
Buildout is now used to download and install Zope 2
Buildout is now used to create instances
Buildout is now used to add Python packages to the
sys.path
The plone.recipe.zope2instance recipe requires
the zope2-location and user
parameters to be set.
The value of the zope2-location parameter is set to the
(hidden) location parameter in the
zope2 section:
${zope2:location}
This is later substituted with the value of the Zope 2 software installation:
parts/zope2
The user parameter takes two arguments separated by a
colon (:). It should be set to the Zope 2 administrator's username and
password:
admin:admin
Of course, do not forget to change the password; we will get to that
later. Finally, we set the value of the eggs parameter
to Plone.
One of the most notorious issues with running Plone is that it requires the Python Imaging Library (PIL) located at http://www.pythonware.com/products/pil/. If you don't have PIL installed, you don't have a working Plone site.
Note
Why is PIL a problem?
It is packaged in such a way that it is difficult to use with other packages.
To make using PIL with Plone easier, you can try one of these techniques: using the Python buildout, using PIP, or adding PIL to your buildout.
As covered in Chapter 1, the Python buildout (http://svn.plone.org/svn/collective/buildout/python/) downloads and installs PIL for you.
You can use PIP to install the following version (re-packaged by core developer Hanno Schlichting): http://dist.plone.org/thirdparty/PIL-1.1.7.tar.gz.
This is done using the following command:
$ pip install http://dist.plone.org/thirdparty/PIL-1.1.7.tar.gz
You can add PIL to your buildout by adding the PILwoTk URL to
the find-links parameter (in the buildout
section) and the PILwoTk package name to the eggs
parameter (in the instance section). In pil.cfg , we
have:
[buildout]
extends = http://dist.plone.org/release/3.3.5/versions.cfg
versions = versions
parts =
zope2
instance
find-links =
http://dist.plone.org/thirdparty/PILwoTk-1.1.6.4.tar.gz
[zope2]
recipe = plone.recipe.zope2install
url = ${versions:zope2-url}
[instance]
recipe = plone.recipe.zope2instance
zope2-location = ${zope2:location}
user = admin:admin
eggs =
Plone
PILwoTk
Now when Buildout runs, assuming you have satisfied PIL's dependencies, PIL will be installed into the buildout.
Note
What is PILwoTk?
PILwoTk is a re-packaging of PIL by Jim Fulton of Zope Corporation. The package name is short for PIL without Tk (PILwoTk) and the source code has been modified to remove the Tk dependency, which Plone does not use. Because of the unique package name, using PILwoTk also avoids the possibility of downloading a potentially inoperable version of PIL from the Python Package Index.
In Chapter 1, we went to great lengths to install Distribute, PIP, and Buildout.
Now we will use the Python 2.4 binary we created with the Python buildout to bootstrap a Plone 3.3 buildout, except of course in Windows, where you must use the binary distribution of Python 2.4.4 that we installed (because it is not that easy to compile Python on Windows).
If you were to run the following now:
$ src/python-buildout/python-2.4/bin/python bootstrap.py $ bin/buildout
You are likely to see a message like this from the infrae.subversion recipe:
If you sure that these modifications can be ignored, remove the checkout manually: rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/develop-eggs rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/python-2.4 rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/eggs rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/parts rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/downloads rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/.installed.cfg rm -rf /Users/aclark/Developer/plone-site-admin/buildout/src/python-buildout/bin …
To prevent this from happening, remove the,
installed.cfg file from the root directory of the
buildout:
$ rm .installed.cfg
This causes Buildout to forget about the Python Buildout. Otherwise, it
would require us to remove the src/python-buildout
directory, which we do not want to do.
$ bin/buildout
$ bin/buildout Creating directory '/Users/aclark/Developer/plone-site-admin/buildout/eggs'. Getting distribution for 'plone.recipe.zope2install==3.2'. Got plone.recipe.zope2install 3.2. Getting distribution for 'plone.recipe.zope2instance==3.6'. Got plone.recipe.zope2instance 3.6. Getting distribution for 'zc.recipe.egg==1.2.2'. Got zc.recipe.egg 1.2.2. Uninstalling instance. Updating zope2. Updating fake eggs Installing instance. Getting distribution for 'Plone==3.3.5'. … Generated script '/Users/aclark/Developer/plone-site-admin/buildout/bin/instance'. $
In the output from the previous Buildout, you may notice a lot of syntax errors of the form:
Installing instance.
Getting distribution for 'Plone==3.3.5'.
File "build/bdist.macosx-10.6-i386/egg/Products/CMFPlone/skins/cmf_legacy/TitleOrId.py", line 11
return title
SyntaxError: 'return' outside function
File "build/bdist.macosx-10.6-i386/egg/Products/CMFPlone/skins/plone_content/link_redirect_view.py", line 24
return context.REQUEST.RESPONSE.redirect(context.getRemoteUrl())
SyntaxError: 'return' outside function
File "build/bdist.macosx-10.6-i386/egg/Products/CMFPlone/skins/plone_deprecated/cropText.py", line 9
return context.restrictedTraverse('@@plone').cropText(text, length, ellipsis='...')
You can safely ignore these.
Note
Why ignore syntax errors?
The short answer is because they are erroneous.
The medium length answer is because they are erroneous, and are caused by Buildout trying to install packages that contain Python scripts which are intended for use only by Zope 2.
The long answer is that Buildout
uses Distribute to install packages. During the installation process,
Distribute attempts to compile the Python source code contained within
the package to create Python byte code (.py to
.pyc). Plone and many of its dependencies (and add-ons)
contain old-style Python scripts that end with .py
and are located inside CMF skin layer directories. Zope 2 uses these
Python scripts during normal operation (for example, when a page
template refers to one). However, Distribute thinks they are Python
source code and tries to compile them. The compilation fails because
Zope 2 does not require these scripts to have valid syntax. For example,
a Python script in Zope 2 may contain return foo. To
Python, this is a syntax error because the return
statement is not inside a function definition, for example, def
foo():.
When you start Plone for the first time, there is no Plone site in the database.
To fix the problem just mentioned, run:
bin/instance fg
You should see:
/Users/aclark/Developer/plone-site-admin/buildout/parts/instance/bin/runzope -X debug-mode=on 2010-03-23 10:49:27 INFO ZServer HTTP server started at Tue Mar 23 10:49:27 2010 Hostname: localhost Port: 8080 … 2010-03-23 10:49:41 INFO Zope Ready to handle requests
You can add a Plone site in the Zope Management Interface (ZMI) by following these steps:
Browse to
http://localhost:8080/manage.Enter the username and password specified in the
buildout.cfgfile. For example, user: admin, password: admin.Add a Plone site from the Add menu on the upper-right.
You should see:
Fill in the form as follows:
Enter Plone as the site Id
Click on Add Plone Site
You should see:
Now, you can browse to
http://localhost:8080/Plone.
Now might be a good time to change the top-level Zope user's password. To do that:
Browse to
http://localhost:8080/manage.Click on acl_users | users | Password.
Type in your password in the Password and Confirm password fields, and then click on Update Password.
You should see:
Later, in Chapter 7, Security, we will discuss more things you can do to secure your site.
If you would like to automate the process of adding a Plone site, there is the collective.recipe.plonesite recipe (http://pypi.python.org/pypi/collective.recipe.plonesite).
In 02-site-basics-plonesite.cfg we have:
[buildout] extends = buildout.cfg parts += plonesite [plonesite] recipe = collective.recipe.plonesite
We extend the functionality of buildout.cfg by setting
the value of the extends parameter in the buildout
section to buildout.cfg.
Then we add the plonesite section by expanding the
value of the parts parameter to include
plonesite (by using the += syntax instead
of =).
The expansion concept is an important one. It is similar to the
extends parameter, which tells Buildout to include all
sections and parameters from another configuration file. The
+= syntax tells buildout to add the new value (not replace)
to the current value.
That means the parts list becomes:
zope2instanceplonesite
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run:
$ bin/buildout c 02-site-basics-plonesite.cfg
You should see:
$ bin/buildout -c 02-site-basics-plonesite.cfg Getting distribution for 'collective.recipe.plonesite'. Got collective.recipe.plonesite 1.3. Updating zope2. Updating fake eggs Updating instance. Installing plonesite. /Users/aclark/Developer/plone-site-admin/buildout/parts/zope2/lib/python/zope/configuration/xmlconfig.py:323: DeprecationWarning: zope.app.annotation has moved to zope.annotation. Import of zope.app.annotation will become unsupported in Zope 3.5 __import__(arguments[0]) Retrieved the admin user A Plone Site already exists and will not be replaced
This is because we have already added a Plone site manually. Try adding
the site-id parameter with a different value, such
as:
[plonesite] recipe = collective.recipe.plonesite site-id = Plone2
$ bin/buildout c 02-site-basics-plonesite.cfg
You should see:
$ bin/buildout -c 02-site-basics-plonesite.cfg Uninstalling plonesite. Updating zope2. Updating fake eggs Updating instance. Installing plonesite. /Users/aclark/Developer/plone-site-admin/buildout/parts/zope2/lib/python/zope/configuration/xmlconfig.py:323: DeprecationWarning: zope.app.annotation has moved to zope.annotation. Import of zope.app.annotation will become unsupported in Zope 3.5 __import__(arguments[0]) Retrieved the admin user /Users/aclark/Developer/plone-site-admin/buildout/eggs/Products.PlonePAS-3.12-py2.4.egg/Products/PlonePAS/setuphandlers.py:39: DeprecationWarning: portal_groups.getGroupIds is deprecated and will be removed in Plone 4.0. Use PAS searchGroups instead existing = gtool.listGroupIds() Added Plone Site Quick installing: [] Running profiles: [] Finished
Now start Plone:
$ bin/instance fg
Browse to
http://localhost:8080/Plone2. Alternatively, just remove the
Plone site from the ZMI and run the buildout again.
To do that, browse to
http://localhost:8080/manage, select the checkbox next to
the Plone site object, and click
on Delete.
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter), run Buildout, and then start Plone again:
$ bin/instance fg
You should now be able to browse to http://localhost:8080/Plone
again.
Note
Do not rename your Plone site object
Incidentally, even though the ZMI permits it, it's generally not a
good idea to rename your Plone site. While your site may appear to work
fine after a rename, there is a possibility that you may encounter an
unexpected error later. This is due to the fact that the ZODB may store
the object path (for example, /Plone) somewhere that
will not be updated when you rename the site, among other
reasons.
To read more about collective.recipe.plonesite,
visit
http://pypi.python.org/pypi/collective.recipe.plonesite.
As a current Plone user, you may be familiar with Plone's automated navigation system and how to configure your global sections, navigation portlet, and sitemap.
The automated navigation system is one of the first features people notice in
Plone. Create a new content item, and it will automatically appear in the global
sections, navigation portlet, and sitemap. If you do not like the default behavior,
you can browse to http://localhost:8080/Plone, click on Site Setup |
Navigation, and change it.
But sometimes the default features are not enough, or there is no adjustable setting for the customization you want to perform. When this happens, you have two choices:
Create the additional functionality yourself
Search for the right add-on to do it for you
Install and configure it
Regarding the first choice, you can read more about how to create additional functionality for Plone in "Professional Plone Development", Martin Aspeli, Packt Publishing.
Regarding the second choice, we will discuss that here. We will now cover some add-ons that customize the navigation portlet and global sections.
The collective.portlet.sitemap (http://pypi.python.org/pypi/collective.portlet.sitemap ) package aims to enhance the functionality of the default navigation portlet by displaying more than the current level of items, similar to the way the sitemap behaves (hence the name).
To demonstrate this:
Browse to
http://localhost:8080/Ploneand add a folder calledFooto the Plone site root (using the Add new… menu).Browse to
http://localhost:8080/Plone. Click on Manage Portlets | Portlets assigned here (on the left) Navigation | Start level, set it to 0, and click on Save.Browse to
http://localhost:8080/Plone. You should see:
Browse to
http://localhost:8080/Plone. Click on Foo and add a folder called Bar.Browse to
http://localhost:8080/Plone. Click on Foo | Bar and add a folder called Baz.
You should see exactly the same thing (in the navigation portlet). But with the collective.portlet.sitemap add-on installed, you would see this:
This is not to be confused with what happens when you navigate to Baz. With either the default navigation portlet or the collective.portlet.sitemap portlet, you would see this:
Now that we understand what the collective.portlet.sitemap add-on does, let us add it to our buildout so we can use it in Plone.
In 02-site-basics-sitemap.cfg, we have:
[buildout] extends = 02-site-basics-plonesite.cfg [instance] eggs += collective.portlet.sitemap zcml += collective.portlet.sitemap
We extend the functionality of the previous configuration file by setting the
value of the extends parameter (in the
buildout section) to
02-site-basics-plonesite.cfg.
Then we add the collective.portlet.sitemap package to the
eggs parameter of the instance section.
In addition to adding the package name to the eggs
parameter, we must add it to the zcml parameter,
also.
Note
Why do I have to configure Zope Configuration Markup Language (ZCML)?
The short answer is you do not, but in some cases you have to tell Buildout to do it for you.
The medium length answer is you do not, but in this case you have to tell Buildout to do it for you. This is because this package and many others do not support auto-configuration using z3c.autoinclude (http://pypi.python.org/pypi/z3c.autoinclude) yet.
As of Plone 3.3, developers and package maintainers are encouraged to
spare end users from having to perform this configuration by configuring
their packages to use the z3c.autoinclude entry
point.
The long answer is that ZCML is a core feature of the Zope Component Architecture ZCA, which is mainly implemented in the zope.component (http://pypi.python.org/pypi/zope.component) and zope.interface (http://pypi.python.org/pypi/zope.interface) packages (which Plone uses with the help of the Five module in Zope 2).
The basic idea behind configuring ZCML is that various components of an application (Plone in this case) should be configured to work together outside the Python code. Visit http://worldcookery.com/files/ploneconf05-five/step2.html for more information.
Any add-on package that makes use of the ZCA must be configured with the help
of ZCML to be used with Plone. End user exposure to this process is unfortunate,
and is likely to be better hidden in future releases of Plone, as more and more
add-on developers embrace the use of z3c.autoinclude. This is
one big reason (but not the only reason) Buildout became a de facto standard for
deploying Plone; nobody wants to manage ZCML configuration by hand.
The zcml parameter in the instance section of the
buildout.cfg file creates files such as
parts/instance/etc/package-includes/001-collective.portlet.sitemap.zcml,
which contains ZCML markup like this:
<include package="collective.portlet.sitemap" file="configure.zcml" />
This tells Five to load the components listed in the package's
configure.zcml file.
Remember that forgetting to configure ZCML in your buildout can mean the difference between a working and a (silently) non-working add-on in Plone.
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout -c 02-site-basics-sitemap.cfg
You should see:
$ bin/buildout -c 02-site-basics-sitemap.cfg Updating zope2. Updating fake eggs Updating instance. Getting distribution for 'collective.portlet.sitemap'. Got collective.portlet.sitemap 1.0.2.
Start Plone with:
$ bin/instance fg /Users/aclark/Developer/plone-site-admin/buildout/parts/instance/bin/runzope -X debug-mode=on 2010-03-07 18:58:34 INFO ZServer HTTP server started at Sun Mar 7 18:58:34 2010 Hostname: localhost Port: 8080 … 2010-03-07 18:59:00 INFO Zope Ready to handle requests
Now browse to
http://localhost:8080/Plone. Click on Site
Setup | Add-on
Products.
In the Products available for install section, you should see the following:
Check the box next to Portlet Navigation Extended 1.0.2 and click on Install.
This will replace the default navigation portlet with the extended navigation portlet and give you the "site map in a portlet" effect.
If you click on Manage portlets | Navigation Extended, you will notice the extra configurable options:
Note
Always be prepared for the worst!
One of the most important lessons you can learn when experimenting with add-ons like this is to never, ever, ever experiment on a production site or a site that you care about.
Add-ons frequently don't behave as expected. They can be incomplete, inconsistent, and otherwise unreliable (and even dangerous). Hence, do not install them unless you are absolutely sure that they are going to help, and not harm your site instead.
Another interesting add-on to explore (literally) is collective.portlet.explore (http://pypi.python.org/pypi/collective.portlet.explore).
This package enhances the default navigation portlet with JavaScript-enabled menus you can click to explore. It looks like this:
To install it, we just need to add the package name to the
eggs and zcml parameters of the instance
section.
We do just that in 02-site-basics-explore.cfg, where we
also extend the functionality provided by
02-site-basics-sitemap.cfg:
[buildout] extends = 02-site-basics-sitemap.cfg [instance] eggs += collective.portlet.explore zcml += collective.portlet.explore
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout -c 02-site-basics-explore.cfg
You should see:
$ bin/buildout -c 02-site-basics-explore.cfg Uninstalling instance. Updating zope2. Updating fake eggs Installing instance. Getting distribution for 'collective.portlet.explore'. Got collective.portlet.explore 1.0rc3. Generated script '/Users/aclark/Developer/plone-site-admin/buildout/bin/instance'.
Now start Plone:
$ bin/instance fg
Browse to http://localhost:8080/Plone, click on Site Setup | Add-on
Products, and you should see:
Now, check the box next to Explorer Portlet 1.0rc3 and click on Install.
Then browse to http://localhost:8080/Plone. Click
on Manage portlets (left or right column)
| Add portlet… |
Explorer Portlet and click on
Save.
So far, we have focused only on the navigation portlet. Let us now take a look at one of the more popular add-ons to enhance the global sections (also known as portal tabs).
The fancily-named add-on webcouturier.dropdownmenu adds JavaScript-enabled drop-down menus to Plone's global sections.
They look like this:
Just like before, to install this add-on we need to add the package name to
the eggs and zcml parameters in
the instance section of our buildout.
We do this in 02-site-basics-dropdownmenu.cfg, where we
also extend our previous efforts in
02-site-basics-explore.cfg:
[buildout] extends = 02-site-basics-explore.cfg [instance] eggs += webcouturier.dropdownmenu zcml += webcouturier.dropdownmenu
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout -c 02-site-basics-dropdownmenu.cfg Uninstalling instance. Updating zope2. Updating fake eggs Installing instance. Getting distribution for 'webcouturier.dropdownmenu'. Got webcouturier.dropdownmenu 2.0. Generated script '/Users/aclark/Developer/plone-site-admin/buildout/bin/instance'.
Start Plone:
$ bin/instance fg
Browse to
http://localhost:8080/Plone. Click on Site
Setup | Add-on Products and
you should see:
Check the box next to Dropdown menu 2.0 and click on Install.
After that, your global sections should "drop down" if they contain sub-items, for example, folders, pages, and so on.
We have now covered three examples of how to add and configure add-ons to enhance Plone's navigation features.
You can find and experiment with more add-ons at the Python Package Index (PyPI) (http://pypi.python.org/pypi). You can also visit http://plone.org and click on Downloads (http://plone.org/products).
While a search for navigation on PyPI turns up some useful results, it is somewhat of a mixed bag because it contains plenty of non-Plone results as well:
On the other hand, a plone.org search is guaranteed to have all Plone-specific results:
One thing is for certain there are seemingly endless amount of options to explore and you are encouraged to do so.
You may be familiar with Plone's content types and how to add content to your site. If not, please read Chapters 4, 5, and 6 of "Practical Plone 3", Veda Williams, Packt Publishing where this subject is covered in detail.
Often, it is necessary to add additional content types to provide a particular functionality. This is not to say adding a new content type is always a good idea, but some problems are particularly well-suited to being solved with the addition of a new content type.
For example, some folks like to blog with Plone. One of the simplest ways to start blogging with Plone is to use the Scrawl add-on (Products.Scrawl package), which creates a new blog content type (by copying the news item content type):
You can easily add the Scrawl add-on as follows. In
02-site-basics-blog.cfg, we have:
[buildout] extends = 02-site-basics-dropdownmenu.cfg [instance] eggs += Products.Scrawl
Now stop Plone (with Ctrl + C or Ctrl + Z/Enter) and run Buildout:
$ bin/buildout c 02-site-basics-blog.cfg
You should see:
$ bin/buildout -c 02-site-basics-blog.cfg Uninstalling plonesite. Uninstalling instance. Updating zope2. Updating fake eggs Installing instance. Getting distribution for 'Products.Scrawl'. Got Products.Scrawl 1.3.2. Generated script '/Users/aclark/Developer/plone-site-admin/buildout/bin/instance'.
Now start Plone:
$ bin/instance fg
Browse to http://localhost:8080/Plone Site Setup and click
on Add/Remove Products.
In the Products available for install section, you should see:
Check the box next to Scrawl 1.3.2 and click on Install.
Browse to
http://localhost:8080/Plone and create a new
Blog Entry:
Fill in the Title field and click on Save.
You should see:
If you browse to http://localhost:8080/Plone, you will
notice that your Plone site still looks the same. Certainly, it does not look
like a blog. Two things will fix that for us:
Configure the Plone site to display the Blog view template provided by Scrawl
Use the syndication feature provided by Plone to create a syndicated feed of our blog entries
To enable the blog view on the home page, we will have to:
Know the name of the template
Configure it as an available view for the Plone site content type
We can find out the name of the template by navigating to the News folder and selecting the Display menu.
You should see:
Notice that at the very bottom of the browser in the status bar, the name of the Blog view template is blog_view.
We can add blog_view to the Plone site's available views like this:
Browse to
http://localhost:8080/Plone. Click on Site Setup | Zope Management Interface | portal_types | Plone Site | Available views.Add blog_view to the list of Available view methods and click on Save Changes.
You should see:
Once that is done, select Blog view from the View menu on the Plone site, like this:
Now, let us enable syndication on the Plone site object.
One of the attractive features of Plone is its ability to syndicate content (that is, create an RSS feed). This feature is enabled by default on the news items and events folders. Unfortunately, the ability to configure syndication for other types of content is disabled by default.
To re-enable it, let's re-enable the link to the configuration form in the Plone user interface. Navigate to Site Setup | Zope Management Interface | portal_actions | object | Syndication | Visible.
Check the Visible box and click on Save Changes.
You should see:
Now return to the Plone site, navigate to Contents | Syndication | Syndication Properties | Enable syndication, and click on it.
Adjust the default settings if you like, and click on Save Changes.
Now if you return to the Plone site, you should see the following at the bottom:
Of course, there is other content in this folder, which you can either delete or set to the private state so that it is not seen by the public.
If you click on the RSS feed link, you'll see that Plone is generating an RSS feed that your browser will be happy to consume:
Note
Plone 4
In Plone 4, there will be a blog view included! That means any content item can be a blog entry.
In the most common scenario, you will configure the blog view to be the default view for a collection. The collection will display the items you configure to be blog entries, for example, pages.
Visit core developer David Glick's website at http://davisagli.com/ in order to see the Plone 4 blog view in action (thanks to the creator, Laurence Rowe).
That's it for this chapter. You have done another impressive amount of work, congratulations!
You have learned:
How Buildout configuration files work
How to add a Plone site with Buildout
How to customize navigation in Plone with add-ons
How to create a weblog with Plone using the Scrawl add-on
In the next chapter, we will learn how to use Buildout to install new themes.