Joomla! Discussion Forums

061 Create a troubleshooting procedure to help resolve problems with template Installation (the entire title didn't fit!)

Hello once again, Joomla! GHOP community. I have claimed another task, and hopefully it won't be my last. (yay for rhyming).

My task is to build a 'troubleshooting procedure' for Template Installation errors. I'm still compiling a list of everything that can go wrong with template installation. This is actually partial list I put together last night when I was checking out the task:

Does your Joomla! installation support the template you are trying to install?

Is the XML correct?

Are you trying to install the same template twice?

Are all the required directories writable?
I have a question about this 'issue'. With Joomla! 1.0.x, the templates directory had to be writable to install templates. With Joomla! it doesn't tell you which directories have to be writable. I assume that its still the templates directory. Also, in J! 1.5 you can submit your FTP log in credentials, I assume that when you do that it automatically sets the file permissions properly.

--

I'll be scanning through the Joomla! templates/general questions forums for installation errors. The ones I have listed I only put in because I know that they exist, and I know the (probable) answers.

The Task description says this:


I assume this is because of user permission errors with Joomla! and Apache. I'm am slightly unsure as to what extent I should get into this. Does anyone have any specific 'go this far and then stop' advice they'd like to offer up?

That's all the questions I have for now, I'll begin compiling my current list of issues into a document. In the mean time, anyone who has anything I haven't listed that should be included, please post and I'll add it in. Thankyou!

Chad,

That sounds like a good plan--I definitely recommend looking for some common problems reported in the forums. 

You might also want to ask in the template forum for suggestions.

Yes, you are right about the FTP credentials.

Here I come with revision 1!

I put this document together. I broke one of the templates from the J! 1.5 template contest as much as I could trying to get different errors so I could get solutions. I spent an hour or so scanning the J! 1.5 Template forum for installation errors. I didn't come up with anything more than I listed. In actuality, I've only got like 4 different 'errors' and their solutions on here. If anyone has ever occurred other errors installing templates please post 'em here, and the solution if you have one, and I'll incorporate those in this document.

Here's the zip file. Let me know what you guys think!

That looks great! There is one "Joomla! Joomla!" double in there - otherwise, I felt it was well written, hit important problems, and will be helpful to people.

Would including something on images and favicons help? Maybe even how to correctly write a CSS statement and/or JS statement.

I hope others share issues, too.

Thanks for taking another task - and getting such a great start on it!
Amy

Wow, you got a lot done!!!!

When I was installing templates, I got

until I chmod'ed the right directories.  I think I had to chmod tmp. It is just a "warning". but it wouldn't install until I changed this.

There are also many cases in there where the word after "Joomla!" is capitalized. 

Gosh darn autocorrect!



I'll add that. Sounds like a permissions error for sure.

Okay so I ran through and made sure all the Joomla!'s were correct. I also added a small 3/4 page section at the bottom about changing favicons.

Changes and suggestions on more errors would be awesome!

Version 2

Just a couple picky grammar and sentence fluency things.


Make sure "tmp" is 777 as well.


People will probably know what you mean by "J!", but it makes it seem like you just whipped this out in five minutes.  Do a find and replace to make sure to get all of these.


You are being redundant when you say "common and frequent".  You may also want to consider changing one of the "errors" to a synonym, like "problems" or "issues".


Its means the property of it.  It's means it is.


If you put quotes in quotes, you should change them to single quotes.  For example:




One of your notes has a "!" after it instead of a ":".




Don't capitalize template, and change "owned" to "own".


Could be better said as


Correct me on any of this if you think I am wrong, because I'm not a college professor or anything (despite what Amy thinks...)
I can tell you have put a lot of work into this.  I can really see others using this document.

You could be!

Revision 3

Thanks for the proof read!

Chad - you and I know the truth! 



Change to: The XML file for each template is different, depending on the file names included.



When would it ever not be installed?


Another possibility is that the template zip file is contained within another zip file.

owned --> own


Consider adding:

Why isn't my CSS being used? (base URL statement - is it pointing to the right folder?)



How come my module is not showing?

(The Location not defined in template. How do you do that? Provide an example.)

Doing good!
Amy

I think I got everything. yay for working on Christmas day!

Revision 4

It's, not its.

Ditto

Its, not it's

I must have bad luck with those things...I'll fix 'em!

Updated to revision 5:

Revision 5

Note:
All previous revisions are no longer available. I deleted them off of my FTP for sake of space.

Hi Chad,

Finally got to reading this....

A good start.    What I had in mind originally was a step-by-step procedure that could be followed by almost anyone to diagnose and fix template installation problems.  A bit like those keys you get for identifying insects or plants or whatever.  It asks questions and you branch depending on the answer.  It might be just too difficult to do it that way; I don't know.

Anyway, the most frequent template installation problem seems (to me) to be down to permissions and ownership issues and you certainly captured the former, but you haven't mentioned the latter.

You state that "Templates supported by Joomla! 1.0.x are not supported by Joomla! 1.5".  I could be wrong, but I thought that 1.0.x templates are supported in 1.5 legacy mode.  You then seem to imply that making a template compatible with 1.5 native is just a matter of updating the XML file.  This is not the case as you will also need to update the template index.php file too.

Under "another template is already using directory...." you suggest deleting the existing template.  Naturally you would expect the user to try doing this using the Template Manager, which is fine.  However, I'm not sure, but I think that might fail if the template is not intact for some reason.  For example, if the templateDetails.xml file is missing or something like that (you need to test this).  If that is the case then you can delete the template using FTP to simply delete the entire directory as there are no database entries for templates.

Under "Could not find an XML setup file in the package" I think you may be missing the most common cause of this error, which is again related to permissions/ownership (at least it is with 1.0.x).  The problem arises because the installer must create a subdirectory under /tmp to unpack the zip file into and it may not have the required permissions to do that.  Or it may be able to create the subdirectory but then not be able to create files within it.  Or something like that.  Under 1.0.x the installer would try to unpack the zip but it would not get an error under these circumstances, so it would then proceed to look for the templateDetails.xml file in the /tmp area and fail to find it because actually nothing had been unpacked.  This is the error message you would get.

Another reason for this error that I've come across is that the template is not actually a Joomla! template at all!

This is a tough task, but I think you've made a very good start.  Well done. 

Regards,
Chris.

I kinda thought they were the same thing. But I understand the difference now.

I'm not entirely positive how to tell someone how to fix an ownership problem. From what I understand, it is a setting in Apache? I've never ventured into Apache setting territory before myself, and I've never had this problem, so I don't know the first thing about telling someone how to fix it. Anyone care to offer up some advice here?

--

I'll work on the other ideas you mentioned and come back with something!

or

or

or

or

or

These will change the owning users or groups of files or folders.  I think apache's default user is www-data, and the group is www-data as well.

I was under the impression that 'root' was the administrative user group...but, I'll take your word for it.

Oh, sorry for the misunderstanding.  root is the administrator.  This means that all of the files you save that were created by root, only root can modify.  Apache runs under the user and group www-data.  root has access to files www-data makes, but not the other way around.  If a user named demouser makes a file, only demouser will be able to modify it.  This is where permissions comes in.  Each user has their own group.  The members of the group demouser get special privileges on demouser's files.  Each file is assigned an owning user and an owning group.  Using chmod, you can set the different permissions based on who is a member of what group.  There are shortcuts in the form of 3 digit numbers.  Many times, the owner can read and write to a file, the group can read the file, and everyone else cannot do anything.  What all of this mean is that since apache runs under the user www-data, it only has the permissions that www-data runs under.  If you are demouser, www-data doesn't have access to your files unless you add www-data to the demouser group.  You do this with
.

Sorry if this makes no sense at all; I will explain it better if you need me to.

Okay! So, I've put some more time into this.

Chris, I thought about your thoughts on asking questions and then having answers, but I had a difficult time trying to wrap my head about how to go about that. So, I've sort of stuck to my original 'error. cause. solution' idea. But, I did make some changes that I hope you'll like and approve of. If you really want it to be a questionnaire-answer thing, I'll work on trying to get that type of format.

Max, thanks for your input on the file ownership stuff. It really helped me put this together. Hopefully I've got this reading the right way. If not, I'll gladly accept some more verbage on that, as the whole apache ownership thing is something that I don't quite 'get' myself. I understand the concept, but I guess some day I'll just have to do it, so I understand how it works.

So, here is the download.Let me know what ya'll think.

Apache uses unix permissions.  chown is the unix command to change the owner and group of a file.  If there are user permission errors, the most likely cause is that root owns the Joomla! folder.  To change this, find the folder that Joomla! is installed to, and run this command:

where joomlaid is the name of the Joomla! installation directory..
Make sure chmod and chown aren't capitalized as well, because they won't work if they are capitalized.

Good luck! 

P.S.-Where did you find that "?" picture on the "notes"?

I made that in Photoshop. The source PSD is in the zip.

well done guys. Could some one explain why we keep getting the message "can't find installation file" I have pack my files exactly as tutorial said in this order:
c3_trial/c3_trial/index.php
c3_trial/c3_trial/template_thumbnail.png
c3_trial/c3_trial/templateDetails.xml
c3_triall/c3_trial/css/main.css
and I have zipped it changed the permission to 777. After I tried install it. I keep getting those messages.
"can't find installation xml file.."
"can't find index.php file.."
"can't find...."
Well the error message sort of change everytime I tried to install the same zip file!
What's more I have a couple of zipped template file which I've download somewhereelse. and it installs fine.
But after I unzipped it just to have a look what's in there and leave it untouched and recompress them back to old same zip file again. it would install properly anymore. and all the same error message will come out.
Some one help please!!

Binwangzz, could you please send me the file so I can look at it? Email it to me: drmmr763 at gmail dot com

Binwanzz -
Sorry, but this is not the right place to ask these questions. This is the forum for the Google's Highly Open Participation Contest. Each contestant has a thread for the task they are working on. Community members are invited to comment on the correctness and appropriateness of the work, but we do not want support questions here.

I see that Chris Davenport suggested you get a copy of this document for assistance in this thread. Both MMMedia and tydust responded, as well. Since each are experts in templating, returning to that thread and interacting with them will be most fruitful.

Thanks for understanding.

Amy

I have send you a emil with my zip file attached to it. thank you very much for looking indeed.

well, sorry for been the wrong place. thanks for reply my post. I will just keep knocking on other doors! : )

I made the change Max specified. Here is the latest file:

*Note: I've again deleted all previous revisions, so only this link will work. Also, on the other documents I wrote, I left only the final accepted versions. All others have been deleted to conserve my available space.

Revison 8

Does anyone have any further recommendations for this document?

Chad -

First of all, this is nicely done.

On 3.2, where you are showing people where to navigate to get rid of the template that didn't install correctly, you tell them to FTP and go to the joomlaroot/templates/ folder. Then, you talk about deleting the "bad" template subfolder. But, I worry they might get rid of highlighted joomlaroot/templates folder. Consider adding joomlaroot/templates/badtemplate/ to the description.

On 6 - make certain to include the basurl. In fact, one of the reason the CSS or images are not used could be because baseurl is not there. (This would be true when they installed in a folder within the base website, like http://example.com/joomla. In that case, baseurl will be joomla.)



Thanks much!
Amy

Thanks for the suggestions Amy!

Revision 9