Plone Training¶

Who are you?¶

Tell us about yourselves:

• Name, company, country...

• What is your Plone experience?

• What is your web development experience?

• What are your expectations for this tutorial?

• What is your favorite text editor?

• If this training will include the development chapters:

  • Do you know the HTML of the output of this?

    <div class="hiddenStructure"
         tal:repeat="num python:range(1, 10, 5)"
         tal:content="structure num"
         tal:omit-tag="">
      This is some weird sh*t!
    </div>
    

    The answer is:

    1 6
    

  • Do you know what the following would return?:

    [(i.Title, i.getURL()) for i in context.getFolderContents()]
    

What will we do?¶

Some technologies and tools we use during the training:

• For the beginning training:

  • Virtualbox
  • Vagrant
  • Ubuntu linux
  • Through-the-web (TTW)
  • Buildout
  • A little XML
  • A little Python

• For the advanced chapters:

  • Git
  • GitHub
  • Try Git (Nice introduction to git and github)
  • TAL
  • METAL
  • ZCML
  • Python
  • Dexterity
  • Viewlets
  • JQuery
  • Testing
  • References/Relations

What will we not do?¶

We will not cover the following topics:

• Archetypes
• Portlets
• z3c.forms
• Theming
• i18n and locales
• Deployment, Hosting and Caching
• Grok

Other topics are only covered lightly:

• Zope Component Architecture
• GenericSetup
• ZODB
• Security
• Permissions
• Performance and Caching

What to expect¶

At the end of the first two days of training, you’ll know many of the tools required for Plone installation, integration and configuration. You’ll be able to install add-on packages and will know something about the technologies underlying Plone and their histories.

At the end of the second two days, you won’t be a complete professional Plone-programmer, but you will know some of the more powerful features of Plone and should be able to construct a more complex website with custom themes and packages. You should also be able to find out where to look for instructions to do tasks we did not cover. You will know most of the core technologies involved in Plone programming.

If you want to become a professional Plone developer or a highly sophisticated Plone integrator you should definitely read Martin Aspeli’s book and then re-read it again while actually doing a complex project.

Classroom Protocol¶

Questions to ask:

• What did you just say?
• Please explain what we just did again?
• How did that work?
• Why didn’t that work for me?
• Is that a typo?

Questions __not__ to ask:

• Hypotheticals: What happens if I do X?
• Research: Can Plone do Y?
• Syllabus: Are we going to cover Z in class?
• Marketing questions: please just don’t.
• Performance questions: Is Plone fast enough?
• Unpythonic: Why doesn’t Plone do it some other way?
• Show off: Look what I just did!

Documentation¶

Follow the training at https://training.plone.org/5

Further Reading¶

• Martin Aspeli: Professional Plone4 Development
• Practical Plone
• Zope Page Templates Reference

Installing Plone¶

The following table shows the Python versions required by Plone from version 3.x to 5.0.x:

(Hopefully you won’t have to deal with any Plone sites older than version 3.x.)

Plone 5.x requires a working Python 2.7 and several other system tools that not every OS provides. Therefore the installation of Plone is different on every system. Here are some ways that Python can be used:

• use a Python that comes pre-installed in your operating system (most Linux Distributions and Mac OS X have one)
• use the python buildout
• building Linux packages
• homebrew (Mac OS X)
• PyWin32 (Windows)

Mac OS X 10.8 - 10.10 and Ubuntu 14.04 come with a working default Python 2.7 built in. These are the lucky ones.

Most developers use their primary system to develop Plone. For complex setups they often use Linux virtual machines.

• OS X: Use the python buildout to compile python and homebrew for some missing Linux tools.
• Linux: Depending on your Linux flavor you might have to build python yourself and install some tools.
• Windows: Alan Runyan (one of Plone’s founders) uses it. A downside: Plone seems to be running much slower on Windows.

Plone offers multiple options for being installed:

1. Unified installers (all ‘nix, including OS X)
2. A Vagrant/VirtualBox install kit (all platforms)
3. A VirtualBox Appliance
4. Use your own Buildout

You can download all of these at https://plone.org/download

For the training we’ll use option 2 and 4 to install and run Plone. We’ll create our own Buildout and extend it as we wish. But we will do so in a vagrant machine. For your own first experiments we recommend option 1 or 2 (if you have a Windows laptop or encounter problems). Later on you should be able to use your own Buildout (we’ll cover that later on).

Hosting Plone¶

If you want to host a real live Plone site yourself then running it from your laptop is not a viable option.

You can host Plone...

• with one of many professional hosting providers
• on a virtual private server
• on dedicated servers
• on heroku you can run Plone for free using the Heroku buildpack for Plone
• in the cloud (e.g. using Amazon EC2 or Codio.com)

Production Deployment¶

The way we’re setting up a Plone site during this class may be adequate for a small site — or even a very large one that’s not very busy — but you’re likely to want to do much more if you’re using Plone for anything demanding.

• Using a production web server like Apache or Nginx for URL rewriting, SSL and combining multiple, best-of-breed solutions into a single web site.
• Reverse proxy caching with a tool like Varnish to improve site performance.
• Load balancing to make best use of multiple core CPUs and even multiple servers.
• Optimizing cache headers and Plone’s internal caching schemes with plone.app.caching.

And, you’ll need to learn strategies for efficient backup and log file rotation.

All these topics are introduced in Guide to deploying and installing Plone in production.

Installing Plone without vagrant¶

If you are experienced with running Plone on your own laptop, we encourage you to do so because you will have certain benefits:

• You can use the editor you are used to.
• You can use omelette to have all the code of Plone at your fingertips.
• You do not have to switch between different operating systems during the training.

If you feel comfortable, please work on your own machine with your own Python. But please make sure that you have a system that will work, since we don’t want you to lose valuable time!

sudo apt-get install python-setuptools python-virtualenv python-dev build-essential libssl-dev libxml2-dev libxslt1-dev libbz2-dev libjpeg62-dev
sudo apt-get install libreadline-dev wv poppler-utils
sudo apt-get install git

Set up Plone for the training like this if you use your own OS (Linux or Mac):

$ mkdir training
$ cd training
$ git clone https://github.com/collective/training_buildout.git buildout
$ cd buildout
$ virtualenv --python=python2.7 py27

Now you can run the buildout for the first time:

$ ./py27/bin/python bootstrap.py
$ ./bin/buildout

This will take some time and produce a lot of output because it downloads and configures Plone. Once it is done you can start your instance with

$ ./bin/instance fg

The output should be similar to:

2015-09-24 15:51:02 INFO ZServer HTTP server started at Thu Sep 24 15:51:02 2015
        Hostname: 0.0.0.0
        Port: 8080
2015-09-24 15:51:05 WARNING PrintingMailHost Hold on to your hats folks, I'm a-patchin'
2015-09-24 15:51:05 WARNING PrintingMailHost

******************************************************************************

Monkey patching MailHosts to print e-mails to the terminal.

This is instead of sending them.

NO MAIL WILL BE SENT FROM ZOPE AT ALL!

Turn off debug mode or remove Products.PrintingMailHost from the eggs
or remove ENABLE_PRINTING_MAILHOST from the environment variables to
return to normal e-mail sending.

See https://pypi.python.org/pypi/Products.PrintingMailHost

******************************************************************************

2015-09-24 15:51:05 INFO ZODB.blob (54391) Blob directory `.../buildout/var/blobstorage` is unused and has no layout marker set. Selected `bushy` layout.
2015-09-24 15:51:05 INFO ZODB.blob (54391) Blob temporary directory '.../buildout/var/blobstorage/tmp' does not exist. Created new directory.
.../.buildout/eggs/plone.app.multilingual-3.0.11-py2.7.egg/plone/app/multilingual/browser/migrator.py:11: DeprecationWarning: LanguageRootFolder: LanguageRootFolders should be migrate to DexterityContainers
  from plone.app.multilingual.content.lrf import LanguageRootFolder
2015-09-24 15:51:09 INFO Plone OpenID system packages not installed, OpenID support not available
2015-09-24 15:51:11 INFO PloneFormGen Patching plone.app.portlets ColumnPortletManagerRenderer to not catch Retry exceptions
2015-09-24 15:51:11 INFO Zope Ready to handle requests

If the output says INFO Zope Ready to handle requests then you are in business.

If you point your browser at http://localhost:8080 you see that Plone is running. There is no Plone site yet - we will create one in chapter 6.

Now you have a working Plone site up and running and can continue with the next chapter. You can stop the running instance anytime using ctrl + c.

Installing Plone with vagrant¶

In order not to waste too much time with installing and debugging the differences between systems, we use a virtual machine (Ubuntu 16.04) to run Plone during the training. We rely on Vagrant and VirtualBox to give the same development environment to everyone.

Vagrant is a tool for building complete development environments. We use it together with Oracle’s VirtualBox to create and manage a virtual environment.

$ mkdir training
$ cd training

$ vagrant plugin install vagrant-vbguest

$ wget https://raw.githubusercontent.com/plone/training/master/_static/plone_training_config.zip
$ unzip plone_training_config.zip

$ vagrant up

Skipping because of failed dependencies

$ vagrant provision

ssh_exchange_identification: read: Connection reset by peer

$ vagrant ssh

ubuntu@training:~$ cd /vagrant/buildout/
ubuntu@training:/vagrant/buildout$ bin/instance fg
2017-09-28 09:19:21 INFO ZServer HTTP server started at Thu Sep 28 09:19:21 2017
        Hostname: 0.0.0.0
        Port: 8080
2017-09-28 09:19:24 INFO Products.PloneFormGen gpg_subprocess initialized, using /usr/bin/gpg
2017-09-28 09:19:24 WARNING PrintingMailHost Hold on to your hats folks, I'm a-patchin'
2017-09-28 09:19:24 WARNING PrintingMailHost

******************************************************************************

Monkey patching MailHosts to print e-mails to the terminal.

This is instead of sending them.

NO MAIL WILL BE SENT FROM ZOPE AT ALL!

Turn off debug mode or remove Products.PrintingMailHost from the eggs
or remove ENABLE_PRINTING_MAILHOST from the environment variables to
return to normal e-mail sending.

See https://pypi.python.org/pypi/Products.PrintingMailHost

******************************************************************************

/home/ubuntu/buildout-cache/eggs/plone.app.dexterity-2.3.7-py2.7.egg/plone/app/dexterity/__init__.py:14: DeprecationWarning: Name clash, now use '_' as usal. Will be removed in Plone 5.2
  DeprecationWarning)
/home/ubuntu/buildout-cache/eggs/plone.app.multilingual-5.0.3-py2.7.egg/plone/app/multilingual/browser/migrator.py:11: DeprecationWarning: LanguageRootFolder: LanguageRootFolders should be migrate to DexterityContainers
  from plone.app.multilingual.content.lrf import LanguageRootFolder
/home/ubuntu/buildout-cache/eggs/plone.portlet.collection-3.1-py2.7.egg/plone/portlet/collection/collection.py:2: DeprecationWarning: isDefaultPage is deprecated. Import from Products.CMFPlone instead
  from plone.app.layout.navigation.defaultpage import isDefaultPage
2017-09-28 09:19:28 INFO Plone OpenID system packages not installed, OpenID support not available
2017-09-28 09:19:30 INFO PloneFormGen Patching plone.app.portlets ColumnPortletManagerRenderer to not catch Retry exceptions
2017-09-28 09:19:30 INFO Zope Ready to handle requests

ValueError: unknown locale: UTF-8

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Background¶

The Plone conference takes place every year and all Plone developers at least try to go there.

Requirements¶

Here are some requirements that we want to meet when the site is done:

• As a visitor I want to find current information on the conference.
• As a visitor I want to register for the conference.
• As a visitor I want to see the talks and sort them by my preferences.
• As a speaker I want to be able to submit talks.
• As a speaker I want to see and edit my submitted talks.
• As an organizer I want to see a list of all proposed talks.
• As an organizer I want to have an overview about how many people registered.
• As a jury member I want to vote on talks.
• As a jury member I want to decide which talks to accept, and which not.

