JDOC

Difference between revisions of "Using chunks in Joomla help screens"

From Joomla! Documentation

m (Hutchy68 moved page Using chunks in Joomla help screens to JDOC:Using chunks in Joomla help screens: wiki instructions, should be JDOC)
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{JVer|2.5}}
+
{{RightTOC}}
= 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 will work for later versions as well. Note that, starting with version 3, we are only using one set of help screens for the entire 3.x series. This means the help screen will all use Chunk30.
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"? =
+
==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.
+
A chunk in MediaWiki jargon is a reusable piece of content. This is very similar to how the Template namespace is used in articles. 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 =
+
==Using an Existing Colheader Chunk==
The syntax for including an existing chunk for version 2.5 is as follows:
+
The syntax for including an existing chunk for generic Joomla version is as follows:
  
<nowiki>{{Chunkxx:colheader|<Chunk Name>}}</nowiki>
+
<code><nowiki>{{Chunkxx:colheader|<Chunk Name>}}</nowiki></code>
  
 
For example, to use the chunk for the category column header for version 2.5, you would enter:
 
For example, to use the chunk for the category column header for version 2.5, you would enter:
  
<nowiki>{{Chunk25:colheader|Category}}</nowiki>
+
<code><nowiki>{{Chunk25:colheader|Category}}</nowiki></code>
  
This will insert this chunk as shown below:
+
This will insert the Category chunk as it is shown below:
 
{{Chunk25:colheader|Category}}
 
{{Chunk25:colheader|Category}}
  
Before creating a new chunk, check to see if it already exists. You can get a complete list of the available chunks [http://docs.joomla.org/index.php?title=Special%3AAllPages&from=&to=&namespace=136 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.
+
====Putting Them All Together====
 +
Now let's piece together multiple chunks to show how they are used practically.{{-}}
 +
<code><nowiki>{{Chunk25:colheader|Category}}</nowiki></code>{{-}}
 +
<code><nowiki>{{Chunk25:colheader|Title}}</nowiki></code>{{-}}
 +
<code><nowiki>{{Chunk25:colheader|Created Date}}</nowiki></code>{{-}}
 +
 
 +
The use of 3 <code><nowiki>{{Chunkxx:colheader|<Chunk Name>}}</nowiki></code> will now show 3 different pieces of information displayed in the sequence they are listed. Here's the above example:
 +
{{Chunk25:colheader|Category}}
 +
{{Chunk25:colheader|Title}}
 +
{{Chunk25:colheader|Created Date}}
 +
 
 +
==Creating a New Chunk==
 +
Before creating a new chunk, check to see if it already exists. You can get a complete list of the used Chunk25 [http://docs.joomla.org/index.php?title=Special%3APrefixIndex&prefix=&namespace=136 pages here] or the Chunk30 page can be [http://docs.joomla.org/index.php?title=Special%3APrefixIndex&prefix=&namespace=140 found here]. You can get to this page by clicking the Special Pages link on the toolbox menu:
 +
# In the 2nd section('''List of Pages''') click ''All Pages with Prefix''
 +
# Select the desired Namespace (for example, "Chunk25") from the drop-down input box
 +
# Then press the "Go button" to see a list of all the pages in the "Chunk25" namespace.
  
= 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.  
 
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:
 
The steps for creating a new chunk are as follows:
# Enter the chunk in an article, just as you would for an existing chunk. For example:
+
# Enter the chunk in an article, just as you would for an existing chunk. For example:{{-}}<code><nowiki>{{Chunk25:colheader|Created By}}</nowiki></code>{{-}}
::<nowiki>{{Chunk25:colheader|Created By}}</nowiki>
+
# 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:[[File:Chunk-tutorial-screenshot-20120622-01.png|frame|none]]<br>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.
# 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:[[File:Chunk-tutorial-screenshot-20120622-01.png|frame|none]]
 
: 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.
 
 
# 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.  
 
# 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.  
 
# 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.
 
# 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 =
+
==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:
 
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).  
 
* 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).  
Line 37: Line 48:
 
* 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").
 
* 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 =
+
==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.
 
* 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.
 
* 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.

Revision as of 19:53, 23 November 2013

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 will work for later versions as well. Note that, starting with version 3, we are only using one set of help screens for the entire 3.x series. This means the help screen will all use Chunk30.

What is a "chunk"?[edit]

A chunk in MediaWiki jargon is a reusable piece of content. This is very similar to how the Template namespace is used in articles. 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[edit]

The syntax for including an existing chunk for generic Joomla version 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 the Category chunk as it is shown below:

  • Category. The Category this item belongs to.

Putting Them All Together[edit]

Now let's piece together multiple chunks to show how they are used practically.

{{Chunk25:colheader|Category}}

{{Chunk25:colheader|Title}}

{{Chunk25:colheader|Created Date}}

The use of 3 {{Chunkxx:colheader|<Chunk Name>}} will now show 3 different pieces of information displayed in the sequence they are listed. Here's the above example:

  • Category. The Category this item belongs to.
  • Title. The name of the item. For a Menu Item, the Title will display in the Menu. For an Article or Category, the Title may optionally be displayed on the web page. This entry is required. You can open the item for editing by clicking on the Title.
  • Created Date. The date the item was created.

Creating a New Chunk[edit]

Before creating a new chunk, check to see if it already exists. You can get a complete list of the used Chunk25 pages here or the Chunk30 page can be found here. You can get to this page by clicking the Special Pages link on the toolbox menu:

  1. In the 2nd section(List of Pages) click All Pages with Prefix
  2. Select the desired Namespace (for example, "Chunk25") from the drop-down input box
  3. Then press the "Go button" to see a list of all the pages in the "Chunk25" namespace.

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:
    Chunk-tutorial-screenshot-20120622-01.png

    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[edit]

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[edit]

  • 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.