Joomla Jumpstart

Sometimes finding documentation for Joomla features is like searching in a darkened home for that illusive flashlight. Even if you find what you're looking for, it may be no help at all (are these batteries dead?). Likewise, documentation on Joomla is often difficult to locate and when you discover something in the area where you're looking, the thing you need is missing. There is a well-lit, often comfortable place where you can find anything you're searching for -- the Joomla source code. Using a powerful text editor like jEdit, you can often quickly and easily locate the information that you need.

 

 

---

Joomla is open source, so provided that you understand the basics of PHP, you can often locate the code to reveal the information you seek. For example, I was recently writing an Administrator module (i.e. Missing Metadata module) which needs to have the Position set to cpanel in order for the module to appear on the Control Panel of the Administrator interface. At first, I simply included instructions that told the user how to properly configure the module, but I wondered if there was a better way. Could the position be specified in the installer XML file?

I tried searching on the web, but I didn't find any information relating to it. In the Joomla forums, I found a suggestion for this feature, but no indication whether it had been implemented or not. It was time to look at the Joomla code itself to discover the answer. To find information in the code requires a little bit of detective work. You have to guess what text in the code file will be unique enough to find that needle in a haystack.

 

Beginning the Search

For my searches, I use the powerful and free text editor jEdit. One great thing about jEdit is its ability to search sets of files in directories and subdirectories. In this case, I need to search the source code in the Joomla directory. By limiting my search to only PHP files (which jEdit lets me do), I can dramatically decrease the search time by ignoring all of the HTML, CSS, and other files in the Joomla installation.

After bringing up jEdit, I hit Ctrl-F to show the Find window. Since I know the default position of a module is set to "left," I'm going to start by searching for that word. I type in my search term, check the Ignore Case option, set the filter to only search in PHP files (with *.php), and select the Joomla directory. When all my options are ready (see below), I click the Find button.

 

The Hypersearch window will be displayed and all of the specified files will be searched. Once the search is complete, entries for each file that matches the search criteria will be displayed in the HyperSearch window. Each entry will show the located file and the search term as it appears in the surrounding code to provide context (see below). Clicking on a file in the HyperSearch window will open it in the text editor.

You can see by the large number of results returned by the query, the simple term left is not exact enough. The point of the search is to narrow down the list of files that need to be examined manually. Since this search term generates so many hits, it's time to think of something more specific.

 

Narrowing the Search

Whenever you attempt a code search, try to think of a word or words that would only be found at a single place in the code. Text that is displayed on the screen is often an excellent place to start because you can make the search case-sensitive. For example, if you wanted to examine the code for the pane that shows the logged in users on the Administrator interface, searching for the tile of the column "Last Activity" would result in only two files: the changelog.php file and (bingo!) the default template for the mod_logged module. With that information, you can look at the mod_logged code and find the information you want.

In our search for the code that parses the module installer, there won't be much text associated with the installation. Therefore, it can be a good idea to generate an error. Because most text explanations of error codes are specific to the problem, the text itself will likely be located near the code doing the work. In my case, I simply try to install a module that already exists. I get the following error:

Another module is already using directory

If I do a Find on that text, I get a single file (module.php) returned in the HyperSearch window:

Finding the Information

After opening the module.php file located in my search, I locate the function install(). After processing a number of elements, the function does the following:

$row->title = $this->get('name');
$row->ordering = $row->getNextOrder( "position='left'" );
$row->position = 'left';
$row->showtitle = 1;
$row->iscore = 0;

I bolded the position code. Well, it looks like the "left" position is hard-coded into the installation. To be a little more certain, I perform a search for the code "->position" because anything setting the position field of the module record may be of interest. My search reveals 11 files and only the file that has already been examined (module.php) is located in the \installer directory.

My search was done. Had I performed a long search through the documentation, it is likely I wouldn't have found a conclusive answer -- if I found any answer at all. By looking at the code that was actually executing for the installation, I could see that no parameter was being read from the XML installer file and therefore, I had the answer to my question.