Joomla! Documentation™

Overview

This article documents how to use "chunks" when writing help screens for Joomla versions 2.5 and later. The example here is for version 2.5, but it should work for later versions as well. Note that, starting with version 3, we plan to do only one set of help screens for the entire 3.x series. So the chunk names will not have the second digit of the version.

What is a "chunk"?

A chunk in MediaWiki jargon is a reusable piece of content. For help screens, we use chunks for text that will appear more than once in the help screens. For example, we have a column called Category in the Article Manager, Banner Manager, Contact Manager, Newsfeed Manager, and Weblinks Manager. In each of these screens, the Category column shows the category for the item. So, instead of copying and pasting the same text into these different help screens, we create a "chunk" for this. A huge advantage of this approach is that we can edit and improve this chunk in one place and the new version will automatically show in each screen.

Using an Existing Colheader Chunk

The syntax for including an existing chunk for version 2.5 is as follows:

{{Chunkxx:colheader|<Chunk Name>}}

For example, to use the chunk for the category column header for version 2.5, you would enter:

{{Chunk25:colheader|Category}}

This will insert this chunk as shown below:

• Category. The Category this item belongs to.

Before creating a new chunk, check to see if it already exists. You can get a complete list of the available chunks here]. You can get to this page by clicking the Special Pages link on the toolbox menu on the left side of the screen, selecting the desired Namespace (for example, "Chunk25"), and pressing the Go button.

Creating a New Chunk

Creating a new colheader chunk is very easy. However, please be careful to following the naming convention so that others will be able to re-use your chunks.

The steps for creating a new chunk are as follows:

1. Enter the chunk in an article, just as you would for an existing chunk. For example:
   {{Chunk25:colheader|Created By}}
2. Preview the article and scroll to the bottom of the screen. The new chunk will show in red under "Templates used in this preview" as in the example below:
   
   
   Notice that the name of the chunk is "Chunk25:Help screen column header Created By", whereas we entered "Chunk25:colheader|Created By". The wiki automatically replaces the word "colheader" with the name "Help screen column header" for us.
3. Open the edit link in a new browser window. (Otherwise, you might lose your edits on the current article you are editing.) You will be taken to a screen where you can enter in the text for this chunk. This is just like editing any other wiki article.
4. After you have entered and saved the text for the chunk, return to your original article and again click on Preview. Now you should see the chunk show as normal text.

Naming Conventions

The key idea for naming conventions is to be consistent in how we name chunks so we don't end up with duplicates. Here are a few guidelines:

• For items that appear in the column heading of a manager screen, use the exact column header name (for example, "Access", "Created By", and so on).
• Generally use initial caps.
• In many cases, we have the same name for a value in a column header as we do when entering the value in an edit screen. (For example, Category or Title.) In these cases, we need different help text for the value as a column versus the value as an entry. The convention is to use the column name for when the value appears in a manager list (for example, "Category") and the word "Enter" in front when the value is being edited (for example, "Enter Category").

Tips

• If you aren't sure whether this chunk will be used somewhere else, you don't need to worry about creating a chunk. Just enter the text. It is very easy to go back later and convert text to chunks if needed.
• Check the existing chunks before creating a new one. Also, use the existing chunks as a guide for naming and other conventions when creating new chunks.
• Don't be afraid to make a mistake! One great thing about the wiki is that we can easily tidy things up later. The main thing is to get useful content in the help screens to help users with Joomla.