Changing the Title, Description, and E-Mail Addresses

The title, description, and e-mail addresses are stored in a Plone site as properties on an object inside Plone. You can access these fields by clicking the Portal Settings link in the Plone control panel (see Figure 4-3).

Figure 4-3. Portal options

The portal settings are as follows:

• Portal title: This is the title of the site that will appear in the title for browsers, breadcrumbs, navigation, e-mails, and so on. The default is Portal.
• Portal description: This is the description for the portal, which is currently used only in syndication.
• Portal From' name: This field is related to various functions, such as a lost password or the 'send-to-a-friend” function. Plone sends the e-mail messages with this name attached. The default is Portal Administrator.
• Portal From' address: This is the address used for the e-mails that Plone sends. The default is postmaster@localhost.
• Default Language: This is the default language that's given in the properties of an object.
• Password policy: New users have two options; they can either enter a password or enter a password that's then e-mailed to them. Although in both cases they have to enter an e-mail address, the latter choice ensures that the e-mail address they enter is valid.
• Enable External Editor Feature: This will turn on External Editor, which is an advanced editing tool. It requires that External Editor be installed on the user's computer. Chapter 10 covers this in more detail.

After selecting the options you want, click Save to commit the changes. All the changes on this form will occur immediately.

Setting Up a Mail Server

Plone will send e-mail using the MailHost object, which provides an interface to an SMTP server and allows the developer to write forms and tools that send e-mails. The 'send-to-a-friend” function and the mailing of a forgotten password use the settings configured here.

The default configuration is for a mail server on the localhost at port 25. If the SMTP server is located elsewhere in the network, then you can access the form by clicking plone setup and then clicking Mail Settings. Then change the mail server and the port to suit your configuration. On my network, the mail server is at monty.clearwind.ca on port 1025, so I set the server as shown in Figure 4-4; however, in most cases, you won't need to change this.

Figure 4-4. Setting up the mail server

NOTE The MailHost object is a Zope object accessible in the ZMI. This object doesn't currently allow for authentication with the server. If this is needed, change the settings on the server.

Logging Errors

The error log catches errors that may occur in a Plone site; these are features such as Page Not Found (404) errors, unauthorized errors, and so on. This isn't designed to trap errors from forms. For instance, if somebody doesn't enter a required field in a form, then this won't be reported; this isn't an error since it's captured by the validation framework. This error log is designed to catch internal server errors that may occur.

