Best practices for customizing a theme?

[camil7]

I am currently setting up a blog with s9y and I would appreciate any advice on best practices how to customize themes in a way that makes upgrading the blog to a new version easy.

I see in the documentation http://www.s9y.org/44.html the recommendation is to take an existing theme, copy it and adapt it. I have to admit that making a complete copy is not something that I like to do, as this means updates from the theme must be patched manually after every upgrade.

What I tried first is to only copy the files from the theme I want to customize to my custom theme, and then change the s9y file lookup so it first looks in the original theme directory and then in my custom theme directory. The idea is that having a small patch in one file of the s9y core is maybe better than lots of copied files which might or might not needed to be updated.
I guess this would mean to patch the serendipity_getTemplateFile in ./include/functions_config.inc.php, so I tried that but failed to get it working. (Maybe it is better that way )

My current solution is to clone s9y directly from the git-repo, create a local branch from the 1.7-tag where I can check in my modifications to my local git clone. I then modify the theme I want to customize directly.
That way I hope I can update to the next release via some git merge ... I have not figured out exactly how the merge command will look like, however. Of course the git merge might create conflicts. but I prefer getting explicit conflicts over accidentally overlooking some changes.
This has the additonal advantage that I am not limited to changes in the template; e.g. I already patched the weights in the google sitemap plugin to my personal preferences.

Has anyone experience with that approach? Or how to you customize your themes and still manage to update the blog software painless?

[Timbalu]

It really depends on what you have changed in that theme...

Prior: Themes normally don't get updates often.

Second: If that are CSS changes only, take a theme using a custom user.css file, eg bulletproof or better 2k11! This file does not get overwritten by the theme update, since it is a user file.

Third: If you also, or singulary changed template files, copy them somewhere else and re-copy them after the update, make a diff to be sure you fetch all changes made by the update. This is in most terms the most pratical and recommended usage.

Forth: There is the possibility to use a fallback chain in the info.txt file (which name part, btw, has to get a new name in terms of "copy a theme" to a custom one *). This is not as easy as it sounds, since you have to know how these fallback chains happen to work in Serendipity.

Fifth: You might put some change logics into the themes config.inc.php file, to minimize the changeable content in the *.tpl files.

Doing this merge thing via git, sounds like some advanced workaround. I can't give tips on this on the fly. It could do, if you know what you do... But this approach seems much more work like the upper ones.

(*) rename the theme directory name to "aUniqueName" and the info.txt Name: "aUniqueName" under which you can find your new theme in the theme list to install, no quotes.

[camil7]

I noticed that there the user.css (for 2k11 in my case) and I already used it a bit, but the fact that one can set up a chain via the info.txt was new to me, to thanks for telling me! I will try to read the code to figure out how it works.

Also the idea to make a backup of the modified files is a good idea; all that I need to do is to keep a list of the files that I have changed, which is not hard to do and a good idea anyway. I have not needed to customize any logic, but good to know that there is a config.inc.php to do that.

[yellowled]

I noticed that there the user.css (for 2k11 in my case) and I already used it a bit, but the fact that one can set up a chain via the info.txt was new to me, to thanks for telling me! I will try to read the code to figure out how it works.

Back in the old days, said chain used to be pretty short: a template would fetch any file not present in its template directory from /templates/default/. The most simple way to create a theme was (still is, actually) to put an info.txt and a style.css into a new template directory. If you take a look at the mt* templates bundled with the s9y core, you'll notice most of them work that way.

Somewhere along the way, I requested a new feature similar to e.g. child themes in WP, sort of a way to assign a “parent template” and fetch missing files from that template instead. Well, we already had that feature, but somehow, nobody new about it.

These are called engine templates. Basically, you just add a line “engine: WHATEVER” (without the quotes) to your template's info.txt and replace WHATEVER with the (directory) name of the desired engine template. You can even add multiple templates there, like so:

Code: Select all

engine: bulletproof, default

In order to make sure that this actually works properly, you'll want to always add default as the last option because it is still the only s9y template which has all files. I'm still not convinced this is actually necessary, but it doesn't hurt, either.

YL

[camil7]

Wow, this "engine template" thing worked like a charm; well, it worked for me after I figured out the following:

• it is of no use to add or change the 'engine:' line while using the theme - one has to choose another theme and then revert back to the test theme, and only after that the change is picked up. Actually reasonable for the system to read the line only on "install", one just needs to know that when experimenting along.
• one must copy over the "config.inc.php" from the "engine template"; it seems this file is not looked up recursively from the engine template. Otherwise functions defined there are unavailable in e.g. the entries.tpl, leaving colourful error messages in the webserver error log. It seems the lang_en.inc.php do not get looked up recursively, but that might be because of something spooky here.
• for me it even works if I leave out the "default" template. Well, for production I guess I better keep it in as advised by yellowled.

Anyway, looks good to go forward with.

[Timbalu]

Yepp, these were my experiences too. Fine you worked that out!

I "invented" a personal template on this, which needs some updates by now, but as you can see in here
https://github.com/ophian/Sliver/tree/m ... ew_default
it has these files needed to work with the chain.

Config.inc, would now need at least a little addition

Code: Select all

$template_config_groups = NULL;

before the last three...

[camil7]

Thanks for the pointer to the example.
Now that I read it I suddenly figured out that copying over the `config.inc.php` is kinda silly, I only need a file with the lines:

Code: Select all

<?php
include_once S9Y_INCLUDE_PATH . 'templates/2k11/config.inc.php';
/* customizations might follow below this line */

and everything works as well, including the "missing" translations.

[Timbalu]

good idea, too!