Theming Plone Product

From ThemesWiki

Source Book ISBN 978-1-847193-87-2 Publisher Packt Publishing Author(s) Veda Williams

[edit] Generating your theme product using paster

Now that we have a working buildout and working instance of Plone, we will generate our skeleton theme product using paster. As mentioned in the previous tutorial, installing Plone gives us paster by default. If you don't get paster by default, follow the instructions in the previous tutorial to install easy_install and ZopeSkel on your system.

Newer installers will be getting paster under the control of buildout so that paster is always available at bin/paster (from your instance directory). ZopeSkel will also be under the control of buildout so that it is updated when buildout is run in "newest" mode. This means you'll always be able to get the most recent updates to paster and ZopeSkel.

[edit] Available templates

A number of paster templates (not the same as page templates) are available to Plone developers for developing different types of Plone products, including themes. To see the available templates, you can run:

$ paster create --list-templates

This command will give you an output like the following:

Your output may show different templates than you see here, as new recipes are created all the time. (The plone3_theme_ootb is a recipe I use internally, as it tweaks folder names and some of the boilerplate to suit my personal preferences.) Most themers will want to use the plone3_theme recipe, which is the official Plone theming recipe.

[edit] Generating your product

Navigate to your Plone product via your terminal tool, and drill down to the directory called src/. Then, type this text into your terminal window:

$ paster create -t plone3_theme

The paster recipe will then ask you a series of questions. You usually want to accept the defaults here (just hit the Enter key), but not always. We'll see the reason in a moment.

 [bash: /opt] paster create -t plone3_theme
 Selected and implied templates:
  ZopeSkel#basic_namespace A project with a namespace package
  ZopeSkel#plone A Plone project
  ZopeSkel#plone3_theme A Theme for Plone 3
 Enter project name: My Theme
 Variables:
  egg: My_Theme
  package: mytheme
  project: My Theme
 Enter namespace_package (Namespace package (like plonetheme)) ['plonetheme']:
 Enter package (The package contained namespace package (like example)) ['example']: mytheme
 Enter skinname (The skin selection to be added to 'portal_skins' (like 'My Theme')) ['']:
 Enter skinbase (Name of the skin selection from which the new one will be copied) ['Plone Default']:
 Enter empty_styles (Override default public stylesheets with empty ones?) [True]: False
 Enter include_doc (Include in-line documentation in generated code?) [False]:
 Enter zope2product (Are you creating a Zope 2 Product?) [True]:
 Enter version (Version) ['0.1']:
 Enter description (One-line description of the package) ['An installable theme for Plone 3']:
 Enter long_description (Multi-line description (in reST)) ['']:
 Enter author (Author name) ['Plone Collective']: Veda Williams
 Enter author_email (Author email) ['product-developers @lists.plone.org']: veda@onenw.org
 Enter keywords (Space-separated keywords/tags) ['web zope plone theme']:
 Enter url (URL of homepage) ['http://svn.plone.org/svn/collective/']:
 Enter license_name (License name) ['GPL']:

Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:

A few key points on these questions:

The text in the square brackets is the default answer, and pressing Enter allows that default to be accepted.

• r, you can type the preferred answer if it is different from the default.
• project name corresponds with the name of your theme. This might be your client's name or the name of the web site for which you are building a theme.
• namespace package is usually plonetheme, but you could name it after your company, if you wish to brand your theme.
• package name is usually a short name for your theme, and one word is generally advisable here, as packages with spaces in their names do not get correctly picked up by buildout.
• skinname is frequently several words, with case sensitivity. This is the name of the theme that you will see when installing it, so make it meaningful.
• For version, zope2product, and zip_safe, you should accept the defaults.
• One question that requires consideration is empty styles, which determines whether you wish to override default public styles with blank stylesheets.

While this is a quick way of suppressing stylesheets, it can feel a little less elegant, a little unusual too. However, it's worth noting that this is the cleanest way of suppressing stylesheets. If you attempt to suppress stylesheets by altering the boilerplate code using GenericSetup, it suppresses them across your entire Plone site, not just within your own theme product. This means that you can't easily layer themes on top of each other if one theme product out of them uses the stylesheets mentioned above and one does not. Again, don't worry too much about this. For new users to Plone and CSS, you likely want to say False. Or, if you always prefer to build on top of the stylesheets that Plone provides you, rather than starting from scratch, you might want to say False. This is purely a personal preference, though it's worth stating that the Plone's stylesheets are quite robust.

