Customizing Plone 3
From ThemesWiki
| Official Page |
| Project Documentation |
| Download |
|
You can customize Plone by changing the settings in the ZMI (through the web) or by making changes to an installable filesystem product. These customizations can serve as the scaffolding upon which a theme product can be built, if desired, although these changes are not necessarily theme-related.
Contents |
[edit] Background
In order to perform most of the customizations mentioned in this tutorial, you need manager rights to your site, basic programming skills, and a little common sense. For some of the changes, you will need to be comfortable working with Plone filesystem products, although this does not mean that you need to know Python in order to make these changes. A filesystem product is merely a product that can be installed; much of the boilerplate is written for you via automated scripts, known as recipes.
[edit] Make changes to tabs, buttons, and menu options
On your Plone site's home page, you will notice various areas where there are menu options or buttons. A default Plone site has a top navigation area, various links for printing or emailing a page, as well as menu actions that allow you to cut, paste, or otherwise manipulate the objects within a folder. You will also see tabs that allow you to access the contents of a given folder, a history tab, a sharing tab, and various tabs along the top for Home, Users, News, and Events:
Each of these tabs, buttons, and menu objects corresponds to an action defined in http://localhost:8080/yoursitename/portal_actions/manage, in the ZMI. You must log in to your site in order to see the available portal_action categories. The following is a screenshot of the main portal_actions screen:
By default, there are seven CMF action categories that are listed. CMF (Content Management Framework) is an add-on product for Zope that is used to build content management systems. It provides some basic tools for handling metadata, members, and so on, but is not a CMS by itself. Plone is an example of a sophisticated CMS built using the CMF.
CMF Action Categories use this technology, but for practical purposes they are merely categories in which you can alter the buttons, tabs, and menu options for your site. An example scenario where action categories might come in handy is where you want to add a new action category, to drive something like a portlet with drop-down lists. Generally, though, you will only be adding or altering action items within the existing categories. The default categories include:
1. document_actions
2. site_actions
3. folder_buttons
4. object
5. object_buttons
6. portal_tabs
7. user
To add a new action category, choose Add CMF Category from the drop-down list found on the top right area of the ZMI.
To add a new action within one of these categories, click on the category and choose Add CMF Action from the drop-down menu. Often, all you may want to do is deselect the Visible? checkbox to hide the items that you do not wish to see, or change the logic slightly, say to point to a different URL. For example, the following portal_action is not marked as visible, and hence does not display:
|
Note that you should not delete any of the categories, or the actions within them. It is safer to simply not mark the actions as visible." |
[edit] Document actions category
Within the document_actions category, you can alter or add to the buttons and widgets that are available on a given site. These document actions are found in the area outlined in the following screenshot:
The default document actions include:
- rss: Displays an RSS button with a link to the aggregated page; in this case, we see this link because the News section is syndicated.
- sendto: Displays an email button with the logic needed to email a link to the page to a specified email address.
- print: Adds a print button and the logic needed to print the page.
- addtofavorites: Flags an item as a favorite; this option only appears and works if you have user folders enabled on the security control panel; actual support for this feature is unknown.
- full_screen: Expands the window to take up the full screen.
- extedit: Enables external editing, if an editor is specified.
Only the first three of these actions are visible by default; the others are not marked as "not visible" in the ZMI and have additional constraints, as defined in their condition expression. Add to Favorites, for example, requires a Members folder to be installed on the site in order to be functional, and Toggle Full Screen Mode requires the user to be logged in.
[edit] Site actions category
Within the site_actions category, you will find the menu options that correspond to the top navigation on a default Plone installation. By default, these include: Site Map, Accessibility, Contact, and Site Setup, as shown in the following screenshot:
If you want to include an additional menu option here, (for example, a Site Help option that is available only to persons with managerial rights) you can add a new CMF action. You will need to specify the Title, Description, I18n (internationalization) domain if you wish to use Plone's translation services, and the URL to which the link will point, utilizing a TALES expression.
Next, you will need to specify the URL of an icon to correspond to the action if one exists, any specific conditions, using a TALES expression, and then select the permissions required for that action. In this case, that permission would be Manage portal.
Saving the new site action definition shown above will result in the following:
Note the additional menu item on the top. This menu item will only display if the user is logged in, due to the permission specified.
In this fashion, we can add menu options to or remove menu options from this area.
[edit] Folder buttons category
Within the folder_buttons category, you will find a listing of all of the buttons that are available when a user is on the Contents tab of any folder on the site. These include actions that can be taken against a piece of content, such as copy, cut, rename, paste, delete, and change state. You will rarely need to customize these items, but the principle is the same.
As seen in the following screenshot, the difference between folder buttons and site actions is that a method is passed in the URL (expression) field that causes an action to occur, in this case, the copying of an object when the Copy button is clicked:
[edit] Object category
This category contains actions that appear as the tabs above the content area, as seen in the following screenshot:
This area includes the following actions:
- folderContents: Provides the logic for displaying the *Contents tab itself, and not the view that you get when you click on it; for this item and the following items, the actual views can either be skin-layer templates or browser views that are configured elsewhere.
- syndication : Provides the logic for determining if an object can be syndicated.
- content rules: Provides the logic for displaying the view for the Content Rules tab.
- local_roles: Provides the logic for accessing the Sharing tab.
- history: Provides the logic for displaying the viewlet for viewing an object's history.
Not all of these actions appear all of the time, as each of them has a special logic that controls their behavior. The Contents tab, for example, can only be accessed if you are on a "folderish" item, and the Syndication option is generally only turned on for folders such as News and Events, although the option can be adjusted if desired.
This mechanism does not control the View and Edit tabs.
[edit] Object buttons category
Within this category are the actions that can be taken against a piece of content. These include Cut, Copy, Paste, Delete and Rename. These items are seen in the drop-down list when you are working with a piece of content:
Again, you will rarely need to modify these.
[edit] Portal tabs category
This category contains a single action that causes a Home tab to be displayed at the top of a default Plone site:
You might see additional items appearing next to the Home tab, but these items are controlled by the navigation code. If you alter the navigation settings in the plone_control_panel to disable Automatically generate tabs, only those tabs defined in the portal_tabs category will be displayed.
Disabling the automatic generation of tabs will allow you to control your navigation more tightly.
[edit] User category
This category contains all of the actions that are displayed in the portal-personaltools area of your site. This is the bar with the log out link, as seen in the following screenshot:
These items are generally displayed only when the user is logged in to the site. They contain all of the functions specific to the logged-in user, many of which are not enabled by default.
These actions include the following:
- A link to the logged in user's Member folder [http://localhost:8080/yoursitename/dashboard http://localhost:8080/yoursitename/dashboard]
- A preferences link ([http://localhost:8080/yoursitename/plone_memberprefs_panel http://localhost:8080/yoursitename/plone_memberprefs_panel])
- A login link ([http://localhost:8080/yoursitename/login_form http://localhost:8080/yoursitename/login_form]; disappears once the user is logged in)
- A logout link ([http://localhost:8080/yoursitename/logout http://localhost:8080/yoursitename/logout])
- A join link ([http://localhost:8080/yoursitename/join_form http://localhost:8080/yoursitename/join_form])
- An undo link ([http://localhost:8080/yoursitename/undo_form http://localhost:8080/yoursitename/undo_form])
- An Add to Favorites link
- A My Favorites link
Additional items in this area that you could add include the following:
- Link to a Site Help section specific to a client
- Link to Plone documentation
- Link to a Support page
Now that we've looked at how to adjust the buttons, navigation, and other menu items on our site, let's take a look at how we can make larger changes through the customization of templates.
[edit] Customization using templates
Site administrators can customize templates within the ZMI by using either the portal_skins tool (for traditional CMF skin layer resources), or the portal_view_customizations tool (for Zope 3 views, viewlets, and portlets). This tutorial will clarify how you can identify which of these you are working with. Although through-the-web (TTW) customization is acceptable for making quick fixes, it is not ideal for building or deploying a robust, maintainable project.
First, we will explain how to make changes through-the-web, and then explain how these changes can be implemented in a better way in a filesystem-based product.
[edit] Skin layer customization The old fashioned way
Prior to Plone 3.x, most customizations performed in the ZMI relied on the concept of a single, global namespace such that the resources for a given product could not easily be shared between products. This was a fairly limiting idea. Plone before 3.x also used Zope's concept of acquisition. Essentially, this means that when looking for an item, Plone finds the closest object that contains the property. For example, when looking for a logo specific to a given section, Plone first looks in the folder for that section, and if it does not find it, it moves up the folder hierarchy until it finds one.
A Zope object can acquire any object or property from any of its parents. That is, if you have a folder called A containing two resources (a document called homepage and another folder called B), then an URL pointing to http://.../A/B/homepage would work even though B is empty. This is because Zope starts to look for homepage in B, doesn't find it, and goes back up to A, where it's found. The reality, inevitably, is more complex than this. For more information, read the tutorial on acquisition in the Zope tutorial, which can found at [http://www.zope.org http://www.zope.org]
A tool called portal_skins was created to help manage the resources within Plone and to control the order of acquisition. If you enter the portal_skins tool, which is located in the ZMI at [http://localhost:8080/mysite/portal_skins/manage_main http://localhost:8080/mysite/portal_skins/manage_main] (where mysite is the name of your site), and click on the Properties tab, you will see a skin called Plone Default, and next to it a listing of skin layers. A "skin," often referred to as a "theme," is just an ordered list of skin layers. Don't worry too much about the distinction between skins and themes there isn't one.
The following is a screenshot of the portal_skins tool:
The skin layers listed on the Properties tab correspond to folders inside the portal_skins tool. A skin's appearance depends heavily on the order in which these skin layers are listed. Plone uses acquisition to look through this list of skin layers, giving precedence to the skin layers at the top of the list. If Plone requests a resource, such as logo.jpg, it will look for it by starting at the top of the list and going down until it finds this resource in one of the directories. The Find tab in portal_skins provides the ability to search for a resource within a selected skin.
Note that there is a drop-down list below the skin layers, called Default skin. This area allows you to switch to a different theme product. (A skin product must first be installed via the portal_quickinstaller option in the ZMI for it to appear in this list. So it ultimately makes more sense to simply install your skin product in portal_quickinstaller for your site rather than use this drop-down option.)
The custom skin layer should always appear at the top of the list of skin layers, generally followed by skin layers for a theme or product's images, stylesheets, and templates. This configuration might change in the event that you have a product installed with which you want to override the installed products beneath it. In this case, the product with the most precedence should be listed at the top.
|
Skin layers often get out of order when a new product is installed, and this can cause some confusing behavior to occur. It would be helpful to monitor this area during product development, and especially prior to going live with a Plone site. |
In the following screenshot, the selected skin is the Dogwood Theme. This theme looks first at the custom skin layer, then goes down to dogwood_templates, dogwood_styles, dogwood_scripts, dogwood_images, dogwood_content_templates, and so on, down thorugh the list. Items in the custom layer take precedence over all of the other resources in the skin layers below, as long as custom is at the top of the list.
Click on portal_skins again to get to the main page that displays all of the available pages, templates, and other resources. To modify one of these resources, locate an item listed there, for example plone_images/logo.jpg, and click on it. You will then be given the opportunity to customize that item in the custom folder. This is a copy of the original item provided by Zope. Removing that item from the custom folder after customizing it means that the site will use the original, non-customized version.
Note that you cannot customize items within their own folders, as they are not folders in the traditional sense. They are filesystem directory views, or folders that correspond to the files inside a particular folder on the filesystem. However, they are not the filesystem themselves. The custom folder, in contrast, lives in the ZODB (Zope Object Database), and its contents cannot be found in the filesystem.
[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 Theming Plone Product, click here
[edit] Source
The source of this content is Chapter 17:Creating a Custom Theme of Practical Plone 3: A Beginner's Guide to Building Powerful Websites by Jon Stahl, Martin Aspeli, David Convent, Darci Hanning, Ricardo Newbery, John DeStefano, Clayton Parker, Alex Clark, Veda Williams, Tom Conklin, Sam Knox, Steve McMahon, Matt Bowen (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
