I'm 100% sure that you will find the new code much more easy to be used and much more flexible compared to before as soon as you understand how it works. It may require some time (hours, not years!), but it's worth every second of it.
Let me try to explain the reason of some of the new changes, so you all may understand the final goal and (maybe) how to easily use these new functions in your own code. I'll try to be as precise and schematic as possible.
Default Template Folder
I have implemented the default template folder to simplify life to stylers. If you are familiar on how phpBB 3 styles system works, you can setup inheritance for some styles, avoiding you to restyle every single TPL. This has been added only recently to phpBB 3, while Icy Phoenix has this feature from years...
Default template folder contains standard version for all template files. If you want to create a new template, you can just focus on header and footer for example and then you can avoid restyling everything, because if the system doesn't find a specific template file in your template folder, it looks for it in default folder. So inheritance is automatic. Moreover, I have extended the way templates work by adding the possibility to include templates from plugins folders, and inheritance is much more flexible.
Let me make an example.
You have on your site 3 styles: Icy Phoenix, Lightning Phoenix and ProSilver IP.
If you have a closer look at templates folder, you will have 4 styles folder: default, icy_phoenix, lightning_phoenix and prosilver_ip.
For each style template layout is very similar of course, but those styles may look very different each other.
Icy Phoenix uses only default template files, to customize the look only CSS and images are different, that is why icy_phoenix folder contains style specific CSS, CFG and images.
Lightning Phoenix uses mostly default template files, but it has header and footer coded differently, in fact if you have a look at lightning_phoenix folder you will notice that you don't have olny CFG, CSS and images, but also header and footer template files... all other files are automatically included from default folder. Suppose you want to change how viewtopic looks only for Lightning Phoenix, all you have to do is duplicate the original viewtopic_body.tpl from default folder into lightning_phoenix folder and edit as you like... that file will be included then from lightning_phoenix folder instead of default foder. All is automatic, no need to code IF THEN or other kind of exceptions.
ProSilver IP uses different HTML structures and code on many files, this is why prosilver_ip folder has many template files, but it doesn't contain all, because some template files are still automatically inherited from default folder and styled using proper CSS properties. Plus CFG file is used to customize other specific style features.
I hope it is everything clear about the purpose of this new template structure.
Page Header And Page Footer
Old phpBB code was awful about header and footer inclusions... ok, many of you were used to it, but this doesn't mean we are forced to that "jail" forever. Let me make an example.
OLD CODE
...
SOME PHP CODE / FUNCTIONS
$i = true;
$j = false;
include($phpbb_root_path . 'includes/page_header.php');
OTHER CODE YOU MAY NEED TO BE RENDERED, TEMPLATES VAR AND SO ON
include($phpbb_root_path . 'includes/page_footer.php');
AND FINALLY THE FUNCTION TO RENDER THE PAGE
This old code was very confusing, because you didn't know at which point you may inject vars to template, so if you wanted to add a new JavaScript to header, but you could check the condition only after you included the header, you couldn't include it anymore by using existing vars, because the header vars were already parsed... also because in old page_header.php header vars where assigned to overall_header.tpl and there was no way to modify them anymore.
So the old code was very limiting, because you could inject header vars only before including page_header.php, and then you lost the control on those vars forever (unless you are so mad to play with preg_replace and ob_get_contents when page is served!).
My goal was to avoid all that stuff and to get back full control on every template var until the whole template vars set has been parsed. This is much more flexible, because this means that until
full_page_generation() is called (and now is 99% of times called at end of file) you can still inject and act on EVERY variable is on the page... being it in header, body, footer or any other nested template file you may include. Moreover header and footer template files are now included through TPL files and not via PHP anymore... this means that those vars are global template vars like all the others, not specific TPL vars handle.
In conclusion, the new template parsing method is much more simple and effective... you just need to call properly
full_page_generation() function at the end of the page and you are set... now you can play with all vars everywhere, and you are not constrained to write your code only before page_header.php inclusion. You will soon discover the power of the new code as soon as you try to code on your own.
CFG File For Styles
These kind of files are used by templates to define some style specific features, so we don't need to add specific functions to all files if not used. I have tried to explain briefly in the previous section why this file is needed, but let's try to go a bith further.
Most of templates may be changed by simply re-design tables and blocks. Original phpBB template code (even phpBB 3) let me say it's quite rigid, there is no flexibility on styling tables and blocks... you have to change HTML markup in at least 50%/60% of the cases... unless you are a CSS master.
In Icy Phoenix I added long time ago (even in version 1.1) wrappers for tables and block, so you can define specific code markup for every template, without the need to go every single template file and change the markup.
This is achieved at CFG level for every template, since CFG file is the first file included when a template is initialized in the core code.
Example for Lightning Phoenix:
$color = $row['body_background'];
$css_color = $color;
$full_server_url = create_server_url();
$default_images_root = 'templates/default/images/';
$current_template_images = $current_template_path . '/images/' . $color . '/';
$png_colors = array();
$png_buttons_colors = array();
$images_extension = in_array($color, $png_colors) ? 'png' : 'gif';
$buttons_extension = in_array($color, $png_buttons_colors) ? 'png' : 'gif';
$img_fade = '';
$img_fade_nm = '';
$extra_padding = in_array($color, $png_buttons_colors) ? '" style="margin-bottom: 2px;' : '';
$nifty_corners = false;
$images['page_begin'] = '<div id="wrapper"><div id="wrapper-inner">';
$images['page_end'] = '</div></div>';
$images['tbl_h_l'] = '<div class="roundedbox"><h3 class="rb-cyan">';
$images['tbl_h_c'] = '';
$images['tbl_h_r'] = '</h3><div class="inside inside-text">';
$images['tbl_b_l'] = '';
$images['tbl_b_c'] = '';
$images['tbl_b_r'] = '';
$images['tbl_f_l'] = '</div>';
$images['tbl_f_c'] = '';
$images['tbl_f_r'] = '</div>';
$template_copyright_link = '<span class="copyright">Design by <a href="http://www.mightygorgon.com" target="_blank">Mighty Gorgon</a> </span>';
include(IP_ROOT_PATH . 'templates/default/default.cfg');
Since this file is included within a function, you need to make sure every extra variable you may want to use is declared as global...
Apart from some self-explaining vars, I would like to focus on these: $images['page_begin'], $images['page_end'] and $images['tbl*'].
$images['page_begin'] and $images['page_end'] are wrapper for the main page, the can be used to wrap the whole page within your preferred markup/style. This is very flexible, because you don't need to recode overall_header and overall_footer every time you update your site and you can keep using the default ones (avoiding missing new vars, inclusions, javascripts and so on!). Every time the default template is updated, your style will continue to work fine as designed, since those vars are injected in the default template.
All $images['tbl*'] vars are used for tables and blocks wrapping, so you can easily change how every block looks for all pages, instead of having to re-design every single file with new markup when you want to change how a block looks.
That's all for now... it took more than one hour for me to write this post, I hope you will find this useful.
hampshire
Borgo San Michele