• include_doc determines whether certain documentation will be included with your product. This can be helpful, especially when you're first getting used to the theming process.
• t's important to type True or False with case sensitivity, otherwise the default option will be selected.

If you've followed the above instructions, you should now have a vanilla theme product in your src/ directory that can be installed and customized.

[edit] Filestructure of a plone3_theme product

Next is a screenshot of a typical Plone 3 theme, outputted using the plone3_theme recipe. We'll examine first the filestructure, then look at a few of the relevant files that define the filestructure.

Generally speaking, you only need to worry about what is in the folder here called mynewtheme. The code above is just a standard boilerplate.

There are two folders that have similar purposes here: browser/ and skins/. The distinction between these two folders is that Zope 3 items go in the browser/ directory, whereas old-school and non-Zope 3 templates go in the skins/ directory. For a novice themer, that may just sound like a lot of jargon, but to clarify, the browser/ folder will hold all templates and viewlets that are derived from the plone.app.layout and plone.app.portlets eggs, as well as any other packages you may wish to override. We'll talk about this more soon. Items that are derived from the CMFPlone product will go in the skins/ folder.

Optionally, if there's a reason to expose images or stylesheets to other products, you might want to put those items in the browser/ folder. An example might be this: you have a shopping cart installed, and users want to be able to modify the buttons or styles to match those buttons and styles to an underlying product's look and feel each time. However, this is a fairly rare use case. Your images and stylesheets will normally live in the skins/ directory unless you have a clear reason why they should not.

The skins/ directory will hold not only images and stylesheets, but also Python, JavaScripts, and any portlet code that doesn't rely on the component architecture.

In the event that you need to modify main_template.pt from CMFPlone (occasionally needed these days), you would place your modified main_template in the skins/ directory too. Any templates that come from CMFPlone will also go in this directory.

Another directory that is useful here is the profiles/ directory. This directory will hold GenericSetup files (XML files that describe the underlying behavior of a skin product, or site configuration). In other words, this directory holds files that allow you to register stylesheets, JavaScripts, add/remove tabs, menu items, and more. It can also hold files that aid in uninstalling a product by describing what the end result should look like. We'll cover GenericSetup in detail later.

It's important to realize that the structure of your theme product isn't set in stone, and that's ultimately where the power of Plone becomes evident. When you get used to modifying ZCML and XML (we'll see more of this later), you'll have the ability to alter names of folders, remove code from the browser/ directory, rename your theme, and more.

Do not be afraid to make changes, but always start your Zope in the foreground when you are making changes to your theme product, to spot any problems in your boilerplate code. In the case of changes to XML files, you'll also have to remember to import those files, which we will cover in a bit.

Let's look now at how to add our theme product to our buildout, so that we can install it.

[edit] Adding your theme product to your buildout

Our theme is a Python package by default, which means that it is ready to be "eggified" for easy distribution, but it's not an actual egg yet. An egg is a sort of hard-boiled Python package. Eggs don't include setup.py or various other parts of the package. Our theme product, however, does contain these parts.

Since we are still in development, we want to put our new skeleton theme product into the src/ directory, which is where we originally generated it. Open your buildout.cfg file located in the root of your buildout.

Open your buildout.cfg file, and make the following modifications in the develop and eggs and zcml parameters of the [buildout] and [instance] sections respectively, based on how you answered the questions when you ran the paster recipe:

 [buildout]
 develop =
  ... [other eggs here] ...
  src/plonetheme.mytheme
  # this tells buildout that it's a development egg, and that
  # it should find it in the src directory rather than fetching
  # from a repository.
 ... [other code here] ...
 
 [instance]
 eggs =
  ... [other eggs here] ...
  plonetheme.mytheme
  # this tells buildout that you'll be using your theme
  # with Plone.
 zcml =
  ... [other zcml slugs here] ...
  plonetheme.mytheme
  # this tells zope that your product exists

These sections may not follow exactly each other in the buildout.cfg file, so be careful to add your code in the right place.