Note that all of our requirements connect roles with capabilities. This is important because we’ll want to limit the capabilities to those to whom we assign particular roles.

Starting and Stopping Plone¶

We control Plone with a small script called “instance”:

$ ./bin/instance fg

This starts Plone in foreground mode so that we can see what it is doing by monitoring console messages. This is an important development method. Note that when Plone is started in foreground mode, it is also automatically in development mode. Development mode gives better feedback, but is much slower, particularly on Windows.

You can stop it by pressing ctrl + c.

Apart from the fg command the instance script offers several more commands. ./bin/instance help shows the list of available commands, bin/instance help <command> will give a short help for each command. Some commands you will use rather often are:

$ ./bin/instance fg
$ ./bin/instance start
$ ./bin/instance stop
$ ./bin/instance debug
$ ./bin/instance run myscript.py
$ ./bin/instance adduser name password

Depending on your computer, it might take up to a minute until Zope will tell you that it’s ready to serve requests. On a decent laptop it should be running in under 15 seconds.

A standard installation listens on port 8080, so lets have a look at our Zope site by visiting http://localhost:8080

As you can see, there is no Plone site yet!

We have a running Zope with a database but no content. But luckily there is a button to create a Plone site. Click on that button (login: admin, password: admin). This opens a form to create a Plone site. Use Plone as the site id.

You now have the option to select some add-ons before you create the site. Since we will use Dexterity from the beginning we select Dexterity-based Plone Default Types. This way even the initial content on our page will be built with Dexterity using the add-on plone.app.contenttypes which is the default in Plone 5.

You will be automatically redirected to the new site.

if __name__ == '__main__':
    sys.exit(plone.recipe.zope2instance.ctl.main(
        ['-C', '/home/vagrant/training/buildout/parts/instance/etc/zope.conf']
        + sys.argv[1:]))

<http-server>
 address 8080
</http-server>

>>> import transaction
>>> transaction.commit()

Walkthrough of the UI¶

Let’s see what is there...

• header:
  • logo: with a link to the front page
  • searchbox: search (with live-search)
• navigation: The global navigation
• banner: A banner. Only visible on the front page.
• portal-columns: a container holding:
  • portal-column-one: portlets (configurable boxes with tools like navigation, news etc.)
  • portal-column-content: the content and the editor
  • portal-column-two: portlets
• portal-footer: portlets for the footer, site actions, and colophon
• edit-zone: a vertical bar on the left side of the browser window with editing options for the content

These are also the CSS classes of the respective divs. If you want to do theming, you’ll need them.

On the edit bar, we find options affecting the current context...

• folder contents
• edit
• view
• add
• state
• actions
• display
• manage portlets
• history
• sharing
• rules
• user actions

Some edit bar options only show when appropriate; for example, folder contents and add are only shown for Folders. rules is currently invisible because we have no content rules available.

Users¶

Let’s create our first users within Plone. So far we used the admin user (admin:admin) configured in the buildout. This user is often called “Zope root” and is not managed in Plone but only by Zope. Therefore the user is missing some features like email and full name and won’t be able to use some of Plone’s features. But the user has all possible permissions. As with the root user of a server, it’s bad practice to make unnecessary use of Zope root. Use it to create Plone sites and their initial users, but not much else.

You can also add Zope users via the terminal by entering:

$ ./bin/instance adduser <someusername> <supersecretpassword>

That way you can access databases you get from customers where you have no Plone user.

To add a new user in Plone, click on the user icon at the bottom of the left vertical bar and then on Site setup. This is Plone’s control panel. You can also access it by browsing to http://localhost:8080/Plone/@@overview-controlpanel

Click on Users and Groups and add a user. If we had configured a mail server, Plone could send you a mail with a link to a form where you can choose a password. (Or, if you have Products.PrintingMailHost in your buildout, you can see the email scrolling by in the console, just the way it would be sent out.) We set a password here because we haven’t yet configured a mail server.

Make this user with your name an administrator.

Then create another user called testuser. Make this one a normal user. You can use this user to see how Plone looks and behaves to users that have no admin permissions.

Now let’s see the site in 3 different browsers with three different roles:

• as anonymous
• as editor
• as admin

Configure a Mailserver¶

We have to configure a mailserver since later we will create some content rules that send emails when new content is put on our site.

• Server: localhost
• Username: leave blank
• Password: leave blank
• Site ‘From’ name: Your name
• Site ‘From’ address: Your email address

Click on Save and send test e-mail. Since we have configured PrintingMailHost, you will see the mail content in the console output of your instance. Plone will not actually send the email to the receivers address.

Content-Types¶

Edit a page:

• Edit front-page
• Title Plone Conference 2015, Bucharest
• Summary Tutorial
• Text ...

Create a site structure:

• Add a folder “The Event” and in it add:
  • Folder “Talks”
  • Folder “Training”
  • Folder “Sprint”
• In /news: Add a News Item “Conference Website online!” with some image
• In /news: Add a News Item “Submit your talks!”
• In /events: Add an Event “Deadline for talk submission” Date: 2015/08/10
• Add a Folder “Register”
• Delete the Folder “Users”
• Add a Folder “Intranet”

The default Plone content types are:

• Collection
• Event
• File
• Folder
• Image
• Link
• News Item
• Page

Folders¶

• Go to ‘the-event’
• explain the difference between title, ID, and URL
• explain /folder_contents
• change the order of items
• explain bulk actions
• dropdown “display”
• default pages
• Add a page to ‘the-event’: “The Event” and make it the default page

Collections¶

• add a new collection: “all content that has pending as wf_state”.
• explain the default collection for events at http://localhost:8080/Plone/events/aggregator/edit
• explain Topics
• mention collection portlets
• multi-path queries
• constraints, e.g. /Plone/folder::1

Content Rules¶

• Create new rule “a new talk is in town”!
• New content in folder “Talks” -> Send Mail to reviewers.

History¶

Show and explain; mention versioning and its relation to types.

Manage members and groups¶

• add/edit/delete Users
• roles
• groups
  • Add group “Editors” and add the user ‘editor’ to it
  • Add group: orga
  • Add group: jury and add user ‘jurymember’ to it.

Workflows¶

Take a look at the state drop down on the edit bar on the homepage. Now, navigate to one of the folders just added. The homepage has the status published and the new content is private.

Let’s look at the state transitions available for each type. We can make a published item private and a private item published. We can also submit an item for review.

Each of these states connects roles to permissions.

• In published state, the content is available to anonymous visitors;
• In private state, the content is only viewable by the author (owner) and users who have the can view role for the content.

A workflow state is an association between a role and one or more permissions. Moving from one state to another is a transition. Transitions (like submit for review) may have actions — such as the execution of a content rule or script — associated with them.

A complete set of workflow states and transitions makes up a workflow. Plone allows you to select among several pre-configured workflows that are appropriate for different types of sites. Individual content types may have their own workflow. Or, and this is particularly interesting, they may have no workflow. In that case, which initially applies to file and image uploads, the content object inherits the workflow state of its container.

Read more at: https://docs.plone.org/working-with-content/collaboration-and-workflow/index.html

Working copy¶

Published content, even in an intranet setting, can pose a special problem for editing. It may need to be reviewed before changes are made available. In fact, the original author may not even have permission to change the document without review. Or, you may need to make a partial edit. In either case, it may be undesirable for changes to be immediately visible.

Plone’s working copy support solves this problem by adding a check-out/check-in function for content — available on the actions menu. A content item may be checked out, worked on, then checked back in. Or it may abandoned if the changes weren’t acceptable. Not until check in is the new content visible.

While it’s shipped with Plone, working copy support is not a common need. So, if you need it, you need to activate it via the add-on packages configuration page. Unless activated, check-in/check-out options are not visible.

Placeful workflows¶

You may need to have different workflows in different parts of a site. For example, we created an intranet folder. Since this is intended for use by our conference organizers — but not the public — the simple workflow we wish to use for the rest of the site will not be desirable.

Plone’s Workflow Policy Support package gives you the ability to set different workflows in different sections of a site. Typically, you use it to set a special workflow in a folder that will govern everything under that folder. Since it has effect in a “place” in a site, this mechanism is often called “Placeful Workflow”.

As with working-copy support, Placeful Workflow ships with Plone but needs to be activated via the add-on configuration page. Once it’s added, a Policy option will appear on the state menu to allow setting a placeful workflow policy.

Zope2¶

• Zope is a web application framework that Plone runs on top of.
• The majority of Zope’s code is written in Python, like everything else written on top of it.
• It serves applications that communicate with users via http.

Before Zope, there usually was an Apache server that would call a script and give the request as an input. The script would then just print HTML to the standard output. Apache returned that to the user. Opening database connections, checking permission constraints, generating valid HTML, configuring caching, interpreting form data and everything else: you have to do it on your own. When the second request comes in, you have to do everything again.

Jim Fulton thought that this was slightly tedious. So he wrote code to handle requests. He believed that site content is object-oriented and that the URL should somehow point directly into the object hierarchy, so he wrote an object-oriented database, called ZODB.

The ZODB is a fully ACID compliant database with automatic transactional integrity. It automatically maps traversal in the object hierarchy to URL paths, so there is no need to “wire” objects or database nodes to URLs. This gives Plone its easy SEO-friendly URLs.

Traversal through the object database is security checked at every point via very fine grained access-control lists.

One missing piece is important and complicated: Acquisition.

Acquisition is a kind of magic. Imagine a programming system where you do not access the file system and where you do not need to import code. You work with objects. An object can be a folder that contains more objects, an HTML page, data, or another script. To access an object, you need to know where the object is. Objects are found by paths that look like URLs, but without the domain name. Now Acquisition allows you to write an incomplete path. An incomplete path is a relative path, it does not explicitly state that the path starts from the root, it starts relative to where the content object is – its context. If Zope cannot resolve the path to an object relative to your code, it tries the same path in the containing folder. And then the folder containing the folder.

This might sound weird, what do I gain with this?

You can have different data or code depending on your context. Imagine you want to have header images differing for each section of your page, sometimes even differing for a specific subsection of your site. So you define a path header_image and put a header image at the root of your site. If you want a folder with a different header image, you put the header image into this folder. Please take a minute to let this settle and think about what this allows you to do.

• contact forms with different e-mail addresses per section
• different CSS styles for different parts of your site
• One site, multiple customers, everything looks different for each customer.

As with all programming magic, acquisition exacts a price. Zope code must be written carefully in order to avoid inheriting side effects via acquisition. The Zope community expresses this with the Python (Monty) maxim: Beware the Spammish Acquisition.

Basically this is Zope.

Content Management Framework¶

• CMF (Content Management Framework) is add-on for Zope to build Content Management Systems (like Plone).

After many websites were successfully created using Zope, a number of recurring requirements emerged, and some Zope developers started to write CMF, the Content Management Framework.

The CMF offers many services that help you to write a CMS based on Zope. Most objects you see in the ZMI are part of the CMF somehow.

The developers behind CMF do not see CMF as a ready to use CMS. They created a CMS Site which was usable out of the box, but made it deliberately ugly, because you have to customize it anyway.

We are still in prehistoric times here. There were no eggs (Python packages), Zope did not consist of 100 independent software components but was one big file set.

Many parts of Plone are derived from the CMF, but it’s a mixed heritage. The CMF is an independent software project, and has often moved more slowly than Plone. Plone is gradually eliminating dependence on most parts of the CMF.

Zope Toolkit / Zope3¶

• Zope 3 was originally intended as a rewrite of Zope from the ground up.
• Plone uses parts of it provided by the Zope Toolkit (ZTK).

Unfortunately, only few people started to use Zope 3, nobody migrated to Zope 3 because nobody knew how.

