Introduction to Plone 3 Viewlets - Part 2 of 2

So far, we've registered the plone personal bar viewlet for the footer, put it in the place we want relative to other viewlets, and hidden it in the portal top Now, let's say we want to add another viewlet to the footer How do we do that? As before, first, we need to register our new viewlet using configure.zcml in our product's browser folder As before, in the registration, we need to give our viewlet a name Because it's our own custom viewlet we can call it what we like So I'm going to give it the name of my theme and then the word "custom" We need to specify the manager for the viewlet Again, I'm going to use the footer. I specify its interface here I only want this viewlet to be visible when my theme is installed So I make sure to include a layer calling an interface specific to my theme product I set the same permission as plone has on its personal bar viewlet This is a new thing I specify a template which is where the viewlet code will live So let's go and make that file Here I have some text that I want my custom viewlet to contain As before, if we want out new viewlet to appear in a specific order relative to other viewlets, we need to change viewlets.xml Here, we are going to insert our custom viewlet after plone.footer in the portal footer viewlet manager Because we changed configure.zcml, we have to stop and start zope Because we changed viewlets.xml, we have to uninstall and install our theme Now when we refresh our site We can see that our viewlet is incorporated Note that our instructions about where to insert this viewlet relative to other viewlets seem to have been ignored I find that this happens fairly commonly and the only really reliable way to put viewlets in the order you want, if you are inserting more than one or two viewlets, is to specify the viewlets in exactly the order that you want Here we have plone personal bar, plone footer, our custom viewlet and the colophon We also remove all the instructions about inserting before and after Save, then uninstall and reinstall our product Refresh our page, and viewlets are in the order we want In case you were wondering why the custom viewlet appears red it's because I added some CSS to make this viewlet stand out for now Thus far, our custom viewlet has been very simple We simply wanted some static text in our template So in our configure.zcml file We could point the viewlet registration directly at the template But if you want to do something slightly more complicated with your template you can't point the viewlet registration at the template directly Instead, you need to point the viewlet registration at a python class which in turn points at a custom template I'm going to do that now For the registration for my custom viewlet Rather than pointing it directly at a template I point it at a class So I change my configure.zcml to point at a python class instad of a template I will put that python class in the viewlets.py file in my product's browser folder I could put it anywhere in my product but I use viewlets.py because paster gives me this file and because the name is comprehensible it suggests it contains python code relating to viewlets Why do we need to point viewlet registration at a python class? It's because we want the viewlet to display something that unless we use the python class to define it the template would have no idea what it was For example, imagine that we want our viewlet to show today's date and time This is a very simple example that illustrates the general principle Our python class must compute the things we want to display in the template Then we amend the template to call these things in Here, I will add some code to this template that calls in the value we computed using the python class Because we changed the python class, we need to stop and start zope When we refresh, we see that our custom code has indeed been incorporated in our custom viewlet In the last part of this screencast, I want to discuss uninstall profiles Let's uninstall the theme product in which I've made viewlet changes Go back to the site and refresh and... oh dear The product is uninstalled, and some elements of the theme are gone for example, the colors have reverted to Plone's defaults the changes I made to viewlets have not disappeared The personal bar viewlet is still absent from the portal top it's in the footer, and we can still see our own custom viewlet What's more, if you go to portal_skins in the ZMI, and click on the properties tab, you'll see that some elements of our skin remain, even though we apparently uninstalled it To clean up our viewlets and portal skins properly we need explictly to write an uninstall profile We do that by going to the same place that the install profile is specified In my theme product, this is in profiles.zcml In yours, it might be in profiles.zcml, or in an overall configure.zcml Profiles.zcml already contains a registration for the profile to be run on install We need to add one for what happens on uninstall The format is very much the same We point the new profile at a new folder we're about to create in our product Into this folder, we add 2 files The viewlets.xml file will hold the uninstall configuration for the viewlet changes we effected through our installation The second file we add in here is a skins.xml file And in that, we set skins back to how we found it In this case, back to Plone Default So we've told generic setup that this profile exists and pointed it at a set of files in a particular folder The next thing is to tell Plone when to run this uninstall profile Depending on which version of Plone you're using, that may be all you need to do But if you're using a version of Plone where this isn't enough (you'll know because nothing new will happen when you uninstall your product) you'll need to do an extra step Create another folder called Extensions, with a capital E at the same level in your product as the browser and skins folder And in that, add a python script, Install.py Into this file, add some code that tells Plone when to run each profile We've added some files, changed a python script and some zcml so before we can see our changes we need to stop and restart zope We then install our theme and uninstall it Now when we look at our site with the theme uninstalled, we should see our site set back to how it was before we first installed our theme To sum up, we've created a theme product which when installed removes a viewlet from where plone put it and instead puts it in a different viewlet manager and inserts a custom viewlet of our own When uninstalled, this product puts the site back to Plone's default theme That's it for now, folks.