Creating a custom template for a Plone content type
So in the last example, Creating a Content Type for Plone 3.x, I provided steps for creating a content-type in Plone. The feedback has generally been positive and those steps can also be found on Plone.org (I try my best to keep both sync'd). What's the next step though? You've got your content-type and you've entered most of your data but now you want to display it in your own template. The number one thing I have heard from people is that they can't make Plone look like anything except Plone without extreme duress. Unfortunately, this is simply not true.
So, for example how do we get Plone from looking like this:
A Stock Plone install using Sunburst theme
To looking like this:
I stole this theme from oswd.org the author is Christopher Robinson
The answer is a concept known as Browser views. Now, there are two trains of thought here. One is that you want all of the default Plone interface to look a specific way. 9 times out of 10 that isn't the case. You probably don't want to theme your content management system the same way you don't go around changing the theme to wordpress/movabletype/drupal in edit mode. Some people do have a need for this but you probably aren't one of them. The other train of thought is that you'd like for the content that you enter to be displayed in a certain visual context depending on where it is displayed. Lets be realistic, you will probably be displaying this primarily on a web browser but you may decide you need several different renditions depending on context and platform. So you may need a mobile version of the same content etc. Let us hop on this train of thought for a minute.
The first thing you'll want to do is change into the browser directory, so for example that would be something resembling:
We are going to create the file web.py because this view is for the web primarily. If we wanted to lets say create a mobile view or page we could make mobile.py or whatever we want to create a view for. In our case though we are just making an html page right now.
In it we are going to put the following:
The HTML Browser View SubClass
This creates a class with methods that we can later access directly from our template should we wish to provide some custom functionality. It isn't explicitly required but unless your content-type is extremely simple or you can use default Plone methods for content-objects. You will most likely need it at some point. In the above example we simply return the string "Some people are still dreaming." when we call the still_dreaming method from the class Html which subclasses BrowserView.
That created and saved. Let us now create our template. In this case I stole the following theme located on oswd at http://www.oswd.org/design/preview/id/3537. I unzip this into my directory and simply rename index.html to web.pt (where .pt stands for page template).
Here, a discussion on Zope Page Templates is required but I plan to save that for a larger document at some point and will replace this paragraph with that. In the meantime please visit this link.
So we want to take information from our content-type and display it on this template. Here is how we go about it:
Lets start with line number 7. It pulls in a stylesheet named dvd.css which houses all of the style for our html page including images that are related to the overall design. There are a couple of different ways to get Plone to recognize and use these type of files but we are going to go with the easiest way for now.
In your Plone site proceed to the ZMI (Zope Management Interface). In our example case it's going to be http://localhost:8080/cwarner/portal_skins/custom/manage and look like the following:
Plone Skins Custom Tool - Zope Mangement Interface
This is Plone's Skin Tool which will allow us to put our own Custom files/images etc. The only thing one should be cognizant of is that these files are available from anywhere in a Plone context. (There is another, more clinical way to do this via the filesystem that I will describe but in order to keep with the concept of Browser views alone I will disregard it for now and add it as a note later). Once here we select the type to add in this case I had the 3 images to add so I added them as images and two css files which I added as the file type: File.
At line 29 and 30 we have the title of our DVD Content type and the description. You'll see that I refer to these via context/title and context/description. The context paradigm is as you would expect. It will display the title of whatever specific context we happen to be in. In this case we are actually working with a dvd content type with the title 'The Pursuit of Happiness". So context/title displays whatever the title of the dvd is named. The same follows for lines 35-39 where we display the Publisher, Length, ISBN, Rating, and Color. Notice that the attributes are named exactly what we called them when we created our content type.
Now, lets take a look at line 42 which has the following "view/still_dreaming" as it's content descriptor. When displayed in the final template we see that it indeed does work and returns the line "Some people are still dreaming" under the Comments section.
Next up! Let us plug this all together with some ZCML (Zope Component Markup Language) and try it out. Open the configure.zcml file located in your browser directory. We are going to add a section for our new template page and view and it should resemble something like the following:
configure.zcml setup for browserview
Lets discuss some of these properties
- Line 8, describes that our browser view is in-fact a page
- Line 9, describe that our our view is applied to a specific interface, in this example we use the greedy operator so this will work with any interface.
- Line 10, is the actual name of our view. In this case I picked a name that describes what our view type is but this can be anything
- Line 11, describes where the view class is located. In our case it's in the web.py and in the class Html; hence .web.Html
- Line 12, describes where the actual template is. Again, in our case it's web.pt where .pt stands for page template
- Line 13, describes who has permission to see our view. In most cases this will be zope2.View
Once this is complete you can save the file and because we've wired everything up from our previous example you should be complete! If plone is started, restart it and you can test it with some dvd content that you've already created. In our case the url we would visit is: http://localhost:8080/cwarner/dvd/the-pursuit-of-happyness/@@html
Notice where we apply the double at (@@) before html. We could also just use the following uri http://localhost:8080/cwarner/dvd/the-pursuit-of-happyness/html. The double @@'s just explicitly tell Plone that we are requesting a view. Now that you are complete we could have Apache, Varnish or even Plone rewrite the url to something a little more pretty if we want. After this run you should be able to use a myriad of different templates and configurations to display your content on whatever device or platform you want!