But there were many useful things in Zope 3 that people wanted to use in Zope 2, thus the Zope community adapted some parts so that they could use them in Zope 2. Sometimes, a wrapper of some sort was necessary, these usually are being provided by packages from the five namespace. (Zope 2 + Zope 3 = “five”)

To make the history complete, since people stayed on Zope 2, the Zope community renamed Zope 3 to Bluebream, so that people would not think that Zope 3 was the future. It wasn’t anymore.

Zope Component Architecture (ZCA)¶

The Zope Component Architecture, which was developed as part of Zope 3, is a system which allows for component pluggability and complex dispatching based on objects which implement an interface (a description of a functionality). It is a subset of the ZTK but can be used standalone. Plone makes extensive use of the ZCA in its codebase.

Pyramid¶

• Pyramid is a Python web application development framework that is often seen as the successor to Zope.
• It does less than Zope, is very pluggable and uses the Zope Component Architecture “under the hood” to perform view dispatching and other application configuration tasks.

You can use it with a relational Database instead of ZODB if you want, or you can use both databases or none of them.

Apart from the fact that Pyramid was not forced to support all legacy functionality, which can make things more complicated, the original developer had a very different stance on how software must be developed. While both Zope and Pyramid have good test coverage, Pyramid has good documentation; something that was very neglected in Zope, and at times in Plone too.

Whether the component architecture is better in Pyramid or not we don’t dare say, but we like it more. But maybe it’s just because it was documented.

Exercise¶

Definition of the PYTHON_PATH makes up most of the bin/instance script’s code. Look at the package list (and maybe also the links provided in the respective sections of this chapter). Try to identify 3 packages that belong to the original Zope2, 3 packages from CMF, 3 Zope Toolkit packages and 3 packages from the ZCA.

Default Theme¶

The new default theme is called Barceloneta

It is a Diazo theme, meaning it uses plone.app.theming to insert the output of Plone into static html/css.

It uses html5, so it uses <header>, <nav>, <aside>, <section>, <article> and <footer> for semantic html.

The theme is mostly built with LESS (lots of it!) and uses the same grid system as bootstrap. This means you can use css classes like col-xs-12 col-sm-9 to control the width of elements for different screen-sizes. If you prefer a different grid-system (like foundation) over bootstrap you can adapt the theme to use that.

The index.html and rules.xml are actually not that complicated. Have a look at them.

The following example from rules.xml makes sure that the banner saying “Welcome! Plone 5 rocks!” is only visible on the frontpage:

<!-- include view @@hero on homepage only -->
<after css:theme="#mainnavigation-wrapper"
       css:content=".principal"
       href="/@@hero"
       css:if-content="body.template-document_view.section-front-page" />

The browser-view @@hero (you can find it by searching all ZCML-files for name="hero") is only included when the body-tag of the current page has the css-classes template-document_view and section-front-page.

New UI and widgets¶

The green edit bar is replaced by a toolbar that is located on the left or top and can be expanded. The design of the toolbar is pretty isolated from the theme and it should not break if you use a different theme.

The widgets where you input data are also completely rewritten.

• We now use the newest TinyMCE
• The tags (keywords) widget and the widgets where you input usernames now use select2 autocomplete to give a better user experience
• The related-items widget is a complete rewrite

Folder Contents¶

The view to display the content of a folder is new and offers many new features:

• configurable table columns
• changing properties of multiple items at once
• querying (useful for folders with a lot of content)
• persistent selection of items

Content Types¶

All default types are based on Dexterity. This means you can use behaviors to change their features and edit them through the web. Existing old content can be migrated to these types.

Resource Registry¶

The resource registry allows you to configure and edit the static resources (js, css) of Plone. It replaces the old javascript and css registries. And it can be used to customize the theme by changing the variables used by LESS or overriding LESS files.

Chameleon template engine¶

Chameleon is the new rendering engine of Plone 5. It offers many improvements:

Old syntax:

<h1 tal:attributes="title view/title"
    tal:content="view/page_name">
</h1>

New (additional) syntax:

<h1 title="${view/title}">
    ${view/page_name}
</h1>

Template debugging:

You can now put a full-grown pdb in a template.

<?python import pdb; pdb.set_trace() ?>

For debugging check out the variable econtext, it holds all the current elements.

You can also add real Python blocks inside templates.

<?python

from plone import api

catalog = api.portal.get_tool('portal_catalog')
results = []
for brain in catalog(portal_type='Folder'):
    results.append(brain.getURL())

?>

<ul>
    <li tal:repeat="result results">
      ${result}
    </li>
</ul>

Don’t overdo it!

Control panel¶

• You can finally upload a logo in @@site-controlpanel.
• All control panels were moved to z3c.form
• Many small improvements

Date formatting on the client side¶

Using the js library moment.js the formatting of dates was moved to the client.

<ul class="pat-moment"
    data-pat-moment="selector:li;format:calendar;">
    <li>${python:context.created().ISO()}</li>
    <li>2015-10-22T12:10:00-05:00</li>
</ul>

returns

• Today at 3:24 PM
• 10/22/2015

plone.app.multilingual¶

plone.app.multilingual is the new default add-on for sites in more than one language.

New portlet manager¶

plone.footerportlets is a new place to put portlets. The footer (holding the footer, site_actions, colophon) is now built from portlets. This means you can edit the footer TTW.

There is also a useful new portlet type Actions used for displaying the site_actions.

Remove portal_skins¶

Many of the old skin templates were replaced by real browser views.

The Control Panel¶

The most important parts of Plone can be configured in the control panel.

• Click on the portrait/username in the toolbar
• Click Site Setup

We’ll explain every page and mention some of the actions you can perform here.

Portlets¶

In the toolbar under More options you can open the configuration for the different places where you can have portlets.

• UI fit for smart content editors
• Various types
• Portlet configuration is inherited
• Managing
• Ordering/weighting
• The future: may be replaced by tiles
• @@manage-portlets

Example:

• Go to http://localhost:8080/Plone/@@manage-portlets
• Add a static portlet “Sponsors” on the right side.
• Remove the news portlet and add a new one on the left side.
• Go to the training folder: http://localhost:8080/Plone/the-event/training and click Manage portlets
• Add a static portlet. “Featured training: Become a Plone-Rockstar at Mastering Plone!”
• Use the toolbar to configure the portlets of the footer:
  • Hide the portlets “Footer” and “Colophon”.
  • Add a “Static text portlet” enter “Copyright 2015 by Plone Community”.
  • Use “Insert > Special Character” to add a real © sign.
  • You could turn that into a link to a copyright page later.

Viewlets¶

Portlets save data, Viewlets usually don’t. Viewlets are often used for UI-Elements and have no nice UI to customize them.

• @@manage-viewlets
• Viewlets have no nice UI
• Not aimed at content editors
• Not locally addable, no configurable inheritance.
• Usually global (depends on code)
• Will be replaced by tiles?
• The code is much simpler (we’ll create one tomorrow).
• Live in viewlet managers, can be nested (by adding a viewlet that contains a viewlet manager).
• TTW reordering only within the same viewlet manager.
• The code decides when it is shown and what it shows.

ZMI (Zope Management Interface)¶

Go to http://localhost:8080/Plone/manage

Zope is the foundation of Plone. Here you can access the inner workings of Zope and Plone alike.

We only cover three parts of customization in the ZMI now. Later on when we added our own code we’ll come back to the ZMI and will look for it.

At some point you’ll have to learn what all those objects are about. But not today.

Summary¶

You can configure and customize a lot in Plone through the web. The most important options are accessible in the Plone control panel but some are hidden away in the ZMI. The amount and presentation of information is overwhelming but you’ll get the hang of it through a lot of practice.

Extension technologies¶

How do you extend Plone?

This depends on what type of extension you want to create.

• You can create extensions with new types of objects to add to your Plone site. Usually these are contenttypes.
• You can create an extension that changes or extends functionality. For example to change the way Plone displays search results, or to make pictures searchable by adding a converter from jpg to text.

What are components, what is ZCML¶

What is the absolute simplest way to extend functionality?

Monkey Patching.

It means that you change code in other files while my file gets loaded.

If you want to have an extensible registry of icons for different contenttypes, you could create a global dictionary, and whoever implements a new icon for a different content type would add an entry to my dictionary during import time.

This approach, like subclassing via multiple inheritance, does not scale. Multiple plugins might overwrite each other, you would explain to people that they have to reorder the imports, and then, suddenly, you will be forced to import feature A before B, B before C and C before A, or else your application won’t work.

The Zope Component Architecture with its ZCML configuration is an answer to these problems.

With ZCML you declare utilities, adapters and browser views in ZCML, which is an XML dialect. ZCML stands for Zope Component Markup Language.

Components are differentiated from one another by the interfaces (formal definitions of functionality) that they require or provide.

During startup, Zope reads all these ZCML statements, validates that there are not two declarations trying to register the same components and only then registers everything. All components are registered by interfaces required and provided. Components with the same interfaces may optionally also be named.

This is a good thing. ZCML is, by the way, only one way to declare your configuration.

Grok provides another way, where some Python magic allows you to use decorators to register Python classes and functions as components. You can use ZCML and Grok together if you wish.

Some like Grok because it allows you to do nearly everything in your Python source files. No additional XML wiring required. If you’re XML-allergic, Grok is your ticket to Python nirvana.

Not everybody loves Grok. Some parts of the Plone community think that there should only be one configuration language, others are against adding the relative big dependency of Grok to Plone. One real problem is the fact that you cannot customize components declared with grok with jbot (which we’ll discuss later). Grok is not allowed in the Plone core for these reasons.

The choice to Grok or not to Grok is yours to make. In any case, if you start to write an extension that is reusable, convert your grok declarations to ZCML to get maximum acceptance.

Personally, I just find it cumbersome but even for me as a developer it offers a nice advantage: thanks to ZCML, I hardly ever have a hard time to find what and where extensions or customizations are defined. For me, ZCML files are like a phone book.

Some notable add-ons¶

Products.PloneFormGen

A form generator.

collective.disqus

Integrates the Disqus commenting platform API into Plone

collective.plonetruegallery

Photo galleries with a huge selection of various js-libraries.

plone.app.mosaic

Layout solution to easily create complex layouts through the web.

collective.geo

Flexible bundle of add-ons to geo-reference content and display in maps

collective.mailchimp

Allows visitors to subscribe to mailchimp newsletters

eea.facetednavigation

Create faceted navigation and searches through the web.

collective.lineage

Microsites for Plone - makes subfolders appear to be autonomous Plone sites

Products.Doormat

A flexible doormat

collective.behavior.banner

Add decorative banners and sliders

plone.app.multilingual

Allows multilingual sites by translating content.

Rapido

Allows developers with a little knowledge of HTML and a little knowledge of Python to implement custom elements and insert them anywhere they want.

Plomino

Powerful and flexible web-based application builder for Plone

How to find add-ons¶

• https://plone.org/download/add-ons
• https://pypi.python.org/pypi - use the search form!
• https://github.com/collective >1200 repos
• https://github.com/plone >260 repos
• https://community.plone.org - ask the community
• google (e.g. Plone+Slider)
• ask in irc and on the mailing list

Installing Add-ons¶

Installation is a two-step process.

eggs =
    Plone
    Products.PloneFormGen
    plone.app.debugtoolbar

$ bin/buildout
$ bin/instance fg

PloneFormGen¶

There are many ways to create forms in Plone:

• Pure: html and python in a view
• Framework: z3c.form, formlib, deform
• TTW: Products.PloneFormGen

The basic concept of PloneFormGen is that you build a form by adding a Form Folder, to which you add form fields as content items. Fields are added, deleted, edited and moved just as with any other type of content. Form submissions may be automatically emailed and/or saved for download. There are many add-ons to PloneFormGen that provide additional field types and actions.

Let’s build a registration form:

• Activate PloneFormGen for this site via the add-on configuration panel in site setup
• Add an object of the new type ‘Form Folder’ in the site root. Call it “Registration”
• Save and view the result, a simple contact form that we may customize
• Click in QuickEdit
• Remove field “Subject”
• Add fields for food preference and shirt size
• Add a DataSave Adapter
• Customize the mailer

By the way, while PloneFormGen is good at what it does, it is not a good model for designing your own extensions. It was created before the Zope Component Architecture became widely used. The authors would write it much differently if they were starting from scratch.

Add Photo Gallery with collective.plonetruegallery¶

To advertise the conference we want to show some photos showing past conferences and the city where the conference is taking place.

Instead of creating new contenttypes for galleries, it integrates with the Plone functionality to choose different views for folderish contenttypes.

https://pypi.python.org/pypi/collective.plonetruegallery

• Activate the add-on
• Enable the behavior Plone True Gallery on the type Folder: http://localhost:8080/Plone/dexterity-types/Folder/@@behaviors
• Add a folder /the-event/location
• Upload some photos from lorempixel.com
• Enable the view galleryview

Internationalization¶

Plone can run the same site in many different languages.

We’re not doing this with the conference site since the lingua franca of the Plone community is English.

We would use the built-in addon https://pypi.python.org/pypi/plone.app.multilingual for this.

Building a multi-lingual site requires activating plone.app.multilingual, but no add-on is necessary to build a site in only one language. Just select a different site language when creating a Plone site, and all text in the user-interface will be switched to that language.

Summary¶

We are now able to customize and extend many parts of our website. We can even install extensions that add new functionality.

But:

• Can we submit talks now?
• Can we create lists with the most important properties of each talk?
• Can we allow a jury to vote on talks?

We often have to work with structured data. Up to a degree we can do all this TTW, but at some point we run into barriers. In the next part of the training, we’ll teach you how to break through these barriers.

What is a content type?¶

A content type is a kind of object that can store information and is editable by users. We have different content types to reflect the different kinds of information about which we need to collect and display information. Pages, folders, events, news items, files (binary) and images are all content types.

It is common in developing a web site that you’ll need customized versions of common content types, or perhaps even entirely new types.

Remember the requirements for our project? We wanted to be able to solicit and edit conference talks. We could use the Page content type for that purpose. But we need to make sure we collect certain bits of information about a talk and we couldn’t be sure to get that information if we just asked potential presenters to create a page. Also, we’ll want to be able to display talks featuring that special information, and we’ll want to be able to show collections of talks. A custom content type will be ideal.

The makings of a Plone content type¶

Every Plone content type has the following parts:

Schema

A definition of fields that comprise a content type; properties of an object.

FTI

The “Factory Type Information” configures the content type in Plone, assigns it a name, an icon, additional features and possible views to it.

Views

A view is a representation of the object and the content of its fields that may be rendered in response to a request. You may have one or more views for an object. Some may be visual — intended for display as web pages — others may be intended to satisfy AJAX requests and render content in formats like JSON or XML.

Dexterity and Archetypes - A Comparison¶

There are two content frameworks in Plone:

• Dexterity: new and the coming default.
• Archetypes: old, tried and tested. Widespread, used in many add-ons.
• Plone 4.x: Archetypes is the default, with Dexterity available.
• Plone 5.x: Dexterity is the default, with Archetypes available.
• For both, add and edit forms are created automatically from a schema.

What are the differences?

• Dexterity: New, faster, modular, no dark magic for getters and setters.
• Archetypes had magic setter/getter - use talk.getAudience() for the field audience.
• Dexterity: fields are attributes: talk.audience instead of talk.getAudience().

“Through The Web” or TTW, i.e. in the browser, without programming:

• Dexterity has a good TTW story.
• Archetypes has no TTW story.
• UML-modeling: ArchGenXML for Archetypes, agx for Dexterity

Approaches for Developers:

• Schema in Dexterity: TTW, XML, Python. Interface = schema, often no class needed.
• Schema in Archetypes: Schema only in Python.
• Dexterity: Easy permissions per field, easy custom forms.
• Archetypes: Permissions per field are hard, custom forms even harder.
• If you have to program for old sites you need to know Archetypes!
• If starting fresh, go with Dexterity.

Extending:

• Dexterity has Behaviors: easily extendable. Just activate a behavior TTW and your content type is e.g. translatable (plone.app.multilingual).
• Archetypes has archetypes.schemaextender. Powerful but not as flexible.

We have only used Dexterity for the last few years. We teach Dexterity and not Archetypes because it’s more accessible to beginners, has a great TTW story and is the future.

Views:

• Both Dexterity and Archetypes have a default view for content types.
• Browser Views provide custom views.
• You can generate views for content types in the browser without programming (using the plone.app.mosaic Add-on).
• Display Forms.

Modifying existing types¶

• Go to the control panel http://localhost:8080/Plone/@@dexterity-types

• Inspect some of the existing default types.

• Select the type News Item and add a new field Hot News of type Yes/No

• In another tab, add a News Item and you’ll see the new field.

• Go back to the schema-editor and click on Edit XML Field Model.

• Note that the only field in the XML schema of the News Item is the one we just added. All others are provided by behaviors.

• Edit the form-widget-type so it says:

  <form:widget type="z3c.form.browser.checkbox.SingleCheckBoxFieldWidget"/>
  

• Edit the News Item again. The widget changed from a radio field to a check box.

• The new field Hot News is not displayed when rendering the News Item. We’ll take care of this later.

Creating content types TTW¶

In this step we will create a content type called Talk and try it out. When it’s ready we will move the code from the web to the file system and into our own add-on. Later we will extend that type, add behaviors and a viewlet for Talks.

• Add new content type “Talk” and some fields for it:
  • Add new field “Type of talk”, type “Choice”. Add options: talk, keynote, training.
  • Add new field “Details”, type “Rich Text” with a maximal length of 2000.
  • Add new field “Audience”, type “Multiple Choice”. Add options: beginner, advanced, pro.
  • Check the behaviors that are enabled: Dublin Core metadata, Name from title. Do we need them all?
• Test the content type.
• Return to the control panel http://localhost:8080/Plone/@@dexterity-types
• Extend the new type: add the following fields:
  • “Speaker”, type: “Text line”
  • “Email”, type: “Email”
  • “Image”, type: “Image”, not required
  • “Speaker Biography”, type: “Rich Text”
• Test again.

Here is the complete XML schema created by our actions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

<model xmlns:lingua="http://namespaces.plone.org/supermodel/lingua"
     xmlns:users="http://namespaces.plone.org/supermodel/users"
     xmlns:security="http://namespaces.plone.org/supermodel/security"
     xmlns:marshal="http://namespaces.plone.org/supermodel/marshal"
     xmlns:form="http://namespaces.plone.org/supermodel/form"
     xmlns="http://namespaces.plone.org/supermodel/schema">
  <schema>
    <field name="type_of_talk" type="zope.schema.Choice">
      <description/>
      <title>Type of talk</title>
      <values>
        <element>Talk</element>
        <element>Training</element>
        <element>Keynote</element>
      </values>
    </field>
    <field name="details" type="plone.app.textfield.RichText">
      <description>Add a short description of the talk (max. 2000 characters)</description>
      <max_length>2000</max_length>
      <title>Details</title>
    </field>
    <field name="audience" type="zope.schema.Set">
      <description/>
      <title>Audience</title>
      <value_type type="zope.schema.Choice">
        <values>
          <element>Beginner</element>
          <element>Advanced</element>
          <element>Professionals</element>
        </values>
      </value_type>
    </field>
    <field name="speaker" type="zope.schema.TextLine">
      <description>Name (or names) of the speaker</description>
      <title>Speaker</title>
    </field>
    <field name="email" type="plone.schema.email.Email">
      <description>Adress of the speaker</description>
      <title>Email</title>
    </field>
    <field name="image" type="plone.namedfile.field.NamedBlobImage">
      <description/>
      <required>False</required>
      <title>Image</title>
    </field>
    <field name="speaker_biography" type="plone.app.textfield.RichText">
      <description/>
      <max_length>1000</max_length>
      <required>False</required>
      <title>Speaker Biography</title>
    </field>
  </schema>
</model>

Moving contenttypes into code¶

It’s awesome that we can do so much through the web. But it’s also a dead end if we want to reuse this content type in other sites.

Also, for professional development, we want to be able to use version control for our work, and we’ll want to be able to add the kind of business logic that will require programming.

So, we’ll ultimately want to move our new content type into a Python package. We’re missing some skills to do that, and we’ll cover those in the next couple of chapters.

Exercises¶

<model xmlns:lingua="http://namespaces.plone.org/supermodel/lingua"
       xmlns:users="http://namespaces.plone.org/supermodel/users"
       xmlns:security="http://namespaces.plone.org/supermodel/security"
       xmlns:marshal="http://namespaces.plone.org/supermodel/marshal"
       xmlns:form="http://namespaces.plone.org/supermodel/form"
       xmlns="http://namespaces.plone.org/supermodel/schema">
  <schema>
    <field name="title" type="zope.schema.TextLine">
      <title>Name</title>
    </field>
    <field name="email" type="plone.schema.email.Email">
      <title>Email</title>
    </field>
    <field name="homepage" type="zope.schema.URI">
      <required>False</required>
      <title>Homepage</title>
    </field>
    <field name="biography" type="plone.app.textfield.RichText">
      <required>False</required>
      <title>Biography</title>
    </field>
    <field name="company" type="zope.schema.TextLine">
      <required>False</required>
      <title>Company</title>
    </field>
    <field name="twitter_handle" type="zope.schema.TextLine">
      <required>False</required>
      <title>Twitter Handle</title>
    </field>
    <field name="irc_name" type="zope.schema.TextLine">
      <required>False</required>
      <title>IRC Handle</title>
    </field>
    <field name="image" type="plone.namedfile.field.NamedBlobImage">
      <required>False</required>
      <title>Image</title>
    </field>
  </schema>
</model>

Syntax¶

The syntax of Buildout configuration files is similar to classic ini files. You write a parameter name, an equals sign and the value. If you enter another value in the next line and indent it, Buildout understands that both values belong to the parameter name, and the parameter stores all values as a list.

A Buildout consists of multiple sections. Sections start with the section name in square brackets. Each section declares a different part of your application. As a rough analogy, your Buildout file is a cookbook with multiple recipes.

There is a special section, called [buildout]. This section can change the behavior of Buildout itself. The variable parts defines which of the existing sections should actually be used.

Recipes¶

Buildout itself has no idea how to install Zope. Buildout is a plugin based system, it comes with a small set of plugins to create configuration files and download eggs with their dependencies and the proper version. To install a Zope site, you need a third-party plugin. The plugins provide new recipes that you have to declare and configure in their own respective sections.

One example is the section

[instance]
recipe = plone.recipe.zope2instance
user = admin:admin

This uses the python package plone.recipe.zope2instance to create and configure the Zope 2 instance which we use to run Plone. All the lines after recipe = xyz are the configuration of the specified recipe.

References¶

Buildout allows you to use references in the configuration. A variable declaration may not only hold the variable value, but also a reference to where to look for the variable value.

If you have a big setup with many Plone sites with minor changes between each configuration, you can generate a template configuration, and each site references everything from the template and overrides just what needs to be changed.

Even in smaller buildouts this is a useful feature. We are using collective.recipe.omelette. A very practical recipe that creates a virtual directory that eases the navigation to the source code of each egg.

The omelette recipe needs to know which eggs to reference. We want the same eggs that our instance uses, so we reference the eggs of the instance instead of repeating the whole list.

Another example: Say you create configuration files for a webserver like nginx, you can define the target port for the reverse proxy by looking it up from the zope2instance recipe.

Configuring complex systems always involves a lot of duplication of information. Using references in the buildout configuration allows you to minimize these duplications.

A real life example¶

Let us walk through the buildout.cfg for the training and look at some important variables:

