Themes
From Achievo/ATK Wiki
|
ATK Howto: Themes
|
Notice
This howto is unfinished as there is going to be a new theme for ATK/Achievo which I will implement and it is likely that I will have to make adjustments to themeing an ATK application and that I will learn more about the process myself by doing this. So I am waiting until after this new theme before continuing with this HOWTO.
About this document
This document was created by Boy Baukema. It's intended audience is twofold: designers and developers of ATK applications. Its purpose is to inform and instruct both on how to effectively and efficiently create and alter themes and theming in ATK. And its format is that of a HOWTO and it will therefor attempt to be as concise as possible without omitting anything that the reader could not deduce him-/herself.
What exactly are themes?
Themes, for purposes of this document, are defined as the structure and presentation layers of data. This includes, but is not limited to, templates, pictures and stylesheets. Everything that makes raw data look good but doesn't add any 'real' value to the data.
The analogy which fits best is that of a normal webpage. The presentation layer (CSS stylesheets, icons, decorative images and backgrounds) and the structure layer(HTML formatting like the < b > tag) being the theme, and the contents (what's between the < p > tag) being the actual data.
In ATK applications this will mean the way your application looks, not how it behaves. You can check out which theme you currently have by seaching for $config_theme in your config.inc.php, this is normally set to the Outlook theme.
To understand how themes are layed out, lets look a little closer at the Outlook theme. Go to the ATK directory of your application then look in the themes directory. Here you will find all available themes and you will also find the default theme here (something we will come back to). Now go to the outlook directory. A file listing should look as follows:
. .. images/ styles/ templates/ themedef.inc icons/
Note that the only file in the directory is the themedef.inc file.
This is where all theme settings for the Outlook theme are set.
Other than that, there are a few self-explanatory directories
(such as images, which is the directory where all the images used
in that theme are stored).
Now lets take a closer look at the themedefinition (the themedef.inc file). In it you will find the following:
$theme["basetheme"] = "outlook";
The 'basetheme' is the theme that this theme is derived from. Everything not specifically defined in this theme, is retrieved from the base theme. If no base theme is set, the 'default' theme is used as base.
For those of you who wonder at what exactly 'templates' are, I suggest you open the templates directory and check out one of the available templates. You will see a lot of HTML and a few strange {} thingees. These thingees are Smarty tags and the templates are Smarty templates. Smarty templating in ATK basically means that data is seperated from structure and this is left to themes. So you don't have to go browsing through ATK functions if you want to change the way your application is laid out but only have to change the template. You can find more info about Smarty templating on the official Smarty website.
For a detailed explanation of which template has what purpose, see the ATK Theme Templates list.
And that is basically it.
This one file contains everything about the Outlook theme. If you want to make changes to the existing themes you should now know where to look. The next chapter will focus on making your own theme.
How do I make them?
Okay, let's face it, the default outlook theme looks nice, but it's not the pinnacle of human designing, you might feel you could do better. Or, you may be making an application for your company and you want to use the company colors. Now you could join the dark side and just hack the Outlook theme, or any other theme and use that. But the best thing to do will always be to create your own theme.
To create your own theme you will need to know a bit more about theming in ATK applications.
First, something about the mysterious inner workings of the themecompiler.
So the ATKThemeCompiler was born. What it does is get all the themes and their elements and info and put it in the atktempdir ($config_atktempdir) in the themes directory for every theme. Meaning that, unless you switch themes or manually remove the themecache, it will continue using that.
If you are having problems with this particulair feature (and during the development of themes in general) I would advise you to either remove the themecache or just turn on $config_force_theme_recompile by setting it to true. This will force the themecompiler to recompile.
The way the themecompiler looks for themes and theme-elements is that it looks for 2 directories in 3 paths. It looks for the a directory with the name of the current theme (from now on refered to as 'CurrentTheme') from $config_defaulttheme and a 'default' directory. The 'CurrentTheme' directory is where all your theme elements should reside and the 'default' directory is where all the default theme elemements belong. In general, you will not need the default theme, unless you plan on making several themes. Theme elements in the 'CurrentTheme' directory will always be used if they exist, however if they do not, then elements from the 'default' directory will take their place.
The ATKThemeCompiler also has a fallback on where to look for theme items. First it looks in the root directory of your application in the 'themes' directory, then it looks in all the modules and their 'themes' directory and finally it looks in the ATK directory, in the 'themes' directory. This means that theme elements mentioned in the 'CurrentTheme' theme in a module will take precedence over another element mentioned in the ATK 'CurrentTheme' directory.
TODOs:
- Various supported elements
- Templating (by Ivo)
How do I change/add behaviour?
- Using themeitems
- atkTheme support for elements
- Tweaking the themecompiler
Example of creating a new ATK theme
- Tekno theme
Troubleshooting
HELP! I keep getting php errors with mkdir() from ATKThemeCompiler! How do I fix it?
This can occur in versions of ATK between 5.0 and 5.03, otherwise your application should give a nice friendly warning, something like: "Can not write to temporary directory: ./atktmp). Ensure that it exists and is writable for the webserver." This occurs because the method responsible for storing cached theme definitions is recursive, so when it does not have access to the directory it will keep on looping until the PHP engine stops it. This was fixed in ATK5.03 for the more user friendly message.
If you are having this problem and don't know how to fix it, just follow the following checklist:
- Check the config files for $config_atktempdir, is it set? It's unlikely that this is not so but if not, set it, preferably to "atktmp" and continue with the checklist.
- Does the directory exist in the root of the application? Meaning that if the atktemp is 'atktmp' check that atktmp/ is actually present in the root of your application (where the atk/ directory and index.php reside). If not, create it and continue with the checklist.
- Is the directory owned by the webserver user or at least writable by it? In linux this would mean that the command ls -la (in the root of the application) would yield:
drwxrwxrwx user user atktmp
or:
drwxr-xr-x www www atktmp
With www being the webservers username and group (the most common usernames are www, nobody and apache). It's always safest to make the directory owned by the webserver user (as root: 'chown -R www atktmp/' if www is your Apache username), but often easier to just make the directory writable for all users (as root: 'chmod -R a+w atktmp/'). But I leave this choice up to you.
I don't see a themedef.inc, only a layout.inc
You are probably using an older version of ATK, probably ATK4, or you are trying to create a theme for Achievo 1.x. For the former option I suggest you upgrade your ATK. As for the latter... well unfortunately the ATK5 backend won't be fully integrated into Achievo until version 2.0 (current development version). So I fear this howto won't be of much use to you as theming has changed so dramatically in ATK5 that the old layout.inc style has become obsolete and will not be discussed in this HOWTO.
I added/changed the name of a theme element (template/stylesheet/icon/etc) but I don't see the change?! What's wrong?
The themecompiler caches all theme settings for performance reasons. This means that when you make changes to a themedefinition, they won't actually be used unless the cache is removed and the themecompiler is forced to recompile. It is always advisable to turn on the $config_force_theme_recompile (ATK>=5.03)config option when working on themes, this will reduce performance but also ensure that the themecompiler will recompile the themecache for every reload, thus always giving you the current and correct themedefinitons. Or you could also just remove the themecache, just use 'rm -rf atktmp/themes' in your application root (with atktmp being the name of the temporary directory). You must have the rights to do this though (only root and the webserver user should have this right).
What you say? LACKING? Why you ingratefull...! :-) But really, feel free to contact me about any and all issues concerning this HOWTO and themes in ATK, just send an email to the ATK mailinglist atk@achievo.org.
Appendix A: Default ATK visual elements
This appendix will contain ever single visual element in ATK that you can customise.
Appendix B: Default ATK templates and their Smarty tags
Appendix C: Premade Themes
The following page lists the themes that come with ATK:
