Guide: How to Copy a Joomla 3 Template (If You've Already Started Doing It Wrong)

Copying a template or extension is no longer as simple as copying a folder and making some changes. Here's what to do, if that's news to you.

Copying a template or extension is no longer as simple as copying a folder and making some changes. Here's what to do, if that's news to you.Once upon a time, it was possible to simply copy a template folder to a new name, and start using your copied template, tweaking as you go. If you read that, and allow yourself to pine after a day when Joomla loaded and ran whatever code someone dropped into a folder, then you could stand to develop a much healthier sense of paranoia, but I digress...

Copying a default Joomla template has become gradually more involved, over the years. If you want to use Protostar as the basis for a new template, you can follow these steps to get it done cleanly and correctly. Afterward, you'll install the template via Extension Manager - on as many sites as you want.

Be aware, if you're starting with the Protostar template, as this tutorial assumes, the new template is automatically protected by the GNU GPL, unless you modify it almost completely. That's no minor matter - there are legal grounds for that claim, in the form of rulings - the GNU GPL isn't an airy-fairy fantasy. There are also valid claims for cases when you start with something simple as an educational tool, so long as little-or-nothing of the original survives, of course - so you're safe learning as much as you can, in the process.

Since this procedure leads to you installing something into Joomla at the end, I also need to say, I'm not responsible for any due diligence failures on your part. Caveats covered, here's how it's done!


The first thing to know is that this official docs.Joomla.org link, has two easier methods which work on modern versions of Joomla 3. The procedure below is for those who have already begun the work, expecting they'd be able to just load a modified folder as a valid template. Via the latter of the two procedures explained at the aforementioned link, you may even be able to do just that, so it's worth a read.

However, many of you may have already gotten started; and the rest of you may simply want a template you can install. For that result, keep reading. 

For the sake of the example, let's say you copied the protostar folder, and named it pseudostar.

At a glance, the steps are these:

  1. Edit the templateDetails.xml file.
  2. Edit and rename the files in languages/en-GB.
  3. Edit a few other files, to make sure everything continues working correctly.
  4. Zip the result into a file, including the folder.
  5. Delete the pseudostar folder on the site.
    (Note: NOT the one you did the work in - keep it at least until you verify everything's working ).
    This step is necessary to make room for the next step.
  6. Install your new template.

Here is a little more detail. First, there's an instruction I'll repeat over and over, below - let's expand on it once, first.

You need to do several text find-replaces. All your find-replaces must be case-sensitive. This means both:

  1. you need to type things in the right case (as shown below);
  2. and that you need to find a checkbox, in the Find-Replace dialog, for specifying case-sensitive option.

That goes for all find-replace steps below - of which I'll remind you.

Here is the procedure!

1. Copy your source template (e.g. protostar) by copying the entire templates/protostar folder, and all its contents and subfolders. Name the copy, an all-lowercase version of whatever you'd like the final name to be. For example purposes, we'll go with pseudostar.

2. Open templateDetails.xml.

3. Find-replace all lowercase instances of protostar with pseudostar (be sure to look for a "case-sensitive" option!)

4. Find-replace all uppercase instances of PROTOSTAR with PSEUDOSTAR (same "case-sensitive" option!)

5. Save templateDetails.xml. Before leaving this file, consider (carefully) changing some fields at the top.

6. Do steps 7 through 10 below for both of the files in languages/en-GB/:

7. Open the file and repeat the find-replaces as explained in steps 3 & 4 above.

8. You might want to update one or two other fields here while you're at it. Mind the quotes, keep it short, and don't add any quote symbols (") yourself!

9. Don't forget to save.

10. Rename the filenames of both language files, so as to replace protostar with pseudostar in the filenames.

11. Open index.php

12. Find-Replace all uppercase (remember the case-sensitive option!) PROTOSTAR with PSEUDOSTAR.

13. Find-Replace all lowercase (ahem) protostar with pseudostar.

14. Save.

15. There are a few other files with appearances, where you must replace one or the other (upper vs lower case) or both. Rinse and repeat until you get them all, and be sure to always find-replace in a case-sensitive manner via both your typing, and the find-replace option. In addition to the files named in other steps, you're editing: error.php, component.php, html/pagination.php, html/modules.php, and js/template.js. (In some of these you'll only change a comment, but let's be thorough.)

16. Create a zipfile -- if you aren't familiar with how to do this, back out of that folder one level and right click it; windows has "Create Archive" or somesuch nowadays, I believe. This is the only place where the naming doesn't matter, but it should probably be named so you'll never forget an important detail about it. For example, I like the filename pseudostar-j3-template.zip.

17. Delete (or move to elsewhere) the pseudostar subfolder from your site templates folder. This is necessary to make room for the installer system.

18. Install your new template via Extension Manager!