[buildout]
extends =
    http://dist.plone.org/release/5.0.6/versions.cfg
    versions.cfg
extends-cache = extends-cache

extensions = mr.developer
# Tell mr.developer to ask before updating a checkout.
always-checkout = true
show-picked-versions = true
sources = sources

# The directory this buildout is in. Modified when using vagrant.
buildout_dir = ${buildout:directory}

# We want to checkouts these eggs directly from GitHub
auto-checkout =
    ploneconf.site
#    starzel.votable_behavior

parts =
    checkversions
    codeintel
    instance
    mrbob
    packages
    robot
    test
    zopepy

eggs =
    Plone
    Pillow

# development tools
    z3c.jbot
    plone.reload
    Products.PDBDebugMode
    plone.app.debugtoolbar
    Products.PrintingMailHost

# TTW Forms (based on Archetypes)
    Products.PloneFormGen

# The addon we develop in the training
    ploneconf.site

# Voting on content
#    starzel.votable_behavior

zcml =

test-eggs +=
    ploneconf.site [test]

[instance]
recipe = plone.recipe.zope2instance
user = admin:admin
http-address = 8080
debug-mode = on
verbose-security = on
deprecation-warnings = on
eggs = ${buildout:eggs}
zcml = ${buildout:zcml}
file-storage = ${buildout:buildout_dir}/var/filestorage/Data.fs
blob-storage = ${buildout:buildout_dir}/var/blobstorage

[test]
recipe = zc.recipe.testrunner
eggs = ${buildout:test-eggs}
defaults = ['--auto-color', '-vvv']

[robot]
recipe = zc.recipe.egg
eggs =
    ${buildout:test-eggs}
    Pillow
    plone.app.robotframework[ride,reload,debug]

[packages]
recipe = collective.recipe.omelette
eggs = ${buildout:eggs}
location = ${buildout:buildout_dir}/packages

[codeintel]
recipe = corneti.recipes.codeintel
eggs = ${buildout:eggs}

[checkversions]
recipe = zc.recipe.egg
eggs = z3c.checkversions [buildout]

[zopepy]
recipe = zc.recipe.egg
eggs = ${buildout:eggs}
interpreter = zopepy
scripts =
    zopepy
    plone-generate-gruntfile
    plone-compile-resources

[mrbob]
recipe = zc.recipe.egg
eggs =
    mr.bob
    bobtemplates.plone

[sources]
ploneconf.site = git https://github.com/collective/ploneconf.site.git pushurl=git@github.com:collective/ploneconf.site.git
starzel.votable_behavior = git https://github.com/collective/starzel.votable_behavior.git pushurl=git://github.com/collective/starzel.votable_behavior.git

When you run ./bin/buildout without any arguments, Buildout will look for this file.

Let us look closer at some variables.

extends =
    http://dist.plone.org/release/5.0.6/versions.cfg

This line tells Buildout to read another configuration file. You can refer to configuration files on your computer or to configuration files on the Internet, reachable via http. You can use multiple configuration files to share configurations between multiple Buildouts, or to separate different aspects of your configuration into different files. Typical examples are version specifications, or configurations that differ between different environments.

eggs =
    Plone
    Pillow

# development tools
    z3c.jbot
    plone.reload
    Products.PDBDebugMode
    plone.app.debugtoolbar
    Products.PrintingMailHost

# TTW Forms (based on Archetypes)
    Products.PloneFormGen

# The addon we develop in the training
    ploneconf.site

# Voting on content
#    starzel.votable_behavior

zcml =

test-eggs +=
    ploneconf.site [test]

This is the list of eggs that we configure to be available for Zope. These eggs are put in the python path of the script bin/instance with which we start and stop Plone.

The egg Plone is a wrapper without code. Among its dependencies is Products.CMFPlone which is the egg that is at the center of Plone.

The rest are add-ons we already used or will use later. The last eggs are commented out so they will not be installed by Buildout.

The file versions.cfg that is included by the extends = ... statement holds the version pins:

[versions]
# dev tools
mr.developer = 1.34
Products.PDBDebugMode = 1.3.1
corneti.recipes.codeintel = 0.3
plone.app.debugtoolbar = 1.1.1
z3c.jbot = 0.7.2
Products.PrintingMailHost = 1.0

# pins for some Addons
Products.PloneFormGen = 1.8.1
Products.PythonField = 1.1.3
# ...

This is another special section. By default buildout will look for version pins in a section called [versions]. This is why we included the file versions.cfg.

Hello mr.developer!¶

There are many more important things to know, and we can’t go through them all in detail but I want to focus on one specific feature: mr.developer

With mr.developer you can declare which packages you want to check out from which version control system and which repository URL. You can check out sources from git, svn, bzr, hg and maybe more. Also, you can say that some sources are in your local file system.

mr.developer comes with a command, ./bin/develop. You can use it to update your code, to check for changes and so on. You can activate and deactivate your source checkouts. If you develop your extensions in eggs with separate checkouts, which is a good practice, you can plan releases by having all source checkouts deactivated, and only activate them when you write changes that require a new release. You can activate and deactivate eggs via the develop command or the Buildout configuration. You should always use the Buildout way. Your commit serves as documentation.

Extensible¶

You might have noticed that most if not all functionality is only available via plugins. One of the things that Buildout excels at without any plugin is the dependency resolution. You can help Plone in dependency resolution by declaring exactly which version of an egg you want. This is only one use case. Another one is much more important: If you want to have a repeatable Buildout, one that works two months from now also, you must declare all your egg versions. Else Buildout might install newer versions.

Be McGuyver¶

As you can see, you can build very complex systems with Buildout. It is time for some warnings. Be selective in your recipes. Supervisor is a program to manage running servers, and it’s pretty good. There is a recipe for it.

The configuration for this recipe is more complicated than the supervisor configuration itself! By using this recipe, you force others to understand the recipe’s specific configuration syntax and the supervisor syntax. For such cases, collective.recipe.template is a better match.

Another problem is error handling. Buildout tries to install a weird dependency you do not actually want? Buildout will not tell you where it is coming from.

If there is a problem, you can always run Buildout with -v to get more verbose output, sometimes it helps.

$ ./bin/buildout -v

If strange egg versions are requested, check the dependencies declaration of your eggs and your version pinnings. Here is an invaluable shell command that allows you to find all packages that depend on a particular egg and version:

$ grep your.egg.name.here /home/vagrant/buildout-cache/eggs/*.egg/EGG-INFO/requires.txt

Put the name of the egg with a version conflict as the first argument. Also, change the path to the buildout cache folder according to your installation (the vagrant buildout is assumed in the example).

Some parts of Buildout interpret egg names case sensitively, others don’t. This can result in funny problems.

Always check out the ordering of your extends, always use the annotate command of Buildout to see if it interprets your configuration differently than you. Restrict yourself to simple Buildout files. You can reference variables from other sections, you can even use a whole section as a template. We learned that this does not work well with complex hierarchies and had to abandon that feature.

In the chapter Buildout II: Getting Ready for Deployment we will have a look at a production-ready buildout for Plone that has many useful features.

Creating the package¶

Our own code has to be organized as a Python package, also called egg. An egg is a zip file or a directory that follows certain conventions. We are going to use bobtemplates.plone to create a skeleton project. We only need to fill in the blanks.

We create and enter the src directory (src is short for sources) and call a script called mrbob from our buildout’s bin directory:

$ mkdir src      # (if src does not exist already)
$ cd src
$ ../bin/mrbob -O ploneconf.site bobtemplates:plone_addon

We have to answer some questions about the add-on. We will press Enter (i.e. choosing the default value) for all questions except 3 (where you enter your GitHub username if you have one) and 5 (Plone version), where we enter 5.0.6:

--> What kind of package would you like to create? Choose between 'Basic', 'Dexterity', and 'Theme'. [Basic]:

--> Author's name [Philip Bauer]:

--> Author's email [bauer@starzel.de]:

--> Author's GitHub username: fulv

--> Package description [An add-on for Plone]:

--> Plone version [5.0.5]: 5.0.6

Generated file structure at /vagrant/buildout/src/ploneconf.site

If this is your first egg, this is a very special moment. We are going to create the egg with a script that generates a lot of necessary files. They all are necessary, but sometimes in a subtle way. It takes a while to understand their full meaning. Only last year I learned and understood why I should have a MANIFEST.in file. You can get along without one, but trust me, you get along better with a proper manifest file.

Inspecting the package¶

In src there is now a new folder ploneconf.site and in there is the new package. Let’s have a look at some of the files:

bootstrap-buildout.py, buildout.cfg, travis.cfg, .travis.yml, .coveragerc

You can ignore these files for now. They are here to create a buildout only for this egg to make testing it easier. Once we start writing tests for this package we will have another look at them.

README.rst, CHANGES.rst, CONTRIBUTORS.rst, docs/

The documentation, changelog, the list of contributors and the license of your egg goes in here.

setup.py

This file configures the package, its name, dependencies and some metadata like the author’s name and email address. The dependencies listed here are automatically downloaded when running buildout.

src/ploneconf/site/

The package itself lives inside a special folder structure. That seems confusing but is necessary for good testability. Our package contains a namespace package called ploneconf.site and because of this there is a folder ploneconf with a __init__.py and in there another folder site and in there finally is our code. From the buildout’s perspective our code is in your buildout directory/src/ploneconf.site/src/ploneconf/site/real code

configure.zcml (src/ploneconf/site/configure.zcml)

The phone book of the distribution. By reading it you can find out which functionality is registered using the component architecture.

setuphandlers.py (src/ploneconf/site/setuphandlers.py)

This holds code that is automatically run when installing and uninstalling our add-on.

interfaces.py (src/ploneconf/site/interfaces.py)

Here a browserlayer is defined in a straightforward python class. We will need it later.

testing.py

This holds the setup for running tests.

tests/

This holds the tests.

browser/

This directory is a python package (because it has a __init__.py) and will by convention hold most things that are visible in the browser.

browser/configure.zcml

The phonebook of the browser package. Here views, resources and overrides are registered.

browser/overrides/

This add-on is already configured to allow overriding existing default Plone templates.

browser/static/

A directory that holds static resources (images/css/js). The files in here will be accessible through URLs like ++resource++ploneconf.site/myawesome.css

profiles/default/

This folder contains the GenericSetup profile. During the training we will put some XML files here that hold configuration for the site.

profiles/default/metadata.xml

Version number and dependencies that are auto-installed when installing our add-on.

Including the package in Plone¶

Before we can use our new package we have to tell Plone about it. Look at buildout.cfg and see how ploneconf.site is included in auto-checkout, eggs and test:

auto-checkout +=
    ploneconf.site
#    starzel.votable_behavior

parts =
    checkversions
    codeintel
    instance
    mrbob
    packages
    robot
    test
    zopepy

eggs =
    Plone
    Pillow

# development tools
    z3c.jbot
    plone.api
    plone.reload
    Products.PDBDebugMode
    plone.app.debugtoolbar
    Products.PrintingMailHost

# TTW Forms (based on Archetypes)
    Products.PloneFormGen

# The add-on we develop in the training
    ploneconf.site

# Voting on content
#    starzel.votable_behavior

zcml =

test-eggs +=
    ploneconf.site [test]

This tells Buildout to add the egg ploneconf.site. The sources for this eggs are defined in the section [sources] at the bottom of buildout.cfg.

[sources]
ploneconf.site = git https://github.com/collective/ploneconf.site.git pushurl=git@github.com:collective/ploneconf.site.git
starzel.votable_behavior = git https://github.com/collective/starzel.votable_behavior.git pushurl=git://github.com/collective/starzel.votable_behavior.git

This tells buildout not to download it from pypi but to do a checkout from GitHub put the code in src/ploneconf.site.

[sources]
ploneconf.site = fs ploneconf.site path=src
starzel.votable_behavior = git https://github.com/collective/starzel.votable_behavior.git pushurl=git://github.com/collective/starzel.votable_behavior.git

Now run buildout to reconfigure Plone with the updated configuration:

$ ./bin/buildout

After restarting Plone with ./bin/instance fg the new add-on ploneconf.site is available for install like PloneFormGen or Plone True Gallery.

We will not install it now since we did not add any of our own code or configuration yet. Let’s do that next.

Changing a widget¶

Dexterity XML is very powerful. By editing it (not all features have a UI) you should be able to do everything you can do with a Python schema. Sadly not every feature also is exposed in the UI of the dexterity schema editor. For example you cannot yet change the widgets or permissions for fields in the UI. We need to do this in the xml- or python-schema.

Our talks use a dropdown for type_of_talk and a multiselect for audience. Radio-buttons and checkboxes would be the better choice here. Modify the XML to make that change happen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<?xml version="1.0" encoding="UTF-8"?>
<model xmlns="http://namespaces.plone.org/supermodel/schema"
       xmlns:form="http://namespaces.plone.org/supermodel/form"
       xmlns:i18n="http://xml.zope.org/namespaces/i18n"
       xmlns:lingua="http://namespaces.plone.org/supermodel/lingua"
       xmlns:marshal="http://namespaces.plone.org/supermodel/marshal"
       xmlns:security="http://namespaces.plone.org/supermodel/security"
       xmlns:users="http://namespaces.plone.org/supermodel/users">
  <schema>
    <field name="type_of_talk" type="zope.schema.Choice"
      form:widget="z3c.form.browser.radio.RadioFieldWidget">
      <description />
      <title>Type of talk</title>
      <values>
        <element>Talk</element>
        <element>Training</element>
        <element>Keynote</element>
      </values>
    </field>
    <field name="details" type="plone.app.textfield.RichText">
      <description>Add a short description of the talk (max. 2000 characters)</description>
      <max_length>2000</max_length>
      <title>Details</title>
    </field>
    <field name="audience" type="zope.schema.Set"
      form:widget="z3c.form.browser.checkbox.CheckBoxFieldWidget">
      <description />
      <title>Audience</title>
      <value_type type="zope.schema.Choice">
        <values>
          <element>Beginner</element>
          <element>Advanced</element>
          <element>Professionals</element>
        </values>
      </value_type>
    </field>
    <field name="speaker" type="zope.schema.TextLine">
      <description>Name (or names) of the speaker</description>
      <title>Speaker</title>
    </field>
    <field name="email" type="plone.schema.email.Email">
      <description>Adress of the speaker</description>
      <title>Email</title>
    </field>
    <field name="image" type="plone.namedfile.field.NamedBlobImage">
      <description />
      <required>False</required>
      <title>Image</title>
    </field>
    <field name="speaker_biography" type="plone.app.textfield.RichText">
      <description />
      <max_length>1000</max_length>
      <required>False</required>
      <title>Speaker Biography</title>
    </field>
  </schema>
</model>

Protect fields with permissions¶

We also want to have a add a new field room to show where a talk will take place. Our case-study says the speakers will submit the talks online. How should they know in which room the talk will take place (if it got accepted at all)? So we need to hide this field from them by requiring a permission that they do not have.

Let’s assume the prospective speakers will not have the permission to review content (i.e. edit submitted content and publish it) but the organizing commitee has. You can then protect the field using the permission Review portal content in this case the name of the permission-utility for this permission: cmf.ReviewPortalContent.

We only want to prevent writing, not reading, so we’ll only manage the write-permission:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

<?xml version="1.0" encoding="UTF-8"?>
<model xmlns="http://namespaces.plone.org/supermodel/schema"
       xmlns:form="http://namespaces.plone.org/supermodel/form"
       xmlns:i18n="http://xml.zope.org/namespaces/i18n"
       xmlns:lingua="http://namespaces.plone.org/supermodel/lingua"
       xmlns:marshal="http://namespaces.plone.org/supermodel/marshal"
       xmlns:security="http://namespaces.plone.org/supermodel/security"
       xmlns:users="http://namespaces.plone.org/supermodel/users">
  <schema>
    <field name="type_of_talk" type="zope.schema.Choice"
      form:widget="z3c.form.browser.radio.RadioFieldWidget">
      <description />
      <title>Type of talk</title>
      <values>
        <element>Talk</element>
        <element>Training</element>
        <element>Keynote</element>
      </values>
    </field>
    <field name="details" type="plone.app.textfield.RichText">
      <description>Add a short description of the talk (max. 2000 characters)</description>
      <max_length>2000</max_length>
      <title>Details</title>
    </field>
    <field name="audience"
           type="zope.schema.Set"
           form:widget="z3c.form.browser.checkbox.CheckBoxFieldWidget">
      <description />
      <title>Audience</title>
      <value_type type="zope.schema.Choice">
        <values>
          <element>Beginner</element>
          <element>Advanced</element>
          <element>Professionals</element>
        </values>
      </value_type>
    </field>
    <field name="room"
           type="zope.schema.Choice"
           form:widget="z3c.form.browser.radio.RadioFieldWidget"
           security:write-permission="cmf.ReviewPortalContent">
      <description></description>
      <required>False</required>
      <title>Room</title>
      <values>
        <element>101</element>
        <element>201</element>
        <element>Auditorium</element>
      </values>
    </field>
    <field name="speaker" type="zope.schema.TextLine">
      <description>Name (or names) of the speaker</description>
      <title>Speaker</title>
    </field>
    <field name="email" type="plone.schema.email.Email">
      <description>Adress of the speaker</description>
      <title>Email</title>
    </field>
    <field name="image" type="plone.namedfile.field.NamedBlobImage">
      <description />
      <required>False</required>
      <title>Image</title>
    </field>
    <field name="speaker_biography" type="plone.app.textfield.RichText">
      <description />
      <max_length>1000</max_length>
      <required>False</required>
      <title>Speaker Biography</title>
    </field>
  </schema>
</model>

$ cd src
$ ../bin/mrbob -O collective.behavior.myfeature bobtemplates:plone_addon

<property name="global_allow">False</property>

A simple browser view¶

Before writing the talk view itself we step back and talk a little about views and templates.

A view in Plone is usually a BrowserView. It can hold a lot of cool python code but we will first focus on the template.

Edit the file browser/configure.zcml and register a new view called training:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<configure
  xmlns="http://namespaces.zope.org/zope"
  xmlns:browser="http://namespaces.zope.org/browser"
  xmlns:plone="http://namespaces.plone.org/plone"
  i18n_domain="ploneconf.site">

  <!-- Set overrides folder for Just-a-Bunch-Of-Templates product -->
  <include package="z3c.jbot" file="meta.zcml" />
  <browser:jbot
    directory="overrides"
    layer="ploneconf.site.interfaces.IPloneconfSiteLayer"
    />

  <!-- Publish static files -->
  <browser:resourceDirectory
    name="ploneconf.site"
    directory="static"
    />

  <browser:page
    name="training"
    for="*"
    template="templates/training.pt"
    permission="zope2.View"
    />

</configure>

Add a file browser/templates/training.pt

<h1>Hello World</h1>

• Restart Plone and open http://localhost:8080/Plone/@@training.
• You should now see “Hello World”.

We now have everything in place to learn about page templates.

TAL and TALES¶

Let’s add some magic and modify the <p>-tag:

<p tal:content="string:blue">red</p>

This will result in:

<p>blue</p>

Without restarting Plone open http://localhost:8080/Plone/@@training.

The same happens with attributes. Replace the <p>-line with:

<a href="http://www.mssharepointconference.com"
   tal:define="a_fine_url string:https://www.ploneconf.org/"
   tal:attributes="href a_fine_url"
   tal:content="string:An even better conference">
    A sharepoint conference
</a>

results in:

<a href="https://www.ploneconf.org/">
    An even better conference
</a>

We used three TAL-Attributes here. This is the complete list of TAL-attributes:

tal:define

define variables. We defined the variable a_fine_url to the string “https://www.ploneconf.org/“

tal:content

replace the content of an element. We replaced the default content above with “An even better conference”

tal:attributes

dynamically change element attributes. We set the HTML attribute href to the value of the variable a_fine_url

tal:condition

tests whether the expression is true or false, and outputs or omits the element accordingly.

tal:repeat

repeats an iterable element, in our case the list of talks.

tal:replace

replace the content of an element, like tal:content does, but removes the element only leaving the content.

tal:omit-tag

remove an element, leaving the content of the element.

tal:on-error

handle errors.

<p tal:define="title context/title"
   tal:content="python:title.upper()">
   A big title
</p>

<p tal:define="talks python:['Dexterity for the win!',
                             'Deco is the future',
                             'A keynote on some weird topic',
                             'The talk that I did not submit']"
   tal:content="python:talks[0]">
    A talk
</p>

tal:condition="talks"

tal:condition="python:len(talks) >= 1"

tal:condition="python:'Deco is the future' in talks"

<p tal:define="talks python:['Dexterity for the win!',
                             'Deco is the future',
                             'A keynote on some weird topic',
                             'The talk that I did not submit']"
   tal:repeat="talk talks"
   tal:content="talk">
   A talk
</p>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

 <ul tal:define="talks python:['Dexterity for the win!',
                               'Deco is the future',
                               'A keynote on some weird topic',
                               'The talk that I did not submit']">
     <li tal:repeat="talk talks"
         tal:content="talk">
           A talk
     </li>
     <li tal:condition="not:talks">
           Sorry, no talks yet.
     </li>
 </ul>

<p tal:content="context/title"></p>

<p tal:content="context/REQUEST/form"></p>

<p tal:content="context/title | context/id"></p>

<p tal:replace="talk/average_rating | nothing"></p>

<p tal:replace="nothing">
    this comment will not be rendered
</p>

1
2
3
4
5
6

<dl tal:define="path_variables_dict econtext">
  <tal:vars tal:repeat="variable path_variables_dict">
    <dt>${variable}</dt>
    <dd>${python:path_variables_dict[variable]}</dd>
  </tal:vars>
</dl>

1
2
3
4
5
6

<dl tal:define="path_variables_dict CONTEXTS">
  <tal:vars tal:repeat="variable path_variables_dict">
    <dt tal:content="variable"></dt>
    <dd tal:content="python:path_variables_dict[variable]"></dd>
  </tal:vars>
</dl>

<tal:block attribute="expression">some content</tal:block>

<tal:block define="id template/id">
...
  <b tal:content="id">The id of the template</b>
...
</tal:block>

<tal:news condition="python:context.portal_type == 'News Item'">
    This text is only visible if the context is a News Item
</tal:news>

<p>
    <img tal:define="tag string:<img src='https://plone.org/logo.png'>"
         tal:replace="tag">
</p>

<p>
    &lt;img src='https://plone.org/logo.png'&gt;
</p>

<p>
    <img tal:define="tag string:<img src='https://plone.org/logo.png'>"
         tal:replace="structure tag">
</p>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

  <table tal:define="talks python:[{'title':'Dexterity for the win!',
                                    'subjects':('content-types', 'dexterity')},
                                   {'title':'Deco is the future',
                                    'subjects':('layout', 'deco')},
                                   {'title':'The State of Plone',
                                    'subjects':('keynote',) },
                                   {'title':'Diazo designs dont suck!',
                                    'subjects':('design', 'diazo', 'xslt')}
                                  ]">
      <tr>
          <th>Title</th>
          <th>Topics</th>
      </tr>
      <tr tal:repeat="talk talks">
          <td tal:content="talk/title">A talk</td>
          <td tal:define="subjects talk/subjects">
              <span tal:repeat="subject subjects"
                    tal:replace="subject">
              </span>
          </td>
      </tr>
  </table>

Plone 5¶

Plone 5 uses a new rendering engine called Chameleon. Using the integration layer five.pt it is fully compatible with the normal TAL syntax but offers some additional features:

You can use ${...} as short-hand for text insertion in pure html effectively making tal:content and tal:attributes obsolete. Here are some examples:

Plone 4 and Plone 5:

1
2
3
4
5

<a tal:attributes="href string:${context/absolute_url}?ajax_load=1;
                   class python:context.portal_type.lower().replace(' ', '')"
   tal:content="context/title">
   The Title of the current object
</a>

Plone 5 (and Plone 4 with five.pt) :

1
2
3
4

<a href="${context/absolute_url}?ajax_load=1"
   class="${python:context.portal_type.lower().replace(' ', '')}">
   ${python:context.title}
</a>

You can also add pure python into the templates:

1
2
3
4
5
6
7
8

<div>
  <?python
  someoptions = dict(
      id=context.id,
      title=context.title)
  ?>
  This object has the id "${python:someoptions['id']}"" and the title "${python:someoptions['title']}".
</div>

Exercise 1¶

Modify the following template and one by one solve the following problems: :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>
    <tr tal:repeat="talk talks">
        <td tal:content="talk/title">A talk</td>
        <td tal:define="subjects talk/subjects">
            <span tal:repeat="subject subjects"
                  tal:replace="subject">
            </span>
        </td>
    </tr>
</table>

1. Display the subjects as comma-separated.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>
    <tr tal:repeat="talk talks">
        <td tal:content="talk/title">A talk</td>
        <td tal:define="subjects talk/subjects">
            <span tal:replace="python:', '.join(subjects)">
            </span>
        </td>
    </tr>
</table>

2. Turn the title in a link to the URL of the talk if there is one.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>
    <tr tal:repeat="talk talks">
        <td>
            <a tal:attributes="href talk/url | nothing"
               tal:content="talk/title">
               A talk
            </a>
        </td>
        <td tal:define="subjects talk/subjects">
            <span tal:replace="python:', '.join(subjects)">
            </span>
        </td>
    </tr>
</table>

3. If there is no URL, turn it into a link to a google search for that talk’s title:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>
    <tr tal:repeat="talk talks">
        <td>
            <a tal:define="google_url string:https://www.google.com/search?q=${talk/title}"
               tal:attributes="href talk/url | google_url"
               tal:content="talk/title">
               A talk
            </a>
        </td>
        <td tal:define="subjects talk/subjects">
            <span tal:replace="python:', '.join(subjects)">
            </span>
        </td>
    </tr>
</table>

4. Add alternating the CSS classes ‘odd’ and ‘even’ to the <tr>. (repeat.<name of item in loop>.odd is True if the ordinal index of the current iteration is an odd number)

   Use some CSS to test your solution:

   <style type="text/css">
     tr.odd {background-color: #ddd;}
   </style>
   

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>
    <tr tal:repeat="talk talks"
        tal:attributes="class python: 'odd' if repeat.talk.odd else 'even'">
        <td>
            <a tal:define="google_url string:https://www.google.com/search?q=${talk/title};
                           "
               tal:attributes="href talk/url | google_url;
                               "
               tal:content="talk/title">
               A talk
            </a>
        </td>
        <td tal:define="subjects talk/subjects">
            <span tal:replace="python:', '.join(subjects)">
            </span>
        </td>
    </tr>
</table>

5. Only use python expressions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>
    <tr tal:repeat="talk python:talks"
        tal:attributes="class python: 'odd' if repeat.talk.odd else 'even'">
        <td>
            <a tal:attributes="href python:talk.get('url', 'https://www.google.com/search?q=%s' % talk['title'])"
               tal:content="python:talk['title']">
               A talk
            </a>
        </td>
        <td tal:content="python:', '.join(talk['subjects'])">
        </td>
    </tr>
</table>

6. Use the new syntax of Plone 5

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>

    <tr tal:repeat="talk python:talks"
        class="${python: 'odd' if repeat.talk.odd else 'even'}">
        <td>
            <a href="${python:talk.get('url', 'https://www.google.com/search?q=%s' % talk['title'])}">
                ${python:talk['title']}
            </a>
        </td>
        <td>
            ${python:', '.join(talk['subjects'])}
        </td>
    </tr>
</table>

7. Sort the talks alphabetically by title

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<table tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'}
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>

<?python from operator import itemgetter ?>

    <tr tal:repeat="talk python:sorted(talks, key=itemgetter('title'))"
        class="${python: 'odd' if repeat.talk.odd else 'even'}">
        <td>
            <a href="${python:talk.get('url', 'https://www.google.com/search?q=%s' % talk['title'])}">
                ${python:talk['title']}
            </a>
        </td>
        <td>
            ${python:', '.join(talk['subjects'])}
        </td>
    </tr>
</table>

METAL and macros¶

Why is our output so ugly? How do we get our html to render in Plone the UI?

We use METAL (Macro Extension to TAL) to define slots that we can fill and macros that we can reuse.

We add to the <html> tag:

metal:use-macro="context/main_template/macros/master"

And then wrap the code we want to put in the content area of Plone in:

<metal:content-core fill-slot="content-core">
    ...
</metal:content-core>

This will put our code in a section defined in the main_template called “content-core”.

The template should now look like below when we exlude the last exercise.

Here also added the css-class listing to the table. It is one of many css-classes used by Plone that you can reuse in your projects:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      lang="en"
      metal:use-macro="context/main_template/macros/master"
      i18n:domain="ploneconf.site">
<body>

<metal:content-core fill-slot="content-core">

<table class="listing"
       tal:define="talks python:[{'title': 'Dexterity is the new default!',
                                  'subjects': ('content-types', 'dexterity')},
                                 {'title': 'Mosaic will be the next big thing.',
                                  'subjects': ('layout', 'deco', 'views'),
                                  'url': 'https://www.youtube.com/watch?v=QSNufxaYb1M'},
                                 {'title': 'The State of Plone',
                                  'subjects': ('keynote',) },
                                 {'title': 'Diazo is a powerful tool for theming!',
                                  'subjects': ('design', 'diazo', 'xslt')},
                                 {'title': 'Magic templates in Plone 5',
                                  'subjects': ('templates', 'TAL'),
                                  'url': 'http://www.starzel.de/blog/magic-templates-in-plone-5'},
                                ]">
    <tr>
        <th>Title</th>
        <th>Topics</th>
    </tr>

    <tr tal:repeat="talk python:talks"
        class="${python: 'odd' if repeat.talk.odd else 'even'}">
        <td>
            <a href="${python:talk.get('url', 'https://www.google.com/search?q=%s' % talk['title'])}">
                ${python:talk['title']}
            </a>
        </td>
        <td>
            ${python:', '.join(talk['subjects'])}
        </td>
    </tr>
</table>

</metal:content-core>

</body>
</html>

<div metal:define-macro="my_macro">
    <p>I can be reused</p>
</div>

<browser:page
  for="*"
  name="abunchofmacros"
  template="templates/macros.pt"
  permission="zope2.View"
  />

<div metal:use-macro="context/@@abunchofmacros/my_macro">
    Instead of this the content of the macro will appear...
</div>

<div metal:use-macro="python:context.restrictedTraverse('abunchofmacros')['my_macro']">
    Instead of this the content of the macro will appear...
</div>

Accessing Plone from the template¶

In our template we have access to the context object on which the view is called on, the browser view itself (i.e. all python methods we’ll put in the view later on), the request and response objects and with these we can get almost anything.

In templates we can also access other browser views. Some of those exist to provide easy access to methods we often need:

tal:define="context_state context/@@plone_context_state;
            portal_state context/@@plone_portal_state;
            plone_tools context/@@plone_tools;
            plone_view context/@@plone;"

@@plone_context_state

The BrowserView plone.app.layout.globals.context.ContextState holds useful methods having to do with the current context object such as is_default_page()

@@plone_portal_state

The BrowserView plone.app.layout.globals.portal.PortalState holds methods for the portal like portal_url()

@@plone_tools

The BrowserView plone.app.layout.globals.tools.Tools gives access to the most important tools like plone_tools/catalog

These are very widely used and there are many more.

What we missed¶

There are some things we did not cover so far:

tal:condition="exists:expression"

checks if an object or an attribute exists (seldom used)

tal:condition="nocall:context"

to explicitly not call a callable.

If we refer to content objects, without using the nocall: modifier these objects are unnecessarily rendered in memory as the expression is evaluated.

i18n:translate and i18n:domain

the strings we put in templates can be translated automatically.

There is a lot more about TAL, TALES and METAL that we have not covered. You’ll only learn it if you keep reading, writing and customizing templates.

The view for News Items¶

We want to show the date a News Item is published. This way people can see at a glance if they are looking at current or old news.

To do this we will customize the template that is used to render News Items.

We use z3c.jbot for overriding templates. The package already has the necessary configuration in browser/configure.zcml.

Find the file newsitem.pt in packages/plone/app/contenttypes/browser/templates/ (in vagrant this directory is in /home/vagrant/packages, otherwise it is in your buildout directory).

The file looks like this:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
    xmlns:tal="http://xml.zope.org/namespaces/tal"
    xmlns:metal="http://xml.zope.org/namespaces/metal"
    xmlns:i18n="http://xml.zope.org/namespaces/i18n"
    lang="en"
    metal:use-macro="context/main_template/macros/master"
    i18n:domain="plone">
<body>

<metal:content-core fill-slot="content-core">
<metal:content-core define-macro="content-core"
                    tal:define="toc context/table_of_contents|nothing;">
  <div id="parent-fieldname-text"
      tal:condition="context/text"
      tal:content="structure python:context.text.output_relative_to(view.context)"
      tal:attributes="class python: toc and 'pat-autotoc' or ''" />
</metal:content-core>
</metal:content-core>

</body>
</html>

Note the following:

• Like almost all Plone templates, it uses metal:use-macro=”context/main_template/macros/master” to use the main_template
• This template fills the same slot content-core as the template you created in the last chapter. This means the heading and description are displayed by the main_template.
• The image and image caption that is provided by the behavior is not part of the template.

Copy that file into the folder browser/overrides/ of our package. If you use vagrant you’d have to use:

cp /home/vagrant/packages/plone/app/contenttypes/browser/templates/newsitem.pt /vagrant/buildout/src/ploneconf.site/src/ploneconf/site/browser/overrides/

• Rename the new file from newsitem.pt to plone.app.contenttypes.browser.templates.newsitem.pt. z3c.jbot allows you to override templates by putting a file inside a special directory with a canonical name (i.e. the path of the file separated by . plus the original filename).
• Restart Plone

Now Plone will use the new file to override the original one.

Edit the new file plone.app.contenttypes.browser.templates.newsitem.pt and insert the following before the <div id="parent-fieldname-text"...:

<p tal:content="python: context.Date()">
    The current Date
</p>

Since we use Plone 5 and Chameleon we could also write:

<p>
    ${python: context.Date()}
</p>

• Open an existing news item in the browser

This will show something like: 2015-02-21T12:01:31+01:00. Not very user-friendly. Let’s extend the code and use one of many helpers Plone offers.

<p>
    ${python: plone_view.toLocalizedTime(context.Date())}
</p>

This will render Feb 21, 2015.

• plone_view is the BrowserView Products.CMFPlone.browser.ploneview.Plone and it is defined in the main_template (Products/CMFPlone/browser/templates/main_template.pt) of Plone 5 like this plone_view context/@@plone; and thus always available.
• The method toLocalizedTime() runs a date object through Plone’s translation_service and returns the Date in the current locales format, thus transforming 2015-02-21T12:01:31+01:00 to Feb 21, 2015.

The same in a slightly different style:

<p tal:define="toLocalizedTime nocall:context/@@plone/toLocalizedTime;
               date python:context.Date()"
   tal:content="python:toLocalizedTime(date)">
        The current Date in its local short format
</p>

Here we first get the Plone view and then the method toLocalizedTime() and we use nocall: to prevent the method toLocalizedTime() from being called, since we only want to make it available for later use.

We could also leave the formatting to the frontend. Plone 5 comes with the moment pattern that uses the library moment.js to format dates. Try the relative calendar format:

<p class="pat-moment"
   data-pat-moment="format:calendar">
    ${python: context.Date()}
</p>

Now we should see the date in a user-friendly format like Today at 12:01 PM. Experiment with other formats such as calendar and LT.

The Summary View¶

We use the view “Summary View” to list news releases. They should also have the date. The template associated with that view is listing_summary.pt.

Let’s look for the template folder_summary_view.pt:

plone/app/contenttypes/browser/templates/listing_summary.pt

The file looks like this:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
    xmlns:tal="http://xml.zope.org/namespaces/tal"
    xmlns:metal="http://xml.zope.org/namespaces/metal"
    xmlns:i18n="http://xml.zope.org/namespaces/i18n"
    lang="en"
    metal:use-macro="context/main_template/macros/master"
    i18n:domain="plone">
<body>

<metal:content-core fill-slot="content-core">
<metal:block use-macro="context/@@listing_view/macros/content-core">

  <metal:entries fill-slot="entries">
    <metal:block use-macro="context/@@listing_view/macros/entries">
      <metal:entry fill-slot="entry">

        <article class="tileItem" tal:define="obj item/getObject">
          <h2 class="tileHeadline" metal:define-macro="listitem">
            <a class="summary url"
                tal:attributes="href item_link;
                                title item_type"
                tal:content="item_title">
              Item Title
            </a>
          </h2>

          <div metal:use-macro="context/@@listing_view/macros/document_byline"></div>

          <div class="tileImage"
               tal:condition="item_has_image"
               tal:attributes="class python: 'tileImage' if item_description else 'tileImageNoFloat'">
            <a tal:attributes="href item_link">
              <img tal:define="scales obj/@@images;
                               scale python:scales.scale('image', 'thumb')"
                  tal:replace="structure python:scale and scale.tag() or None" />
            </a>
          </div>

          <div class="tileBody" tal:condition="item_description">
            <span class="description" tal:content="item_description">
              description
            </span>
          </div>

          <div class="tileFooter">
            <a tal:attributes="href item_link"
                i18n:translate="read_more">
              Read More&hellip;
            </a>
          </div>

          <div class="visualClear"><!-- --></div>

        </article>

      </metal:entry>
    </metal:block>
  </metal:entries>

</metal:block>
</metal:content-core>

</body>
</html>

Note the following:

• Unlike newsitem.pt the file does not display data from a context but obviously pre-defined variables like item, item_link, item_type or item_description.
• It reuses multiple macros of a view context/@@listing_view.
• The variables are most likely defined in the macro entries of that view.

Copy it to browser/overrides/ and rename it to plone.app.contenttypes.browser.templates.listing_summary.pt.

Add the following after line 28:

<p tal:condition="python:item_type == 'News Item'">
  ${python:plone_view.toLocalizedTime(item.Date())}
</p>

After you restart the instance and look at the new folder again you’ll see the dates. z3c.jbot needs a restart to pick up the new file. When you only change a existing override you don’t have to restart.

The addition renders the date of the respective objects that the template iterates over (hence item instead of context since context would be either a collection aggregating the news items or a folder containing a news item).

The date is only displayed if the variable item_type is News Item.

Let’s take a closer look at that template. How does it know that item_type is the name of the content type?

The first step to uncovering that secret is line 14 of listing_summary.pt:

<metal:block use-macro="context/@@listing_view/macros/entries">

use-macro tells Plone to reuse the macro entries from the view listing_view. That view is defined in packages/plone/app/contenttypes/browser/configure.zcml. It uses the template plone/app/contenttypes/browser/templates/listing.pt. That makes overriding that much easier.

That template listing.pt defines the slot entries like this:

<metal:listingmacro define-macro="listing">
  <tal:results define="batch view/batch">
    <tal:listing condition="batch">
      <div class="entries" metal:define-slot="entries">
        <tal:entries repeat="item batch" metal:define-macro="entries">
          <tal:block tal:define="obj item/getObject;
                                 item_url item/getURL;
                                 item_id item/getId;
                                 item_title item/Title;
                                 item_description item/Description;
                                 item_type item/PortalType;
                                 item_modified item/ModificationDate;
                                 item_created item/CreationDate;
                                 item_icon item/getIcon;
                                 item_type_class python:'contenttype-' + view.normalizeString(item_type);
                                 item_wf_state item/review_state;
                                 item_wf_state_class python:'state-' + view.normalizeString(item_wf_state);
                                 item_creator item/Creator;
                                 item_link python:item_type in view.use_view_action and item_url+'/view' or item_url;
                                 item_has_image python:view.has_image(obj);
                                 item_is_event python:view.is_event(obj)">

...

Here the item_type is defined as item_type item/PortalType. Let’s dig a little deeper and find out what item and PortalType are.

tal:repeat="item batch" tells the template to iterate over an iterable batch which is defined as batch view/batch.

view is always the BrowserView for which the template is registered. In our case this is either plone.app.contenttypes.browser.collection.CollectionView if you called that view on a collection, or plone.app.contenttypes.browser.folder.FolderView for folders. You might remember that both are defined in configure.zcml

Luckily the first is a class that inherits from the second:

class CollectionView(FolderView):

batch() is a method in FolderView that turns results into batches. results exists in both classes. This means, in case the item we are looking at is a collection, the method results() of CollectionView, will be used; and in case it’s a folder, the one in FolderView.

So batch is a list of items. The way it is created is actually pretty complicated and makes use of a couple of packages to create a filtered (through plone.app.querystring) list of optimized representations (through plone.app.contentlisting) of items. For now it is enough to know that item represents one of the items in the list of News Items.

The template listing_summary.pt is extraordinary in its heavy use of nested macros. Most of the templates you will write are much simpler and easier to read.

It can be hard to understand templates as complicated as these, but there is help to be found if you know Python: use pdb to debug templates line by line.

Add the following to line 29 just before our additions:

<?python import pdb; pdb.set_trace() ?>

When you reload the page and look at the terminal you see you have the pdb console and can inspect the template at its current state by looking at the variable econtext. You can now simply look up what item ` and `PortalType are:

(pdb) pp econtext
[...]
'context': <Collection at /Plone/news/aggregator>,
'context_state': <Products.Five.metaclass.ContextState object at 0x10b7f50d0>,
'default': <object object at 0x100294c50>,
'dummy': None,
'here': <Collection at /Plone/news/aggregator>,
'isRTL': False,
'item': <plone.app.contentlisting.catalog.CatalogContentListingObject instance at /Plone/news/hot-news>,
'item_created': '2016-10-08T15:04:17+02:00',
'item_creator': 'admin',
[...]
(pdb) item = econtext['item']
(pdb) item
<plone.app.contentlisting.catalog.CatalogContentListingObject instance at /Plone/news/hot-news>

As discovered above, item is a instance of plone.app.contentlisting.catalog.CatalogContentListingObject. It has several methods and properties:

(pdb) pp dir(item)
[...]
'Language',
'ModificationDate',
'PortalType',
'Publisher',
'ReviewStateClass',
'Rights',
[...]

PortalType is a method that returns the name of the items content-type.

(pdb) item.PortalType()
'News Item'

Finding the right template¶

We changed the display of the listing of news items at http://localhost:8080/Plone/news. But how do we know which template to customize?

If you don’t know which template is used by the page you’re looking at, you can make an educated guess. Start a debug session or use plone.app.debugtoolbar.

1. We could check the HTML with Firebug and look for a structure in the content area that looks unique. We could also look for the CSS class of the body

   <body class="template-summary_view portaltype-collection site-Plone section-news subsection-aggregator icons-on userrole-anonymous" dir="ltr">
   

   The class template-summary_view tells us that the name of the view (but not necessarily the name of the template) is summary_view. So we could search all *.zcml-Files for name="summary_view" or search all templates called summary_view.pt and probably find the view and also the corresponding template. But only probably because it would not tell us if the template is already being overridden.

   A foolproof way to verify your guess is to modify the template and reload the page. If your modification shows up you obviously found the correct file.

2. The safest method is using plone.app.debugtoolbar. We already have it in our buildout and only need to install it. It adds a “Debug” dropdown menu on top of the page. The section “Published” shows the complete path to the template that is used to render the page you are seeing.

3. The debug session to find the template is a little more complicated. Since we have Products.PDBDebugMode in our buildout we can call /pdb on our page. We cannot put a pdb in the templates since we do not know (yet) which template to put the pdb in.

   The object that the URL points to is by default self.context. But the first problem is that the URL we’re seeing is not the URL of the collection we want to modify. This is because the collection is the default page of the folder news.

   (Pdb) self.context
   <Folder at /Plone/news>
   (Pdb) obj = self.context.aggregator
   (Pdb) obj
   <Collection at /Plone/news/aggregator>
   (Pdb) context_state = obj.restrictedTraverse('@@plone_context_state')
   (Pdb) template_id = context_state.view_template_id()
   (Pdb) template_id
   'summary_view'
   (Pdb) view = obj.restrictedTraverse('summary_view')
   (Pdb) view
   <Products.Five.metaclass.SimpleViewClass from /Users/philip/.cache/buildout/eggs/plone.app.contenttypes-1.1b2-py2.7.egg/plone/app/contenttypes/browser/templates/summary_view.pt object at 0x10b00cd90>
   view.index.filename
   u'/Users/philip/workspace/training_without_vagrant/src/ploneconf.site/ploneconf/site/browser/template_overrides/plone.app.contenttypes.browser.templates.summary_view.pt'
   

   Now we see that we already customized the template.

   Here is a method that could be used in a view or viewlet to display that path:

   def get_template_path(self):
       context_state = api.content.get_view(
           'plone_context_state', self.context, self.request)
       view_template_id = context_state.view_template_id()
       view = self.context.restrictedTraverse(view_template_id)
       return view.index.filename
   

skin templates¶

Why don’t we always only use templates? Because we might want to do something more complicated than get an attribute from the context and render its value in some html tag.

There is a deprecated technology called ‘skin templates’ that allows you to simply add some page template (e.g. ‘old_style_template.pt’) to a certain folder in the ZMI or your egg and you can access it in the browser by opening a url like http://localhost:8080/Plone/old_style_template and it will be rendered. But we don’t use it and you too should not, even though these skin templates are still all over Plone.

Since we use plone.app.contenttypes we do not encounter many skin templates when dealing with content any more. But more often than not you’ll have to customize an old site that still uses skin templates.

Skin templates and Python scripts in portal_skins are deprecated because:

• they use restricted Python
• they have no nice way to attach Python code to them
• they are always callable for everything (they can’t easily be bound to an interface)

Summary¶

• Overriding templates with z3c.jbot is easy.
• Understanding templates can be hard.
• Use plone.app.debugtoolbar and pdb; they are there to help you.
• Skin templates are deprecated; you will probably only encounter them when you work on Plone 4.

View Classes¶

Earlier we wrote a demo view which we also used to experiment with page templates. Now we are going to enhance that view so that it will have some python code, in addition to a template. Let us have a look at the zcml and the code.

browser/configure.zcml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<configure xmlns="http://namespaces.zope.org/zope"
    xmlns:browser="http://namespaces.zope.org/browser"
    i18n_domain="ploneconf.site">

    <browser:page
       name="demoview"
       for="*"
       class=".views.DemoView"
       template="templates/training.pt"
       permission="zope2.View"
       />

</configure>

We are adding a file called views.py in the browser folder.

browser/views.py

1
2
3
4
5
6
7
8

from Products.Five.browser import BrowserView

class DemoView(BrowserView):
    """ This does nothing so far
    """

    def the_title(self):
        return u'A list of great trainings:'

In the template training.pt we can now use this view as view and access all its methods and properties:

<h2 tal:content="python: view.the_title()" />