Since we have made changes to your buildout, you now need to rebuild your buildout with the following command for these changes to be read by Zope. You should be in your buildout's directory when you run this command. It might be named zinstance or similar, depending on how your buildout is set up. Just make sure you re above the bin/ directory.:

./bin/buildout
You may use the following command to run buildout offline, if you don't need any new, external components it's a good bit faster:
./bin/buildout -o

[edit] Starting Zope and installing your product on a Plone site

After running your buildout, start your Zope in the foreground (extremely helpful during development, as it displays errors in your terminal window). All the installer buildouts will start with bin/plonectl start. It (bin/plonectl fg) will run a standalone install in foreground, which is useful for debugging.

Type:

./bin/plonectl fg

You'll know your Zope is working when you see the phrase, "INFO Zope Ready to handle requests".

Once Zope is up and running, you can connect to its management interface from any web browser. We'll assume in this tutorial that Zope is running on port 8080, which is the default. In your browser, go to http://localhost:8080/manage_main and log in using admin/admin as your username and password. Optionally, at this point, you can create a new user in the acl_users area of the ZMI (Zope Management Interface), create a secure password for that username, and assign manager permissions.

[edit] Creating a Plone site

As of Version 3.2, all the installers will create a Plone site by default. If one is not created, or you wish to create a different one, from the ZMI choose Plone Site from the Add pop-up list. You should not need to select a profile at this time, although you could do so if you know that you will be building on top of a policy product that will control generic debt help settings that you want to repeat from project to project.

Once you add a site, you will be able to navigate to your new site by selecting the new site and clicking on the View tab. You should see the following result (notice that default Plone styles are applied wedding bands):

[http://www.plope.com/Members/chrism/whatsnew_27 
http://www.plope.com/Members/chrism/whatsnew_27].

[edit] Installing your Plone theme

To install your theme on a Plone site, go to Site Setup | Add-on Products and select your theme product, or go to your site in the ZMI, and navigate to portal_quickinstaller via http://localhost:8080/newsite/portal_quickinstaller/manage_installProductsForm.

Choose your product from the list of installable products. If you do not see your theme present, you have not correctly registered it in your buildout.cfg file.

Click on the checkbox next to your theme product and choose Install.

Note that the ZMI quick installer is functionally the same as the Add-on Products option in the Plone Site Setup panel. The ZMI interface just gives you some additional options. Choosing an extension profile when creating custom research papers a new Plone site is also functionally the same.

[edit] Putting your site into debug mode

Before going any further, we will put our site's stylesheets into debug mode. This allows us to see the changes that you will apply to stylesheets immediately after reloading a page, without having to restart the Zope server.

In order to set portal_css in debug mode, go to the portal_css tool in the ZMI by pointing your browser to an address that should look like http://localhost:8080/mysite/portal/css/manage_cssForm.

Then check the Debug | development mode and click the Save button. You can also access this by drilling down into portal_css through the ZMI.

sudoku play suduko online You can optionally put your entire Zope in debug mode. This must be configured programmatically in a file usually located in the etc/ folder of the Zope instance on the file system. If you are using buildout, debug mode can be set from the instance part of a buildout configuration file. (Zope debug mode is automatic professional resume services when you're running in foreground mode.) It is also probable that you will need to put your entire Zope instance into debug mode just to theme a web site, and you may occasionally also need to put your portal_javascripts and portal_kss into debug mode.

In the future, debug modes may be consolidated and possibly enabled by default, so stay tuned.

[edit] Summary

In this tutorial, we have learned:

• How to create a theme product
• What a theme product's filestructure looks like
• How to add a theme product to a buildout
• How to start Zope, create a Plone site, and install your theme product
• How to enable debug mode to ease theme development

[edit] Additional References

• For instructions on Installing Plone, click here
• For instructions on Installing Plone 3, click here
• For instructions on customizing themes for Plone, click here
• For instructions on Customizing Plone 3, click here

[edit] Source

The source of this content is Chapter 4: Theming Plone Product of Plone 3 Theming by Veda Williams(Packt Publishing, 2009).logo design by Kevin Josh 2010

Logo Designby ThemesWiki.org Kevin Josh 2010

Executive Editor Sean Lopez own  : SEO Company and provider of Link Building Services and SEO Services

And Like Costumes and Halloween Costumes and criar sites

And Like The Global Information Network and Global Information Network