Community Documentation

v3 Knowledgebase

Create a new theme

The phpfox script is very generous about new themes and styles, every theme and style has a parent, so if in any section the style or the theme is missing it will take on the parent's, so you may be only starting with a theme and the site will still work.

First we need to explain a little what is what:
- A theme has a template and one or more styles.
- A style is a set of images and css.
- A template is html code.

Before we begin we need to make sure we will be working with fresh files, so make sure you have the dev file as suggested here, of special importance are the constants "PHPFOX_NO_TEMPLATE_CACHE" and "PHPFOX_NO_CSS_CACHE" but the debug ones are also very handy.

Now lets go to the AdminCP -> Extensions -> Themes -> Create New Theme and fill the fields there shown. The only really important fields are the name and the folder, but it doesnt hurt to fill in the others too, for example:
create theme.png

Now lets create a style for this theme so please go to AdminCP -> Extensions -> Themes -> Manage Themes, if you click the number zero in the styles column for your new theme it will offer you the link to create a new theme, you can also click on the icon to the left of the new theme and then on Create Style.

Make sure the Parent Theme is the theme you just created ("myTheme" in our example) and that the Parent Style is the phpfox default one.
Now enter your information in the fields, for the logo one this will depend on the file name for the logo, each style can have a different logo so this is good to remember later. For now lets use logo.png but you can use a different one as long as it matches the file name.

At this point we have a theme and a style but only in the database, and we want to use files so we can download and edit in our desktop program of choice, so lets export this theme by going to AdminCP -> Extensions -> Theme -> Manage Themes. Click on the icon to the left of your new theme and then on Export Theme, it will list all of this theme's styles (which right now is just one) so please make sure you click on the one style and then on Download.

The resulting archive will contain the folders and xml files needed to get started, in fact you get from here a /upload/ folder, you need now to upload the contents of that folder (not the /upload/ folder itself) to your site's theme folder (/public_html/theme/ for example).

Now lets create the folder for the templates, this is the folder /theme/frontend/mytheme/template/. Now copy the file /theme/frontend/default/template/template.html.php into /theme/frontend/mytheme/template/

Lets edit this file a little bit, something that beyond doubt tells us that we are looking at our theme, for example I replaced the title from this:

to this:
<title>THIS IS THE NEW TEMPLATE {title}</title>

This will only affect the frontend (not the adminCP) but is still good enough to figure out we're tweaking the right file.

Now lets activate this theme by going to the AdminCP Theme Manager, you need to disable the default theme and turn your style as default, otherwise the script wont take your new template.
Like this:
change style1.png

If you refresh your browser (on the front end, not the admincp) you will see the title changed already. You can now continue editing the general layout of the site by editing the template.html.php file we have just copied Smile

Now, every module has a set of template files, for example, go to the folder /module/group/template/ and you will see a folder called "default" this is directly related to the "default" theme, and that is how the script can display something even if the currently enabled theme doesn't implement that section.
If you want to create a custom layout for each module you would need to go to each module's template folder and create a new folder named "mytheme" and copy the files from the "default" one in that location, for example:

Now the CSS, you already know how you can change the layout, but what about the looks?
It is actually very easy. The short version is to copy one file from the css folder in the default theme (/theme/frontend/default/style/default/css/) in your own theme (/theme/frontend/mytheme/style/style1/css/) and edit that file as you need, for example the layout.css file, and only add new rules to match your new items or to override other rules. Again, if the script can't find a specific file it will try the parent folder, so no worries if you didn't copy all of the files.
By copying only one file you are making sure that new versions that overwrite default css files will be updated without a problem (because you didn't edit those files), and those CSS changes (in the upgrade) will match new elements in the template files, then again if you're not using the default template the new rules wont affect anything

How do you know in which css file is the rule that you want to edit?
There are several tools for this, I prefer Firefox + Firebug + A little setting: if you go to AdminCP -> Settings -> System Settings -> Manage Settings => Module Core, and disable "Cache JavaScript & CSS" you will get one request for each file from the browser, so you can Inspect elements with Firebug and it will show you which file has each of the CSS rules that affect that element:

One important thing to remember is that if you edit a template or css file from the AdminCP it will create a copy in the database (the original file with the change will be stored in the database) and the script will cache that copy and use it on the site instead of the original flat file, so if you are making changes to the original file and you are sure no caches are enabled but the site still not picking up the changes it is most likely because the file was changed at some point from the AdminCP.