How Joomla! Works

From the Rough Cut

Joomla! Programming

Learn More

From the Rough Cut

From the Rough Cut 

Joomla! Programming

Learn More

Tour of Joomla! Folders

When you install Joomla, it installs the folders and files shown in the figure below.

Figure 1: Joomla! Version 1.6 Folders and Files

Note that, in a production version, the "installation" folder would normally be deleted, because keeping it around presents a security vulnerability. If you download Joomla using the SVN repository, you will get a folder called "tests" that contains the automated unit and system test files. These are removed when Joomla is packaged for normal installation.

Front End versus Back End

If you have used Joomla, you are familiar with the concept of the front end and back end (sometimes called the administrative back end). We can think of these are completely separate applications that happen to share some common libraries.

If you look at the sub-folders of the administrator folder, you will see many of the same folders that you see in the top-level folder. These include cache, components, includes, language, modules, and templates.

The administrator folder also has its own version of "index.php". So, when you enter the URL "http://mywebsite.org/administrator" it loads this file (administrator/index.php) which starts the administrator application. When you enter the URL "http://mywebsite.org" it loads the "index.php" file from the top-level folder, which starts the front-end application.

Each of these folders is discussed briefly below. Since the administrator folder it is similar in structure to the top-level, we will wait and discuss it last.

Cache

The cache folder is very easy to understand. This is just where we store our cached files. In a dynamic website, the system does a lot of work to pull together the information to display a page. For example, if the page is displaying a blog layout, the system has to access the database to get the articles for the blog; layout the articles on the page; and load the desired modules for the page.

In many real-life websites, the information for a page might stay the same for hours or days. So, if you have 50 users requesting the same page per hour, and the information is only changing once per day, you would be getting the exact same information from the database about 1,200 times (50 x 24) before the information actually changed.

With caching enabled, we try to reduce the number of times we access the database to get exactly the same information. In our example above, if we cache the page, we save a copy of the page in the cache folder for a specified period of time – perhaps 15 minutes. When the first user requests the page, it is compiled from the database in the normal manner, and a copy of the entire page is saved in the cache folder.

If a second user requests exactly the same information, the system first checks to see if there is a cached copy of the page that has not yet expired (less than 15 minutes old, in our example). If so, the page is read from the cached copy and we don't have to access the database or assemble the page. This allows the page to load much faster and also reduces the amount of work the server must do.

On a busy website where the frequency of viewing is greater than the frequency of database changes, caching can improve overall system performance dramatically.

The files in this folder are deleted when you select Site → Maintenance → Clear Cache or Site → Maintenance → Purge Expired Cache. If you run a large production site, you may also run a system-level job to remove unneeded cache files from this folder.

Components

A component is normally the main thing on a given page and usually corresponds to a menu item. When you select an item from a menu, the page that loads contains the component defined by that menu item.

If we look at the sub-folders for components, we see each of the core components for Joomla: com_banners, com_contact, com_content (for articles), com_mailto, com_media, com_newsfeeds, com_search, com_users, com_weblinks, and com_wrappers. As you have probably figured out by now, the component folders all start with the letters "com_" followed by the component name. This is one example of strong naming conventions that are used throughout Joomla. We will discuss these later in this chapter.

If we look at the options when you are creating a new menu item for the core components, we have the options shown in the figure below.

Figure 2: Front End Core Menu Types

Most of these menu item types match up exactly to one of the folders. These include contacts, articles (which uses the com_content folder), newsfeeds, search, users, weblinks, and wrapper.

The components "com_banners", "com_mailto", and "com_media" do not correspond to menu item types. Banners are components but they get inserted into pages inside modules. When you click on the Email icon to email an article to someone, the com_mailto is the component that is called. "com_media" is the component that is called when you edit an article in the front end and you press the Image button to load the Media Manager.

These components do not display as the main thing on a page and therefore don't fit the simple definition of a component. This brings us to the more detailed and technical definition of a component, which is this. A component is an extension that has to take some action other than displaying something. For example, when you click on a banner, it has to write to the database to record the click and then perhaps redirect you to another URL. Similarly, when you click the Email icon, it has to offer you a form to fill out and then send the email. When you want to insert an image into an article, you are again taking actions, such as uploading an image to the web server.

