Adding a Document

You have two ways to add any piece of content using a Web browser. First, ensure you're logged in, because only logged-in users can add content. Second, select the my folder link from the top-right navigation bar. This will take you to your home folder, an area that you control. If you're able to add content to a folder, then the folder will show up with the green border around the top (see Figure 3-9).

Figure 3-9. My content

If the green border doesn't appear, then you won't be able to add content; this border contains the actions you can perform in the current location. In Figure 3-9, you can see that the page shows the contents of the folder, because that's the highlighted tab. Other tabs appear such as view, sharing, and properties for more advanced options. In the top-right corner of the green border, you'll see an Add New Item drop-down menu and a State drop-down menu. Click the Add New Item menu to open a drop-down list of items to add (see Figure 3-10).

Figure 3-10. Adding a document from the green drop-down menu

To add a new document, select Document. Alternatively, if you look in the body of the page, you can see another Add New Item drop-down box. Again, click the down arrow to open a list of items that can be added and then select the item you'd like to add (see Figure 3-11).

Figure 3-11. Adding a document from the main folder's content menu

Using the Add New Item list from the green border is a handy menu since it's available most of the time.

NOTE **If you're familiar with Zope, you should never, never, never add content from the Zope Management Interface (ZMI). Depending upon how you've installed Plone, you may have already seen the ZMI and used it for customizing and developing Plone through the Web. However, adding content through the ZMI will create content items that are incomplete and don't ***Begin Sidebar*

Understanding Where to Add Content

The easiest place to add content at the beginning is in the user's member folder, accessible by clicking the my folder link. Although this is useful, it's probably not the best approach for a long-term solution. Most noticeably it creates long URLs (for example, /Members/andy/Docum....). It also means your content isn't accurately reflected in the navigation tree.

As you'll see later, a few solutions exist for this; the most common solution is to make a folder and give certain users the right to access it. For example, that folder may be Help or News. The 'Using Folder” section later in this chapter discusses adding folders, and Chapter 9 discusses using group workspaces and security.

Editing a Document

Once you've clicked to add a document, you'll be taken directly to the edit page with a message telling you that the document has been created. If this doesn't happen, you can click a document and then click the edit tab. Again, you'll see that the edit tab becomes highlighted in green (see Figure 3-12).

Figure 3-12. Editing a document

Now you can edit the document in your Web browser, using the form provided. If you look at the URL in the address bar of your browser, you'll note that a short name for the object has been created for you, something such as Document.2003-12-29.43787. The following is a list of the fields and their meanings:

Short name: The short name will become part of the document's URL, so keep the name short and descriptive, preferably without spaces. Keeping to these rules will make URLs easier to read. For example, use something such as audit-report-2003. If you don't provide a name, Plone will create one for you.

NOTE This field won't appear if you selected No for the short names in your preferences page.

Title: This is the title for the item, and it'll be shown throughout the site (for example, at the top of the page, in the search interface, in the title of the browser, and so on). This field is required.

Description: This is a short lead-in to the document, usually about 20 words to introduce the document and provide a teaser for the remainder of the document. This is useful for pages that show summaries of documents, such as search results and folder contents.

Body text: This contains the body of the document. The format for the content is set using the Format field (described next).

Format: You have three choices for the format of body content: Structured Text, HTML, and Plain Text. These types of text are discussed in the 'Choosing a Text Format” sidebar; if you're unsure, leave this field alone and type the body text as usual.

Upload document: If you do have your document as a file on your computer, you can upload it instead of typing the content into the Body Text field. Use the Upload button at the bottom of the page to select a file. The contents of an uploaded file will replace any content in the Body Text field.

Once you've finished editing your document, click the Save button to commit your changes. You'll be returned to the view tab where you can see how the document will be shown to users (see Figure 3-13); to edit it again, click the edit tab.

Figure 3-13. Saving the content will take you to the view tab.

If you don't provide the correct input on the edit form, when you save the document you'll be returned to the edit page, and your errors will be highlighted. At this point your changes haven't been applied—you must correct the mistakes and click Save again before the changes will be committed. The view tab shown in Figure 3-13 shows the document you've created. You'll see that the title, description, and content are all shown in slightly different styles. At the bottom of the page is a byline that contains information about the author of the document, including the date the page was created.

You'll note that if you go back to folder contents after saving your changes, you'll see two documents in your folder: the existing one that's created for you and the new one you've just added. You can edit either of these documents by clicking them to open the view tab, which allows you to select the edit tab.

Choosing a Text Format

As mentioned previously, you can edit the document content in at least three formats: structured text, HTML, and plain text. This rather confusing state of affairs is brought about by trying to produce easy systems for users to write rich marked-up content in plain text without having to use fancy editors.

Unfortunately, in most cases, this really doesn't work; training is required to understand the formatting. Structured text requires quite a bit of understanding in itself because it has a frustrating syntax and doesn't internationalize well. If I had to pick one format that I'd recommend over all the others, I'd pick HTML because it's widely understood, and you can use What You See Is What You Get (WYSIWYG) editors such as Epoz to produce it.

*HTML* HTML is the most standard format; if a document is entered as HTML, it will be rendered in the same format. This HTML shouldn't be a complete page but rather a snippet. For example:

<p>Here is a sample in <i>HTML</i> for a demonstration.</p>

Ideally the HTML should also be valid Extensible HTML (XHTML) to comply with the rest of the Plone system; if it's not, your pages don't comply with Web standards. Entering text as XHTML isn't for the faint of heart, so in Chapter 9, you'll see how into integrate rich-editing tools into Plone that allow users to easily write content in XHTML. The following screen shot shows Plone using Epoz so users don't have to understand HTML:

