A. Common Problems and Solutions

If you follow the instructions in this book, you will avoid most common problems. However, sometimes things go wrong. Here are the most common issues we see and how to solve them.

Lost Administrator Password

If a normal user forgets his or her password, it can be recovered with the “Forgot your password?” link that is typically shown in the Login module on a site. The exact wording may depend on the site and any modifications that may have been done. However, if you are a super administrator, you can’t do this for security reasons. Another common situation is when for some reason the person who had super administration access is no longer available either to do the super administration tasks or to promote someone else to be a super administrator. If someone is no longer associated with a site, it is very important that his or her access be restricted or removed entirely. If you have this situation, once you have gained access to the administrator you must make sure to block access for the former super administrator. To block a super administrator, you must edit that user and change his or her user group to any other group, although Registered is best. After saving, you will be able to block the user in the User Manager, as shown in Figure A.1.

Figure A.1. Blocking a Registered user in the Joomla! administrator back end

Joomla! 1.6 and Later

Since the release of Joomla! 1.6, the simplest way to recover your password is to take advantage of root user status. Log in to your hosting account and, using the File Manager, find the file configuration.php located in the directory of your Joomla! site. Edit this file and scroll to the bottom. Before the final bracket (}) add this line, replacing myname with the name of a registered user: public $root_user='myname';.

This will give that user super user rights. You should immediately log in to your site, change the password for the user, and make any other necessary changes (such as resetting a password for the administrator or changing another account to have super user privileges). Then immediately delete the line from the configuration.php file and save it in the original form. If you forget to do this and log in to your site administrator as a super user, you will get a reminder to do so.

Some people worry that this feature is a security issue. In fact, if a user has the ability to change your configuration.php file, he or she already has the ability to destroy your site by changing the database and other crucial information. Further, the user must still know his or her password to log in to the site. So this procedure is not actually dangerous as long as you do not leave anyone as a super administrator who should not have such permissions.

Joomla! 1.5 and Earlier

To access your database, you will need to log in to your hosting account’s Cpanel or the hosting panel your host provides. If you are using Cpanel, find the icon for phpMyAdmin or use the Find in the top-left corner of Cpanel to search for the icon. Figure A.2 shows an example, but as always, your host may use a different hosting panel, and the screen may not look exactly the same.

Figure A.2. phpMyAdmin icon in Cpanel

After clicking the icon, you will see the administrative interface for your databases, as shown in Figure A.3. In many cases you will have just one, which is the one for your Joomla! installation. However, if you have several and are not sure which is the Joomla! one, go back to your control panel and, using the File Manager (see Chapter 3), open the configuration.php file. At about line 18 you will see a line that starts with var $db=. The text (not including the quotes) to the right of the equal sign tells you the database name.

Figure A.3. Administration screen for phpMyAdmin

Click the name of your database. The top of your database will look as shown in Figure A.4.

Figure A.4. Viewing the tables in your Joomla! database

Each line represents a database table. Find the jos_users table, which will be the second-to-last one on the list, because the list is arranged alphanumerically, unless you have installed extensions that add tables that fall alphanumerically after jos_users. Click the first button in the Action column, which is the Browse action. This will show you a group of rows and columns, as in Figure A.5.

Figure A.5. The data inside the jos_users database table

Some of the important fields shown here include username, password, usertype, and gid. In this case there are two super administrators, which we can tell by both the usertype text and the gid entry of 25. The gid is what actually controls this; the text is simply for display in the User Manager. The passwords do not look anything like a normal password. This is because they are encrypted as a security precaution. To replace a password, you need a hashed version of a known word. Here’s an example:

d2064d358136996bd22421584a7cb33e:trd7TvKHx6dMeoMmBVxYmg0vuXEA4199

This is the hash for the word secret. You can copy this string from http://docs.joomla.org/How_do_you_recover_your_admin_password since typing it exactly is likely to be hard.

To edit the record, click the pencil icon on the left of the screen that is in the Administrator row. The screen will appear as in Figure A.6. Simply change the text in either the email or password field. When you are ready, click the Go button on the bottom right of the screen.

Figure A.6. Editing the database record for the administrator in the jos_users table of the database

Once the record is saved, you can log in as that user using the password secret or whatever word you chose.

At this point it is imperative that you change the password to a secure password if you used a common hash like that given earlier for changing a password in the database.

File Permissions and Ownership Problems

If you followed the instructions for installation in Chapter 3, you should not have problems with your files. However, you may experience file problems over time, perhaps because you have FTPed files from an external client and uploaded some using the File Manager. Or perhaps your server environment has changed. Some of the symptoms of this problem are an inability to save changes in a file that you edit and the inability to install extensions.

Each file on your site has an owner. Usually that owner is either your account or Apache. Joomla! is designed to work with one or the other, but not both at the same time. It is very important that you maintain consistency in your file ownership. For example, if you use the FTP layer in Joomla! for installing some extensions, you should use it for all extensions. You must also make sure to use the same account consistently so that your files are not owned by different users. If you end up with mixed ownership, most likely you will have to submit a support ticket to your host, who will then need to run a chown utility (this is a Linux utility that all Linux-based hosting should have available).

