Status

26.11.2006: I have abandoned Plone, therefore I do not update this page any longer.

Version

Everything that I write on this page refers to Plone 2.1 which is run on Zope 2.8.

System installation

Installing the Debian meta package

plone

makes sure that the actual plone package (zope-cmfplone) will be installed, including all the other required zope packages.

References

At the time of writing, the documentation in /usr/share/doc/zope2.8/ or /usr/share/doc/zope-cmfplone/ was no help at all for setting up zope or plone.

The following online HowTo, on the other hand, was very helpful (especially the readers' comments):

http://plone.org/documentation/how-to/helpcenterhowto.2005-10-24.6883487858

A few people have formed a group that calls itself the "Debian Zope packaging project". Their site can be found at:

http://pkg-zope.alioth.debian.org/

Information about integrating zope with apache can be found in this article:

http://www.zope.org/Members/anser/apache_zserver

Additional information about the Apache module mod_proxy can be found here:

http://httpd.apache.org/docs/2.1/mod/mod_proxy.html

Zope/Plone setup

First we need to create a so-called instance of zope. We could do this more or less "manually" by using a number of zope scripts (located in /usr/lib/zope2.8/bin/), but the easiest way is to use a tool that was created by the "Debian Zope packaging project". The tool is called

dzhandle

To create the new zope instance, we write the following command line

dzhandle --zope-version=2.8 make-instance moser-naef.ch -m all -t linked -u admin:<password>

As you can see, I chose to give the instance the name of the web site that I intend to run Plone on. The zope instance is stored in

/var/lib/zope2.8/instance/moser-naef.ch/

The zope instance can be configured by editing the file

/etc/zope2.8/moser-naef.ch/zope.conf

For now, we don't do anything of the sort. The new zope instance will therefore listen on the default port 9673, but first we have to start the instance:

/var/lib/zope2.8/instance/moser-naef.ch/bin/zopectl start

Now we can point our browser to the host that is running zope:

http://osgiliath:9673/

This displays a quick start page. To go to the ZMI (Zope Management Interface), point the browser to

http://osgiliath:9673/manage

Integrating Zope and Apache

As we have seen, zope runs its own web server on a different port than the regular http port 80. But we really don't want users to have to remember to enter a cryptic port like 9673 when they access a specific part of the web site.

The Apache module mod_proxy comes to our rescue. Using this module, we configure the apache server to act as a so-called "reverse proxy" (sometimes also called "inverse proxy") when users access parts of our web site whose URL starts with /zope/.

Using apache2, we can enable mod_proxy with this command line:

a2enmod proxy

Now we have to configure apache. In /etc/apache2/conf.d/general.conf, we add the following statements to the end of the file:

<IfModule mod_proxy.c>
   ProxyPass /zope/ http://localhost:9673/
   ProxyPassReverse /zope/ http://localhost:9673/
   <Location /zope/>
      Require all granted
   </Location>
</IfModule>

The ProxyPass directive tells apache to route all requests whose URL starts with /zope/ to the zope server that runs on port 9673 of the localhost. The URLs are stripped of the /zope/ prefix.

The ProxyPassReverse directive tells apache to monitor all responses from the zope server and to re-add the /zope/ prefix so that the external client does not notice anything suspicious.

To activate the changes in the apache configuration, restart the apache server:

apache2ctl restart

Last but not least, we also have to configure zope to play the game:

point the browser to the ZMI at http://localhost:9673/manage
authenticate
if not already displayed, go to the "Contents" folder
add an object called "SiteRoot"
within the object, set the "Base" property to http://moser-naef.ch/zope/
save

WARNING: After saving, you will no longer be able to access the ZMI via http://localhost:9673/manage. You will have to go to http://moser-naef.ch/zope/manage.

Plone setup

Basic installation

Point your browser to the ZMI, then add a "Plone Site" object. The ID of the plone site is important as it will later show up in the URL. Since I don't plan to have more than one plone site, I simply decided on the ID

plone

From now on, you may point your browser to this URL to get at the plone content:

http://moser-naef.ch/zope/plone

Log in to the plone site using your zope admin account. Then go to the control panel and configure the plone site:

http://moser-naef.ch/zope/plone/plone_control_panel

Plone site configuration

Add/Remove Products

The products installed by default are: ATContentTypes, ATReferenceBrowserWidget, Archetypes, MimetypesRegistry, PortalTransforms, ResourceRegistries, kupu kupu

Installed the following products:

PloneLanguageTool

Language Settings

Default language = de

Allowed Languages = de, en, fr, it, nl

Portal settings

Portal title = moser-naef.ch

Portal "from" address = plone@moser-naef.ch

Password policy = Generate and e-mail member's initial password

Additional products

The general way to install a new product:

download tar ball
extract, then

cp -R ProductFoo /var/lib/zope2.8/instance/moser-naef.ch/Products

restart zope (/etc/init.d/zope2.8 restart)
log into Plone as admin
go to the site administration page and add the product

CMFContentPanels

current version: 2.0
download from

http://plone.org/products/cmfcontentpanels

Quills

current version: 0.9
download from

http://plone.org/products/quills

PlonePopoll

current version: 2.4
download from

http://plone.org/products/plonepopoll

install via "Add/Remove Product" in the Plone site admin area, not via the "external method" as documented in INSTALL.txt

Content configuration

Remove entry from site-wide navigation tabs

Each page on the site contains a navigation bar at the top with a number of tabs in it. These tabs are automatically generated from the folders that exist within the "home" folder. If, for instance, I don't want the "Members" folder to appear as a tab, I can do the following modification:

open folder "home"
open tab "contents"
open folder "members"
open tab "properties"
check "exclude from navigation"

Unfortunately, this is not possible for all item types, as the "exclude from navigation" checkbox does not always appear. Notably, the checkbox is missing on weblog items from the Quills product, and on content panel items from the CMFContentPanels product. So far, I have not been able to find a way how not to have tabs for these item types.

Configure site-wide navigation tabs

It is possible to have site-wide navigation tabs for items that are not located within the top-level "home" folder:

open the ZMI
go to /plone/portal_actions
at the bottom of the form, fill out the form with the following values, then click the "add" button
- name = the string that should be the tab's visible name
- id = an ID that is not in use
- URL = the location that the tab points to, e.g. string:$portal_url/foo/bar
- condition = <blank> (if the tab should be always visible), <expression> (to show the tab only in certain circumstances)
- permission = view
- category = portal_tabs
- visible = yes

The "home" tab can be found in the same ZMI location (/plone/portal_actions). To change its URL and/or name, simply edit the corresponding properties.

Configure the plone site (or any item's) default page

Usually you use the Plone site interface, not the ZMI, to change an item's default view ("choose content item as default view" from the "display" menu).

Unfortunately, this is not possible for all item types, as some types simply do not show up in the list of content items that the Plone site interface displays. Notably, this is the case for weblog items from the Quills product.

There are two solutions to this problem: either configure the item type so that from now on it always shows up in the Plone site interface, or configure only one specific item.

Configure the item type:

open the ZMI
go to /plone/portal_properties/site_properties
open the "properties" page
look for the property "default_page_types" (or create it, it has the type "lines") and add the desired type to the list
- for instance, in the mentioned case with Quills, I had to add the type "Weblog"

Configure one specific item to be the default view:

open the ZMI
go to /foo/bar (i.e. the item for which you want to change the default view)
open the "properties" page
add a new property named "default_page" which is of type "lines" and has as its value the ID of the content item that you want to display by default

Make a document (= page) visible as a portlet

The original how-to

http://plone.org/documentation/how-to/editable-static-text-portlets

Summary:

create the document whose content should be displayed as a portlet
- the term "document" refers to a content item of type "page"; in the ZMI this displays as an object of type ATDocument
- note: the page title and body will be displayed, but not the description
- you do not have to fill in the content yet, all that is required is that the page exists before the next steps are made
open the ZMI
go to /plone/portal_skins/custom
create a new object of type "Page template"; name it "portlet_document_view"
edit the object and enter the following content:

 <div metal:define-macro="portlet" tal:omit-tag="">
   <tal:block>
     <div class="portlet">
       <h5 tal:content="here/title_or_id">Title</h5>
       <div class="portletBody">
         <div class="portletContent" tal:content="structure python:here.CookedBody(stx_level=2)">
           Content will appear here.
         </div>
       </div>   
     </div>
   </tal:block>
 </div>

- note: the how-to document on plone.org gives a warning that if ATContentTypes are used some of the above code needs to be changed; we can ignore this warning, because even though the page that has the portlet content is of type ATDocument, this does ***not*** mean that we are using ATContentTypes
go to /plone and open the properties tab
add the following line to either "left_slots" or "right_slots" property

portal/portlets/links/portlet_document_view

- the first part of the path is always "portal"
- the next part "portlets/links" refers to the page that has the portlet content; in this example, I have created a top-level folder named "portlets" that contains a page named "links"
- the last part refers to the page template object "portlet_document_view"

Configure portlet location/visibility

The original how-to

http://plone.org/documentation/how-to/control-portlets

In the ZMI, go to the "plone site" entry (/plone) and edit the properties of the entry. You will see two lists, "left slots" and "right slots", that define the portlets that can be seen on the left and on the right hand side of the site's main content area.

Default entries on the left are

here/portlet_navigation/macros/portlet
here/portlet_login/macros/portlet
here/portlet_recent/macros/portlet
here/portlet_related/macros/portlet

Default entries on the right are

here/portlet_review/macros/portlet
here/portlet_news/macros/portlet
here/portlet_events/macros/portlet
here/portlet_calendar/macros/portlet

You can freely move portlet entries from the left to the right, and vice versa. Of course, it is also possible to completely remove an entry.

My site is configured like this:

because the default view of my site's "home" folder already lists news items, I have completely removed the news portlet
my site is extremely simple; all the navigation that I require is already there with the top-level tabs, therefore I have removed the navigation portlet
again, because I have so little content, I feel that the "recent" portlet is a waste of space
I have moved all remaining portlets to the right hand side to make room for the main content area

Configure logo

The original how-to

http://plone.org/documentation/how-to/custom-logo

Summary:

open the ZMI
go to /plone/portal_skins/custom
create a new object of type "Image"
name the object "logo.jpg", and upload the new logo
- note: despite the object name, the image may be of any type supported by plone (e.g. gif, jpg, png)
reload the plone site page in the browser to see the new logo (it is possible that you have to clear the browser's cache)

Configure portlets

The default Plone portlets are located in the ZMI at

/plone/portal_skins/plone/portlets

To change something about a specific portlet, select the portlet and then select "customize". A copy of the portlet code will be placed into the folder

/plone/portal_skins/custom

You can now edit this copy to customize the portlet. If you ever want to get rid of the customized behaviour, simply delete the portlet entry from the custom folder.

Example: I wanted the "Events" portlet to display only 3 events instead of the default 5. I created the customized copy of "portlet_events" as described above, and then changed a single number from 5 to 3 - the number is located near the top of the portlet code, the line looks something like this:

review_state='published')[:3];"

Plone

Status

Version

System installation

References

Zope/Plone setup

Integrating Zope and Apache

Plone setup

Basic installation

Plone site configuration

Add/Remove Products

Language Settings

Portal settings

Additional products

CMFContentPanels

Quills

PlonePopoll

Content configuration

Remove entry from site-wide navigation tabs

Configure site-wide navigation tabs

Configure the plone site (or any item's) default page

Make a document (= page) visible as a portlet

Configure portlet location/visibility

Configure logo

Configure portlets

Navigation menu

Search