So, in all of these cases, we need a component to handle these actions, even though these components will never be the central content of a page on our site.

Images

The images folder is one place where image files for the site can be stored. For example, in the core distribution, we have sub-folders called "banners" and "sampledata". As you would expect, the banners folder stores images for the example banners that are included in the core distribution. The "sampledata" folder stores images that are used in the sample data that you can install (optionally) when you install Joomla.

Figure 3: Browser Window of Images Folder Without index.html File

Includes

We mentioned earlier that the administrator folder, which controls the back end of the site, can be thought of as an entirely separate application from the front end of the site. For this reason, when we start a front end or back end session, we need to load different classes and constants into our session.

The includes folder contains the programs that are specific to either the front or back end application. So, the top-level includes folder loads the files that we need to get a front-end session started, whereas the administrator/includes folder has files we need to load to get a back-end session started.

The includes folder contains the following files:

Installation

The installation folder is a entire separate mini-application that does one thing -- the initial Joomla installation. When you initially start either a front or back-end session, the system checks for the presence of a file called "configuration.php" in the root folder. If it doesn't find this file, it assumes you need to run the installation and it loads the installation mini-application.

Since this is a self-contained mini-application, it has it's own "includes" folder as well as other folders needed to run the installation process. One of the great things about Joomla is how easy it is to install. Everything is done for you, including creating the database. This cool stuff is done in the installation mini-application.

Language

Joomla is designed to be run natively in any of 63 (and counting) languages. As discussed in Chapter 2, virtually all text in Joomla is translated before it is shown in the browser. This is done by way of language packs, which install a set of language files. The "languages" sub-folder is where these language packs get installed.

With a standard English installation, we get two sub-folders: en-GB and overrides. The first folder holds all of the language files needed to translate the front end of the site into English. (The GB stands for Great Britain. The official English for Joomla is British English.)

The second folder is related to a new feature in version 1.6 – language overrides. Language overrides allow you to change the value of any text string without having to replace the entire language file. We will show an example of this in Chapter 5.

Note that there are often two language files per extension, one ending in ".sys.ini" and one ending in just ".ini". The ".sys.ini" files are loaded to get the name and description of the extension, for example, for showing in the Module Manager. We load the ".ini" file when we are actually working with the extension to show all of the text used by this extension.

Libraries

A software library is a set of programs that are designed to be reused to perform a specific task or set of tasks. These software libraries are stored in sub-folders of the libraries folder.

In version 1.5, Joomla used 14 libraries. 13 were external libraries from third-party developers and one was the Joomla library.

In version 1.6, this has been reduced to four. The three external libraries are "phpmailer", used for sending email; "phputf8", used for some operations on UTF-8 text; and "simplepie", used for RSS feeds.

The library folder we are most interested in is the "joomla" folder. This folder contains the Joomla platform classes. We will discuss this in more detail later in this chapter.

Logs

This folder is used to store log files generated by Joomla. Events are logged based on certain conditions. For example, any error condition will be logged in a file called "error.log". In addition, turning on debug mode will cause some events to be logged.

Media

The media folder holds CSS, Javascript, and image files for some of the components, modules, and editors. The system sub-folder contains, among other things, the mootools JavaScript framework, which is used in Joomla to supply certain JavaScript functionality. We will discuss JavaScript and Mootools in more detail in Chapter 11.

Modules

The modules folder contains a sub-folder for each front-end module available. The figure below shows the sub-folders on the left and a list of the Module Types you see when you create a new module in the Module Manager on the right.

Figure 5: Module Sub-Folders and Module Types

Each module type has it's own sub-folder. The table below shows which module names correspond with which sub-folder names.

When you install module extensions, they get added as sub-folders to the modules folder and become completely integrated into your Joomla application. We will discuss modules in detail in Chapter 7.

Plugins

The plugins folder holds the plugins extensions. There are eight types of plugins, each with its own sub-folder, as indicated in the table below. Each plugin type deals with a specific type of activity on the site and fires events during these activities.

We will discuss plugins in more detail in Chapter 6.

Templates

In Joomla, the content of each web page is separated as much as possible from the way the page is presented on the screen. The presentation is controlled by extensions called templates.

