Joomla! Documentation - User contributions [en]

Accessing the database using JDatabase

2009-09-08T10:27:33Z

Tahar:

Using Class Suffixes

2009-08-30T03:28:16Z

Tahar: /* Menu Class Suffix */

This tutorial will show you how to use Page, Module, and Menu Class Suffixes in Joomla! 1.5 to fine-tune the appearance of your site. For the tutorial, we will assume you have the Joomla! 1.5.9 Sample site available.

==Background==
Joomla! creates HTML pages that use [[Glossary#Cascading_Style_Sheet_.28CSS.29|Cascading Style Sheets]] to control the appearance of the page. This includes things like fonts, colors, margins, and background. The CSS files are part of your template.

When Joomla! creates a page, it creates different CSS classes that are then referenced in the CSS file to specify which style will apply to which parts of the HTML page. These class names are pre-programmed into Joomla!. But Joomla! allows you to modify or add CSS classes by way of the Class Suffix parameters. This lets you fine-tune the appearance of specific pages with no programming and very little work. The best way to understand this is to see specific examples.

==When Would You Use a Class Suffix?==
Say, for example, that your website contains a number of Section Blog layouts, each for a different Section. If you are happy to have all of these pages styled the same way, then you wouldn't need to use a Page Class Suffix. However, say you want each of these sections styled differently than the others. For example, maybe you want a different background color or image for each different section.

Or say that you want the heading on your front page to look different than the heading on other pages.

In both of these cases, if you modify the styling in your "template.css" file for the standard CSS classes, it will affect all Menu Items that use these CSS classes. For example, if you change the style for the CSS class "componentheading", it will affect all of the Menu Items that use this class.

However, if you add a unique Page Class Suffix to a Menu Item, then Joomla! will create new CSS classes for each individual Menu Item so you can style each one differently.

==Page Class Suffix==
Before you start, make sure you have the Joomla! sample website available. Also, make sure the default template is set to "rhuk_milkyway" (in the Extensions → Template Manager).

===How It Works Without a Page Class Suffix===
Before we add a Page Class Suffix, let's see how this pages works without one. In the front end, navigate to Example Pages → Section Blog. In your browser, select the option to view the page source code. For example, in Firefox, press Ctrl+U. In Internet Explorer, select View → Source. In Safari, select View → View Source.

Using the "Find" command, find the first occurrence of the word "componentheading". It should look like the following: <pre><div class="componentheading"></pre>

Browse down the file and find the following tags:
:<pre><table class="blog" cellpadding="0" cellspacing="0"> </pre>

:<pre><table class="contentpaneopen"></pre>

:<pre><td class="contentheading" width="100%"></pre>

:<pre><table class="contentpaneopen"></pre>

<blockquote>''Note: The following screenshots were made using the free Firefox add-in called "Firebug". Firebug allows you to quickly see the relationship between the HTML elements in your source and the text and graphics shown on the page. It is a very handy tool, and you can get it [https://addons.mozilla.org/en-US/firefox/addon/1843 here]. There is also a free video tutorial about using Firebug with Joomla! available [[Tutorial:Using_Firebug_With_Your_Joomla_Website|here]].''</blockquote>

The screenshot below shows you the "componentheading" class. It is the page title area above the blog article.

[[Image:Componentheading_class_firebug.png]]

This screenshot shows you the entire "blog" class. This is the outer table into which all of the articles will fit.

[[Image:Blog_class_firebug.png]]

The next screenshot shows you the "contentpaneopen" class for an article heading. This includes the article title and the PDF, Print, and Email icons to the right.

[[Image:Contentpaneopen_class_title_firebug.png]]

This screenshot shows you the "contentpaneopen" class for the body of the article. This includes the author and date information as well as the actual article text.

[[Image:Contentpaneopen_class_article_firebug.png]]

So this gives us a good understanding of how Joomla! allows us to style the elements on a Section Blog layout. Joomla! writes out these classes as part of the HTML. And the template contains CSS that provides the styling information for these various elements and classes.

===Page Class Suffix (No Space)===
Now that we see how this works without a Page Class Suffix, let's try it with one. In the back end, navigate to Menus → Example Pages and click on "Section Blog". This should display the "Menu Item: [Edit]" screen for the Section Blog Layout. Click Parameters (System) to show the System Parameters. In the "Page Class Suffix" field enter the value "_myBlogSuffix" and click the Save button.

Now, go back to the front end and again navigate to Example Pages → Section Blog. Notice right away that we lost the styling for the page and article titles. Let's look closer to see why.

Using the browser "Find" command, find the first occurrence of "_myBlogSuffix". It is in a "div" tag and looks like this: <pre><div class="componentheading_myBlogSuffix"></pre> If you look through the source, you should also see the following classes: <code>blog_myBlogSuffix</code>, <code>contentpaneopen_myBlogSuffix</code>, and <code>contentheading_myBlogSuffix</code>.

By adding the Page Class Suffix, we ''changed'' all of these class names. That means that special styling in the CSS file that refers to the "base" class names (like componentheading, blog, and so on) will not be applied, since those classes no longer exist on the page.

Now, you can fix this problem by editing your templates CSS file to add the same styling for the new classes (for example, "componentheading_myBlogSuffix"). But there is a much easier way to do this -- simply by adding a leading space to the parameter.

===Page Class Suffix (With a Leading Space)===
Again in the back end, go back to Menus → Example Pages → Section Blog. We're going to change the value of the Page Class Suffix. This time we're going to enter in a leading space and call it <space> + "myBlogClass", as shown below.

[[Image:Page_class_suffix_space.png]]

Now, go back to the front end and re-display the Example Pages → Section Blog. Notice that our styling is back! Let's look at the HTML source to see what is going on. Open the source and find the first occurrence of "myBlogClass". It should like this: <pre><div class="componentheading myBlogClass">
</pre> Because we put a leading space in the Page Class Suffix, we created a second class instead of changing the name of the first class (which is allowed and supported by all modern browsers). So we didn't break any of the existing CSS styling for this page. (One warning: we need to make sure the new class name is different than any of the other class names used on the page. Otherwise, we might get styling we don't want.)

===Add CSS Styling to New Class===

At this point, we've created a new CSS class in the HTML to allow for some new styling. Now we need to use this new class to actually change the look of our page. The first thing we need to do is find the applicable CSS file. In this case, it is <code><joomla_root>/templates/rhuk_milkyway/css/template.css</code>.

Let's say we want to add a background color, but only to this specific Section Blog. (Remember, if we wanted to just change all of the Section Blog pages in our site, we could just change the CSS styling for the base classes, such as "componentheading" or "blog".) We need to do is figure out which area ("componentheading", "blog", or "contentpaneopen") we want to style. Say we just wanted to style the "componentheading" area.

First, let's use the CSS selector "div.myBlogClass" and add the following code to the end of our CSS file:<source lang="css">
/* Custom Styling */
div.myBlogClass {
background-color: #FFE4E1; /* mistyrose */
}
</source>

The result is that the page heading now has the background color, as shown below.

[[Image:Div_styling_example.png|center|frame]]

Now this works fine in our example, because the other classes are defined for "table" tags and not "div" tags. But it is normally better to be more specific in our style selector by styling only those elements that have both the desired base class and the new class. For example, let's replace the code above with the following code:
<source lang="css">/* Custom Styling */
.blog.myBlogClass {
background-color: #FAFAD2; /* lightgoldenrod */
}
</source>

This specifies that the new style will only be applied to elements that have both the "blog" and the "myBlogClass" styles. This gives us the background color over the entire "blog" area, as shown below.

[[Image:Blog_styling_example.png]]

The great thing about creating a ''new'' class (with the leading space trick) is that we don't need to copy all of the existing styling for the base classes. We can just focus on the new styling that we want.

Now in this example, we focused on the Section Blog layout. The class names for different components might be different, but the process will be the same. The table below shows some common Joomla! layouts and a list of class names that can have Page Class Suffixes added.

{| class="wikitable"
|-
! Layout
! CSS Class Names Used
|-
| Article Layout
| componentheading, contentpaneopen, contentheading, contentpagetitle
|-
| Category Blog, Frontpage Blog, Section Blog
| componentheading, contentpagetitle, blog, contentpaneopen, contentheading, readon, blog_more
|-
| Category List, Section List
| componentheading, contentpane, contentdescription
|-
| Contact Category
| componentheading, contentpane, contentdescription, sectiontablefooter, sectiontableheader, category
|-
| Contact Layout
| componentheading, contentpaneopen, contentheading
|}

So, to sum up what we have learned about using the Page Class Suffix parameter:
# Use a leading space to create a new CSS class. This way you don't have to worry about re-doing or breaking existing CSS styles.
# Look in the HTML source code to find the locations of the base and new classes.
# If desired, use Firebug to see which HTML elements correspond to which areas on the page.
# Add custom styling to the end of the "template.css" file, specifying both the name of the desired base class and the custom class in the form <code>.baseclass.customclass</code> as in the example above.

==Module Class Suffix==
The Module Class Suffix parameter works in the same way as the Page Class Suffix. Let's go through an example using the Latest News module.

In the administrative back end, navigate to Extensions → Module Manager and find the "Latest News" module. Click on it to open it for editing, and enter <space> + "customLatestClass" in the Module Class Suffix parameter field, as shown below:

[[Image:Module_class_suffix_space.png]]

Now, navigate to the home page in the front end and view the page source code. The screenshot below was made using the Firebug add-in tool. It shows the home page and the HTML and styling for the customised Latest News module.

[[Image:Latest_news_custom_class.png]]

In the upper part of the screen, outlined in light blue, is the "div" element for the module. Below, in the HTML window, we see the HTML as follows: <pre><div class="moduletable customLatestClass"></pre> and then <pre><ul class="latestnews customLatestClass"></pre>

The "moduletable" and "latestnews" classes are created automatically. The new class, "customLatestNews" was created because we started the Module Class Suffix parameter with a leading space.

Now, let's use our new class to add some custom styling. Again, go to the end of the templates/rhuk_milkyway/css/template.css file and add the following code:
<source lang="css">
div.customLatestClass {
background-color: #FFFFD2;
}

div.customLatestClass h3, ul.customLatestClass, ul.customLatestClass a {
color: #8B4513;
}
</source>

Save the file and re-display the home page. It should look like the screenshot below:

[[Image:Latest_news_styled.png]]

The CSS selector <code>div.customLatestClass</code> sets the background color for the entire area. The three selectors <code>div.customLatestClass h3, ul.customLatestClass, ul.customLatestClass a</code> select the font color for the "h3" heading, the bullets ("ul" tag), and the "a" tag, respectively. Note that, if we only wanted to style the "ul" element, we wouldn't need a Module Class Suffix unless we had more than one "Latest News" module. Instead, we could just have defined the CSS using the standard "latestnews" class.

===Be careful not to break existing CSS styling===

In menus, we need to be careful not to break existing CSS styling.

Let's look at how this works. In the administrative back end, navigate to Extensions → Module Manager and open the Main Menu for editing. Click on the Advanced Parameters. Notice that the Module Class Suffix is set to "_menu", without a leading space.

Now, go to the Home page in the front end and view the source code (or use Firebug). The screenshot below shows the HTML for the Main Menu.

[[Image:Main_menu_div.png]]

Notice that the class is called "module_menu" because of the Module Class Suffix. Also, notice that there is special styling in the "template.css" and "blue.css" files for the "module_menu" class. For example, there is a background image that provides part of the blue border around the menu.

We can confirm this by returning to the back end and changing the Module Class Suffix to blank. Return to the Home page and refresh. Now the Main Menu will show without the special "module_menu" styling, as shown below:

[[Image:Main_menu_no_suffix.png]]

This shows an important point. Existing modules, especially menus, may already have CSS styling that depends on Module Class Suffixes. So we need to be careful when making changes.

What if we still wanted to add some special styling just to the Main Menu? One way is to get tricky and add a second CSS class to the existing suffix. To see this, return to the Module Manager in the back end and open the Main Menu for editing. This time, in the Module Class suffix, enter <code>_menu</code>, a space, and then <code>myMenuClass</code>, as shown below:

[[Image:Module_class_suffix_tricky.png]]

Now, add the following code to the end of the templates/rhuk_milkyway/css/template.css file:
<source lang="css">
div.myNewClass {
font-size: 1.2em;
}
</source>

Go back to the Home page and notice that now the font in the Main Menu is larger, as shown below.

[[Image:Main_menu_custom_style.png]]

If we open Firebug, we can see what the HTML and CSS looks like, as shown below:

[[Image:Firebug_custom_menu_class.png]]

By putting a space between the "_menu" and "myNewClass", we added the new class into the HTML. Then, by selecting the new class in the CSS file, we changed the font size.

==Menu Class Suffix and Menu Tag ID==
All core modules allow you to enter a Module Class Suffix, as discussed above. Menu modules have two additional parameters: Menu Class Suffix and Menu Tag ID. Let's look at what these parameters do.

===Menu Class Suffix===

The Menu Class Suffix inserts an extra suffix in the class for the unordered list that builds up the menu. If unedited, the class is "menu". If adding "_myMenuClass" under Advanced Parameters → Menu Class Suffix, the new tag will be "menu_myMenuClass".

(This behaviour is only for the Menu Style "List". If choosing "Legacy - Vertical" or "Legacy - Horizontal", the class suffix will be added to the links in the table; this suffix will then be "mainlevel_myMenuClass". When choosing the Legacy Flat List, the suffix will be added to the links (as on the two other Legacy lists), but it will also be added to the ul tag, but as an id rather than a class; the id will be "mainlevel_myMenuClass".)

===Menu Tag ID parameter===

Now, lets look at the Menu Tag ID parameter. Navigate to the back end, open the Main Menu module for editing, and enter "myTagID" in the Menu Tag ID parameter.

Add the following code to the end of the templates/rhuk_milkyway/css/template.css file:
<source lang="css">
#myTagID {
list-style-type: square;
}
</source>

Now, re-display the Home page to see the change. The bullets for the Main Menu should now appear as squares, as shown below:

[[Image:Main_menu_square_bullets.png]]

Finally, we can look at the HTML and CSS in Firebug, as shown below.

[[Image:Menu_tag_id_code.png]]

Joomla! has added the attribute <code>id="myTagID"</code> to the "ul" tag for the Main Menu. This allowed us to change the style for this ID. Note that, since this is an "id" attribute, we use the CSS selector <code>#myTagID</code> (with a "#" instead of a ".").

==Conclusion==
The Class Suffix and Menu Tag ID parameters allow you to fine-tune the CSS styling of your web site. By using a leading space in the suffix name, we can create a new class. This is normally the preferred method, since, as long as the new class name does not conflict with an existing class, no existing styling will be broken.

[[Category:Tutorials]]

J1.5:Creating a submenu

2009-08-30T03:08:54Z

Tahar: /* Menu Modules */

In Joomla!, submenus can be shown either as one menu with two or more levels or as completely separate menu modules. To show how to do this, we will step through creating a two-level menu and then see how to show it either as one large menu or as separate parent and child menus.

==Example Data==
In our example, we will create a menu called "Pets". It will have two top-level menu items called "Dogs" and "Cats". Under Dogs, we will have "Collies" and "Greyhounds". Under Cats we will have "Tabbies" and "Siamese". So the structure of the Pets menu will be as follows:
*Dogs
**Collies
**Greyhounds
*Cats
**Tabbies
**Siamese

==Menu and Menu Items==
To create this structure, we create one menu with two levels of Menu Items. Note that we do this whether we want to have everything shown as one large menu or whether we want to create separate menu modules (one parent menu and two child menus). We'll see how to do this later on, when we create the modules.

Here are the steps to create the Menu and Menu Items.
# Create a new Menu in the Menu Manager called "Pets".
# Add a new Menu Item called "Dogs". For this example, we don't really care what the type of the Menu Items is. For example, you can just create one article called "Pet Menu Test" and then create all of the Menu Items as type '''Article → Article Layout''' and point to this article.
# Add a second Menu Item called "Collies" (again, Menu Type of Article Layout as above). In the Parent Item box, select "Dogs", as shown below: [[Image:submenu_example1.png|frame|center]]
# Add a third Menu Item called "Greyhounds", again making "Dogs" the Parent Item. (Remember, these can all point to the same article.)
# Add the "Cats" Menu Item. Be sure to make the Parent Item for this "Top".
# Add the last two Menu Items, "Tabbies" and "Siamese", making "Cats" the Parent Item for both.

When you get done, the Menu Item Manager should look like the following:[[Image:submenu_example2.png|frame|center]]

==Menu Modules==
At this point, we've got the Menu and Menu Items done. Now we need to create the Menu Modules. In Joomla!, the Menu Module determines three main things: (1) what the menu looks like; (2) where on the page it will show; and (3) on which pages it will show. We will do two examples. In the first example, we will create one Menu Module that shows all of the items in one menu. In the second, we will create three separate menu modules to show the Pets, Dogs, and Cats menus as separate modules.

===One Menu Module===
To show this as one module, follow these steps:
# Navigate to Extensions → Module Manager, click the "New" icon in the toolbar, and select "Menu".
# Enter the Title as "Pets Menu" and Position as "left".
# In the Menu Assignment, enter "Select Menu Item(s) from the List" and select "Home" (under "mainmenu"), and all of the Menu Items under the "pets-menu".
# In Menu Name, select "pets-menu" from the drop-down list box.
# If you are using the default "rhuk_milkyway" template and want the menu to look like the other menus, in the Advanced Parameters enter "_menu" for Module Class Suffix.

Now, navigate to the front-end home page. You should see the Pets Menu as shown below:[[Image:submenu_example3.png|frame|center]]Click on the Dogs Menu Item. The selected article displays and the Dogs menu expands to show the two submenu items, Collies and Greyhounds. Note that we can set a parameter in the Module Manager to always show submenu items. Here we have taken the default value of "No".

Click on "Collies" and again the article changes. (Or it would if we had different articles for each Menu Item!) The screen should look like the one below: [[Image:submenu_example4.png|frame|center]]

Notice that the Breadcrumbs now shows three levels: Home, Dogs, Collies. Because we used submenus, Joomla! "knows" that Collies is under Dogs.

===Separate Menu Modules===
Now we will change our example to create three separate menus -- one for the top level (Dogs and Cats), one for the Dogs (Collies and Greyhounds), and one for the Cats (Tabbies and Siamese).

<blockquote>''Note: Make sure that your Menu Items each have a unique Alias value. If you use the Copy command in the toolbar of the Menu Item Manager to create these Menu Items, the Alias will be the same as the item being copied. In this case, just edit the Alias value to make it unique (for example, the same as the Title). If you have duplicate Alias values, the menus will not work correctly if the parameter SEF URLs is set to Yes in Global Configuration.''</blockquote>

To do this:
# Open the Pets Menu in the Module Manager and change the Title to "Pets Menu Top Level Only".
# Select the Left Position.
# Under Module Parameters, select the Menu Name "Pets Menu"
# Under Module Parameters, change the Menu Style to "List".
# Set the Start Level to "0" and the End Level to "1".
# ''This is optional. It allows your template to apply special a menu style to the menu (a border, for example).'' In Advanced Module Parameters put "_menu" in Module Class Suffix.
# For submenu Dog, in extensions menu select Module Manager, click New and select Menu, and set the title to "Dogs Submenu".
# Set the Position to "Left".
# ''Now this part is very important.'' We only want this submenu to show when we are in one of the Dogs Menu Items. So, in the Menu Assignment box, select the three items "Dogs", "Collies", and "Greyhounds", as shown below: [[Image:submenu_example5.png|frame|center]]
# Under Module Parameters, select the menu name "Pets Menu" and change the Menu Style to "List".
# Set the Start Level to "1" and End Level "2".
# ''This is optional.'' In Advanced Module Parameters, set Module Class Suffix to "_menu".
# For the "Cats Submenu", repeat steps from 7 to 12 except step 9. In the Menu Assignment box, select the items "Cat", "Tabbies" and "Siamese" (so this menu will only show under these Menu Items).

At this point, we have three menu modules all pointing to the Pets Menu. The only differences between them are (1) the Start and End Levels and (2) the Menu Item Assignment.

Now, in the front end, navigate to the Home page. The "Pets Menu Top Level Only" menu should show. Select the "Dogs" Menu Item. Now, the "Dogs Submenu" should show as a separate menu, as shown below:[[Image:submenu_example7.png|frame|center]]

Click on the Collies Menu Item and notice that again the Breadcrumbs shows the hierarchy of "Home", "Dogs", and "Collies".

Using this same technique, it is easy to create third-level submenus. You just make the Parent Menu Item a second-level submenu. Then you could use the same technique to create a separate Menu Module with Start Level of 2 and End Level of 3. This would show only the third-level Menu Items.

[[Category:Tutorials]]

J1.5:Moving a menu to a different position

2009-08-30T02:55:00Z

Tahar: /* Related Articles */

{{review}}
== Moving a menu to a different position ==

=== Joomla! 1.5 ===

Go to '''Extensions'''>'''Module Manager''' and select the module that your menu is being displayed through.

[[Image:Menu_Module.jpg]]

Next select the position that you would like your menu to be in on the front end of your site. (Positions vary from theme to theme so make sure you know your theme)

[[Image:Menu_Module_position.jpg]]

=== Joomla! 1.0 ===

Go to '''Modules'''>'''Site Modules''' and select the module that your menu is being displayed through.

[[Image:Module_1_0.jpg]]

Next select the position that you would like your your menu to be in on the front end of your site.

[[Image:Module_1_0_Positions.jpg]]

== Related Articles ==

* [http://docs.joomla.org/Modules_Administrator Module Administrator]
* [http://docs.joomla.org/Screen.modules.15 Module Manager]

J1.5:Moving a menu to a different position

2009-08-30T02:52:37Z

Tahar: /* Joomla! 1.5 */