Unfortunately, it can be difficult to determine what account owns your files. For example, the standard Cpanel File Manager does not show this. However, some FTP clients do.

File permissions are what different groups of users are allowed to do with your files and are usually represented by a three-digit number. Your Joomla! folders should be set to 755, and your files should be set to 644. At times you may receive advice to change file ownership to 777, but you should never do this if you are in a shared hosting environment (which most sites are) because it will make your files susceptible to attack from other sites on the same server. To change the permissions on a folder or file, select the box next to its name, and then click the Permissions icon in the top menu, as shown in Figure A.7. The configurations for 755 and 644 are shown in Figures A.8 and A.9.

Figure A.7. Change Permissions icon in the Cpanel File Manager

Figure A.8. Changing permissions for a folder to 755

Figure A.9. Changing permissions for a file to 644

Be sure to remember to click Change Permissions to complete the process.

Editor Background Has a Color or Looks Strange

If you install a template with a dark-colored background, the editor is sometimes difficult to use because it attempts to use the template styles to make the content in the editor look more like that in your actual template. If this happens to you, the easiest solution is to create an editor.css file and add it to your template css folder for the front-end template in the same way custom.css was added in the sample sites in Chapter 8. In the parameters of your editor (such as the default WYSIWYG editor that comes installed in Joomla! or if you are using JCE as your editor) you can then specify that you are using an editor.css file. Each editor has a specific place for this directive, so you may have to look in the documentation of the editor or review the parameter options in the editor you are using. You can make the editor.css file as simple or as complex as you want, but be sure to use a light color for the background. For example, the following will produce a white background:

body { background: #ffffff; }

Some people make a copy of their template.css file or the CSS file that contains most of the CSS styling of elements in their template and add this line to the top of the file, replacing any body styling that may be present with the background directive of #ffffff (white).

Template Disappears When Turning SEF URLs On

In some server environments, turning on SEF URLs, especially without using the htaccess option, causes all the pages except your home page to lose the template. In this case you will just see black text and blue links on a white background. The solution to this problem is often to use the $livesite variable. To do this, access your file server by using the File Manager via Cpanel as described in Chapter 3. Find the file configuration.php in the directory in which your site is installed. Open that file to edit it, and find the following line at about line 21:

var $live_site = '';

Inside the quotation marks put the URL for your site (for example http://mydomain.com). Make sure to put http:// at the beginning and do not put a slash at the end. If your site uses www as part of the domain name or redirects all non-www traffic to www, you will need to include www in the URL (for example http://www.mydomain.com).

Site Displays Differently or Incorrectly in a Certain Browser

Cross-browser compatibility is one of the most difficult issues in Web design. Unfortunately, there are many browsers, and not all of them interpret the same code in the same way. This is why you will often see ie.css or ie6.css as part of your template. Those files make specific adjustments to the CSS styles for certain browsers. This is not a Joomla! issue but a Web standards issue.

When you have a problem with a particular browser, try to identify the CSS that is causing the issue. There are some useful tools for this, such as browser add-ons like Firebug for Firefox and Developer Tools in Internet Explorer 8. You can also find a great deal of advice and reference material about specific issues and browsers on the Web. Appendix B contains some useful links for this.

Problem Assets Table

Since Joomla! 1.6 there has been a table in the database called the assets table. Some users who have imported their data from Joomla! 1.5 or earlier have problems when the assets table is created incorrectly during the import process. For small sites this can often be solved by opening and saving the individual articles or by moving all of the articles in a category to a new category and then moving them back. If this does not resolve the problem, you may need a more complex solution. Please consult http://docs.joomla.org and http://officialjoomlabook.com for more detailed information.

Problems Updating

On some hosts you may have problems using the Joomla! Update button to update your site when there is a new release. Before assuming that an update has failed, you should always make sure to check the Database tab to see if there are any fixes that need to be applied (click the Fix button if there are any listed). Also you should clear your browser cache. Each browser does this somewhat differently, but in general you will find the option to do this in a browser menu called something like Tools or Privacy Settings. Since browsers sometimes change the location of this option, we suggest you read the instructions for your preferred browser. If the update still has not completed, you need to use alternative update methods. There are two main ones. As always, back up your site before updating.

• Use the extension installer: Go to www.joomla.org/download.html. Download a copy of the update package, which will be a zip file. Go to the Install tab of the Extension Manager. Install the new version of Joomla! as if it were an extension (browse for the zip file on your computer and then click Upload and Install).

• Use your host’s File Manager: Download the update package from www.joomla.org/download.html. Use either FTP or your host’s File Manager to upload the zipped file to the root of your Joomla! site. Unzip the update file, making sure to overwrite existing files.

When complete, refresh your site, clearing the browser cache if necessary, and check for any database issues that may require you to press the Fix button.

Excellent help on upgrading is available at http://forum.joomla.org, and documentation for some more difficult situations can be found at http://docs.joomla.org.