The templates folder contains a sub-folder for each front-end template that is installed on the system. In the default installation, this includes "atomic", "beez_20", and "beez5". This folder also contains a "system" folder. The "system" template has some layout information that is shared by all of the other templates and also is used by the system as a fall-back in case a CSS class or file can't be found in the named template.

We discuss the template folders in more detail in Chapter 5.

Tmp

The "tmp" folder, as you might guess, is a place for the system to store files on a temporary basis. One of the most frequent uses of this folder is when extensions are installed. When a new extension is installed, a copy of the extension's archive file is copied into the "tmp" folder and then is unpacked into the correct Joomla folders.

Administrator

As discussed earlier, Joomla can be thought of as two separate applications that share some of the same underlying code. These applications are the front end of the site and the administrative back end of the site.

This is evident when you look at the sub-folders under the "administrator" folder. The administrator folder contains many of the same sub-folders as the top-level folder, including: cache, components, help, includes, language, modules, templates, and the file index.php.

Figure 8: Contents of "administrator" folder

Adminstrator / Cache

This folder holds the cache files for the back-end of the site. When back-end pages are cached, the temporary cache files are stored in this folder.

Administrator / Components

This folder contains all of the components that are available in the back end of the web site. Every menu choice in the back end is provided by one of these components. The table below lists each component and the back-end menu options that it provides.

* = New in version 1.6

Administrator / Help

This folder contains a file called "helpsite-16.xml". This file contains the list of available on-line help sites. Normally, when you press the Help button, you are linked to the on-line help at "docs.joomla.org".

There is also a folder called "en-GB" that contains and HTML file for each help topic. This allows for the option of having the help file on the local server. As shipped, the files in this folder simply redirect the user to the on-line help. But they can be overridden if desired to provide the help files locally.

Administrator / Includes

This folder serves the same purpose as the top-level "includes" folder discussed earlier. This folder holds the files we need to get a back-end session started, as shown in the table below.

Administrator / Language

This is exactly the same as the top-level "language" folder, except that it is for the translation of the back-end of the site. Each component, module, plugin, and template has it's own language files.

Note that, like the front-end language files, we normally have a ".sys.ini" file and a ".ini" file for each extension. As discussed earlier, the ".sys.ini" file typically includes just the name and description of the extension for displaying in a list of extensions. The ".ini" file translates all of the text strings used by the extension.

Administrator / Manifests

This is a new folder for version 1.6 to support the new one-click update feature. It contains three sub-folders: "files", "libraries", and "packages".

The "files" folder contains a file called "joomla.xml" that lists all of the top-level folders and files in a standard Joomla installation. It also contains a list of update servers (URL's) where the program can look for updated versions of these files. This XML file tell the updater which files to update for this application.

The "libraries" folder contains an XML file for each library used in Joomla. These XML files list all of the folders and sub-folders in the library and, again, a URL where the program can check for updates to the library.

The "packages" folder also contains a file called "joomla.xml". This supports a method of updating the Joomla installation as a package instead of set of files. This feature is not implemented for version 1.6 but will be coming in a future version. It will support dependency relationships between extensions. For example, if you request to update or install extension A and that extension requires extensions B and C, these will automatically be included in the installation or update.

We will discuss one-click updates in more detail in Chapter 7.

Administrator / Modules

This folder serves the same purpose for the back end as the top-level "modules" folder serves for the front end. In contains one sub-folder for each back-end module. These are listed in the table below.

Figure 11: Back-End Modules

Each module type has it's own sub-folder. The table below shows which module names correspond with which sub-folder names.

Administrator Templates

This folder holds the templates used to display the back-end pages. Two templates are included with the standard implementation: "bluestork" and "hathor". Bluestork is the default template, Hathor is a template designed especially for accessibility. For example, Hathor is designed to work well with screen readers (used by people with visual impairments) and without using the mouse (for those who might have difficulty using a mouse).

As with the front end, we also include a "system" template that is used for common displays and as a fall-back if the assigned template is missing.

Administrator / index.php

This file is loaded automatically by the web server when your browser points to the administrator folder. It is the entry point for the back end of Joomla. It controls the back-end command cycle in the same way that the top-level "index.php" file controls the front-end command cycle. Note that, because we want the system to load this file, we don't need to have an "index.html" file here.

Files

The following six files are found in the top-level Joomla folder. The table below describes the purpose of each.