*Plain Text* Plain text is simple. It does no major conversion or manipulation of the text entered; it's just plain text. The only modification made is that new lines are converted into HTML when rendered so that new lines appear in the Web browser. No other altering happens. For example:

Here is a sample in plain text for a demonstration

*Structured Text* Structured text is a system for writing plain-text documents in a particular format, which can then be interpreted in different ways. For example, if a piece of text needs to be highlighted, then it can written as italics; this will then be shown as italics. This series of rules means that a user can write a page that contains formatting information easily. For a full list of structured text rules and examples, please see Appendix A. The following is a sample of structured text:

Here is a sample in *structured text* for a demonstration

Setting Document Metadata

Any piece of content can have any number of properties assigned to it. These properties are known as metadata and provide information such as keywords, copyrights, and contributors of an item.

This entire set of properties is optional and is usually used only if there are special requirements for this piece of content, especially since this information isn't normally shown to the person viewing the content. So the main reason for entering this data is to add information for tasks such as searching or categorizing the content.

You can access properties on an object by selecting the green properties tab. This properties form has the following fields, which are common to all content types:

Allow Discussion: This lets this document be discussed by users who have the right to do so. If the value is left as default, it'll use the sitewide policy for that content type.

Keywords: Each item can have keywords assigned to it to enable grouping and sorting of the items. For example, an article about recent events in politics may have the keywords politics and prime minister. Keywords are flexible, and you can use any keyword from the given list. By default there are no keywords in the Plone system; site administrators may add new keywords so that other users can select them.

Effective Date: The effective date is the first day a piece of content should be available. You can specify this date by entering the values in the form or clicking the little calendar icon, which opens a calendar, and picking a date (see Figure 3-14).

Figure 3-14. Entering an effective date

Expiration Date: The expiration date is the last day a piece of content should be available. Usually the Effective Date and Expiration Date fields are left blank.

Format: This is the Multipurpose Internet Mail Extensions (MIME) type of the item. The term MIME type refers to a computer definition of the type of content (for example, application/msword or image/jpeg). This is set at a default value; if you're unsure about this field, just ignore it.

Language: This is the language in which the document is written; the default is English.

Copyright: This is the copyright information for the content, which is usually blank.

Contributors: This includes the names of the people outside the Plone system who contributed to the object. Each person's name should be on its own line.

After completing the values for this form, click Save to commit the changes. As stated, usually you won't need to edit the values on this tab. Editing the contents of this tab is usually based upon the requirements for your site and the type of site you're building.

What Are Effective and Expiration Dates?

Any item in the Plone system can have effective and expiration dates if the person editing the content wants. Both of these are optional, and leaving the fields blank will ensure that these values aren't set.

One example of an item that may have an effective date is a press release. In the ideal world, the news item is crafted, prepared, and reviewed in Plone. However, suppose the news item has to go live on the Web site at midnight, but that's exactly when you plan to be sleeping. Not a problem—give the press release an effective date and a time of midnight. Up until the effective date, it won't be visible in the calendar, in navigation, in searches, or in pages that use a search as the listing under the news tab. However, anybody who knows about the press release will be able to access the page directly. Once the effective date has passed, the item will appear in all the aforementioned places and be live to the world.

The effect is similar with expiration dates. If you have a special offer that stops being effective on a particular day, then you could set an expiration date of that day. After that, date it wouldn't appear in calendar, navigation, searches, and so on.

The effective and expiration dates don't actually change the state of the item in workflow (see Chapter 7 for more information on workflow); rather, they just change where it displays. You can also set effective and expiration dates on the state tab, which you'll learn about in the next section.

Publishing Your Document

When a document is created, it's given an initial state, called visible. By default, content isn't automatically published and available to the world; instead, others can view your content, but it doesn't show up in searches or the navigation tree. This is a useful state because you can point other users to this content, but because it won't show up in navigation or searches, it's not visible unless users know about it.

At any point in time, each item of content in your Plone site is in a particular state. This state describes its permissions and roles within the Plone site. By having items in different states, it's possible to apply different security to each item of content. For example, sometimes an item may take a week or two to prepare and involve multiple revisions. Eventually you'll want to publish the content so that it's visible for all users and shows up in the navigation and search.

You can publish the content using the State drop-down menu located at the top right of the main navigation (see Figure 3-15).

Figure 3-15. State drop-down menu

To publish an object, select Submit from the drop-down menu. By default you can't directly publish content, but you can submit it for review. When an item is submitted for review, it moves into the review state. This is an intermediary state between visible and published. It allows for the review of content by users of your site with the reviewer role, before it goes live for the entire world to see. After you've submitted the content, you'll notice that the content is now in the review state by looking at the box in the top-right corner. You'll also notice that in Figure 3-16, there's no longer an edit tab.

Figure 3-16. The content has been submitted for review, the state has changed to pending, and the edit tab is no longer an option.

NOTE If you're logged in as a manager, then you'll note there will be one extra option in the drop-down publishing list called Publish. This lets you put content straight into the published state with no intermediate step.

In the workflow drop-down list in the top-right corner, there's also an option for Advanced, which opens the state form for changing the status of an object. This form is the same as clicking the state tab. It has the following fields:

Effective Date: This is the same as the Effective Date field in the properties (see the 'Setting Document Metadata' action).

Expiration Date: This is the same as the Expiration Date field in the properties (see the 'Setting Document Metadata' section).

Comments: This includes any comments you want to make for this change in state that will be recorded in history. For example, you could enter First draft; Bob, please see second paragraph.

Change State: These mirror the choices available in the drop-down menu. For example, the options are Publish, Submit, and so on. One further option, No Change, is available if no change is necessary.

Select the change of state you'd like to occur, and click Save to commit the changes.

Sharing Your Document

This allows you to assign more rights to other users or groups of users of the system to your document. This is an advanced feature and is covered in more detail in Chapter 9.