From the Plone interface, click plone setup and then click Error Log to see the errors reported by the Plone site. Click the exception in the list (if there's one reported) to see the error. Figure 4-5 shows an error that occurred when incorrectly filling out the mail settings form. It's a long page that includes a complete Python traceback and the incoming request.

Figure 4-5. An example error

On the error log form you'll see the following settings:

• Number of exceptions to keep: These are the exceptions to keep in the active log on the screen. The default is 20.
• Copy exceptions to the event log: This copies each exception to the file-based log file. Not doing this means that no permanent record will be kept for exceptions. The default is that this is selected.
• Ignored exception types: This is a list (one per line) of exception types to ignore. The default is Unauthorized, NotFound, and Redirect.

You can log each exception and view it on the screen. This means if a user is visiting your site and an error occurs, then you can go to the error log and see what occurred. The three components of an error are the error type (which is the type of the error), the error value (which is a string explaining when an error occurs), and the traceback. These first two items are shown to a user on a standard error page (see Figure 4-6).

Figure 4-6. An example error message

So, when a user reports an error, the report will often include a message with the error name and a value in it. If user isn't allowed to do something and an Unauthorized error is raised or a Page Not Found (404) is triggered, then you'll get a custom error page rather than the standard page shown in Figure 4-6. The following standard error types occur:

• Unauthorized: This occurs when a user doesn't have the right to perform a function.
• NotFound: This occurs when the item a user is trying to access doesn't exist.
• Redirect: This is an error that can raise a Hypertext Transfer Protocol (HTTP) redirect.
• AttributeError: When an object doesn't have this attribute, this error is raised.
• ValueError: This occurs when a value given is incorrect and isn't caught correctly by the validation or other framework.

Understanding Portlets

On a Plone site, you'll see three columns to a page by default: the left, middle, and right columns. The middle column contains the content for the object being currently viewed. This is where most of the user functionality is for adding and editing content, completing forms, and so on. The left and right columns contain a series of boxes that display information. Each of these boxes is called a portlet. A variable determines which portlets display at a particular point in time. The best way to understand these portlets is to look at the default portlets that ship with a Plone site. You can find the parameters for the portlets in the portal object. To access this, go to the ZMI, ensure you're on the root Plone site, and click the properties tab. This opens a list of properties, including left_slots, right_slots, and document_action_slots (see Figure 4-7).

NOTE In earlier versions of Plone, the portlets were called slots. This is a common term that conflicts with the page template term slot, so it was changed to portlets for version 2. In certain places in the code and in the text, you may see the term slot used. In these contexts, the words slot and portlet are synonymous.

Figure 4-7. The default portlet properties

The left_slots properties refer to portlets shown on the left of the page, and the right_slots properties list the portlets shown on the right of the page. The portlets are shown in the order, from top to bottom, that they're listed in the properties; notice that each portlet is on a new line. However, most portlets have some code to ensure that the portlet displays only if it makes sense. For example, a login portlet is pointless to show if the user is already logged in. In this case, the login portlet is included in the list of portlet but will show up only when needed.

Each portlet value is actually a special value called a Template Attribute Languages Expression Syntax (TALES) path expression (Chapter 5 covers this in detail). Site developers can add their own portlets to a site by creating simple macros and page templates. The default portlets are as follows:

left_slots: This includes the navigation, login, and related portlets.

right_slots: This includes the review, news, events, recently published, and calendar portlets. All the available portlets aren't configured in Plone by default. The following sections describe portlet slot in Plone. Each section describes the portlet and shows what it looks like. Then I give the path expression that you need to add to the slots property so it'll show up in your Plone site.

For example, to show the calendar portlet on left side, enter here/portlet_calendar/macros/portlet in the left_slots property, and click Save Changes. If you want to remove it from the right_slots property, then you could remove the same line from the right_slots property and click Save Changes.

Altering the Navigation Portlet

Of all the portlets covered, probably the most useful and the most asked about is the navigation portlet. Specifically, how can you alter the navigation portlet and the way that it's displayed? The navigation portlet is list of current folders and documents in the navigation slot. You can alter the navigation slot by changing the code; however, you can make many changes through the ZMI. The biggest thing to remember is that only published objects will be shown in the navigation tree to members and anonymous users. To alter the navigation tree properties, click portal_properties and then click navtree_properties in the ZMI.

The following is an abridged list of the options available:

• showMyUserFolderOnly: This displays only the user folder of the user logged in. So when the Members folder is being shown in the navigation, it won't show every Members folder. This is selected by default.
• showFolderishSiblingsOnly: Only folders in parent folders will display if this is selected; otherwise, it will show all content. This is selected by default.
• showFolderishChildrenOnly: When this is enabled on a folder, it shows only folders in the same folder rather than all the other types of content. Selecting this option effectively shows you all the contents of the folder currently viewed. This is selected by default.
• roleSeeUnpublishedContent: As mentioned, content is shown only if published to members and anonymous users. Add more roles to this list, with each role on a new line, to have nonpublished content display. This is undesirable if the user doesn't actually have access anyway.
• croppingLength: This determines how many characters of the names to show in the navigation tree. The default is 256.
• idsnotToList: This is the item IDs not to show. Place each ID on a separate line. The default is None.

Make any changes to that form, and then click Save Changes. The order of the items in the navigation tree is determined by the order of the items in the folder contents form. As shown in Chapter 3, using the up and down arrows, users can change this order to suit their own needs.

Book Web Site: Altering the Navigation Tree

For most Web sites I prefer a fuller navigation tree than the one provided by default. So, I went to the navigation tree options and deselected showFolderishChildrenOnly and showFolderishSiblingsOnly. This made the contents show up nicely; for example, here's the software folder with just a few items selected:

Altering the Date Formats

Throughout the portlets and the whole site, Plone presents dates in a consistent format that are editable using formats set internally. Whenever a date is shown in Plone, it calls one of two formats. You can find these formats by accessing the ZMI, clicking portal_properties, and clicking site_properties. These are the formats:

• localTimeFormat: This is the time format to use for dates that should appear in a short format in Plone.
• localLongTimeFormat: This is the time format to use for dates that should appear in a long format in Plone, showing seconds.

The format for the date is based on Python's time format module. The reference for the formats are at http://www.python.org/doc/current/lib/module-time.html. For the short date, the default value is %Y-%m-%d, which means year-month-day as decimal numbers (for example, 2003-10-26). For long date, the default value is %Y-%m-%d %I:%M %p, which means year-month-day hours:minutes am/pm (for example, 2003-10-26 07:32 PM).

The following is a quick summary of the options available:

• %a: Locale's abbreviated weekday name (for example, Mon)
• %A: Locale's full weekday name (for example, Monday)
• %b: Locale's abbreviated month name (for example, Jan)
• %B: Locale's full month name (for example, January)
• %d: Day of the month as a decimal number
• %H: Hour (24-hour clock) as a decimal number
• %I: Hour (12-hour clock) as a decimal number
• %m: Month as a decimal number
• %M: Minute as a decimal number
• %S: Second as a decimal number
• %y: Year without century as a decimal number
• %Y: Year with century as a decimal number

If you want to include the day name in the short date, it's a simple matter of changing the short date format to read %A, %b. %d, %y. This produces Thursday, Oct. 24, 02. These dates are used in the boxes on the left and right of the screen, in the search results, in the content byline, and so on.

Adding Keywords and Event Types

One of the tools in Plone, portal_metadata, allows the site administrator to define some of the metadata elements. Plone uses the metadata defined in the portal_metadata tool in several places.

For example, when you add an event, you're given a list of possible types of events. You can add to this list by clicking portal_metadata, clicking elements, and then clicking subject in the ZMI. You'll see a vocabulary for events that lists the subjects for that content type. It's a simple matter of adding or editing that list, one item per line, to have the relevant event types. These event types will then appear in the forms for adding and editing events.

Another use of portal_metadata is the selection of keywords available on a site. On the form at portal_metadata/elements/subject, you'll also see a vocabulary form for a content type of <default>. If you add items to the Vocabulary field of that page and click Update, you'll add these to the list of available keywords for every content type.

If you want keywords to appear for, say, only documents, then use the add form at the bottom of the page. Select a content type, and add some vocabulary, one value for each line. These will then become keywords that users can select for that piece of content only.

If you're logged in as a user with the manager or reviewer role, clicking the properties tab of an object in the Plone interface will display a New Keywords box for the addition of ad-hoc keywords. These keywords won't appear in the portal_metadata vocabulary but will appear on all types of content for other users to enter.

Changing the Default Page

As discussed in Chapter 3, when a user is viewing a folder, the default page for that folder is shown if present. In the old versions of Zope and Plone, the name for that default page was index_html. You'll see these a lot in Plone sites, where Web site addresses often have index_html on the end. If you made this filename an extension that's more commonly recognized as index.html, then it'd be easier to edit using editing programs and Web site tools.

In Plone you can define a list of pages that will be looked up to be rendered as the default page (see Figure 4-18). The default pages are index_html, index.html, index.htm, and FrontPage. You set the list of pages in portal_properties/site_properties/default_page property, one name per line. When the default page is looked for, Plone will look for each page in that list, starting with the first until it finds one that matches. Further, if you'd like to change the value for a folder only, you can access the folder through the ZMI, click the properties tab, and then add a new list property called default_page.

Figure 4-18. Making index.asp the first default page

How Can You Make the News Items List the Default Page?

Exactly how this works involves knowing the underlying machinery a little too much. For now, go to your portal root and click Properties. Then you need to go to the bottom of the page, complete the add new property form with the following information, and then click the Add button:

For the Name field: default_page For the Value field: news For the Type field: lines

Now return to your Plone site. Instead of the standard home page, you'll see the news page. The news tab will still show you the news, as well, but in the following sections I'll show how to remove that.

Altering the Site Tabs

In a Plone site various tabs refer to different sections or parts of a site. Using tabs is a familiar concept in Web site design and is common in sites such as Amazon, MSN, and Plone sites.

Two main types of tabs exist: portal tabs and content tabs. The portal tabs are blue and appear at the top of the Plone site. The default ones are home, news, and members. The following sections show how to customize these. The content tabs are green and appear when an item can be edited. The content tabs, as the name suggests, are related to content. Chapter 11 covers how to alter these tabs. The tabs you see in a Plone site are formed by a collection of actions, so to understand how to modify these tabs, you'll take a quick look at actions in general.

Changing Images and CSS

The look and feel of a Plone site is a big subject that takes three chapters of its own, Chapters 5-7. The following sections cover the basics and, rather than trying to explain everything, just show how to quickly make a few changes.

A skin is a series of CSS, images, templates, and scripts that come together to form a look and feel for the user. The idea of a skin is that you can change the skin and hence change the look and feel of a site without having to change the content.

/* DELETE THIS LINE AND PUT YOUR CUSTOM STUFF HERE */

body {
   background-image: url(background.jpg);
   background-repeat: no-repeat;
   background-position: center;
}