glFusion provides several ways you can customize your site. With this much flexibility, sometimes it is difficult to keep track of the changes you make, or even why you made them. We are going to look at some of the methods I use to keep track of customizations I do to web sites that I manage.
glFusion attempts to make the upgrade process as painless as possible. glFuision has features to allow you to store your customizations where they will not get overwritten during an update. Let’s do a quick review of the customization features in glFusion:
custom/ template directories
Every theme directory and plugin template directory has a corresponding custom/ directory where you can place custom versions of template. The custom/ directories are never overwritten during an update. For more information, see the Custom Directory for Templates documentation.
Each theme will load a custom.css style sheet if it is present in the theme directory. You can place your own styles, or override standard styles in custom.css to change the colors or look and feel of certain aspects of your site. glFusion does not ever overwrite this file. For more information, see the Customized Style sheet documentation.
If you are a PHP programmer, or you want to modify some existing PHP code to meet your needs, you can place your modification in the private/system/lib-custom.php file. glFusion has several hooks in place where it will call a CUSTOM_*() function instead of the standard glFusion function. Unfortunately, there is very little documentation on the CUSTOM hooks. Generally, folks will look at the glFusion source to determine if a CUSTOM hook is available.
Every theme has a functions.php PHP file that controls certain configuration items for the theme. You may want to change or override the default configuration. You can create a custom functions.php in the <themename>/custom/ directory. glFusion does not overwrite this file during upgrades. For more information see the Theme’s custom functions.php documentation.
Keeping Track of All Your Customizations
As we can see, there are several places where we can customize stuff. But, sometimes when we upgrade glFusion, we need to update our customization's as well. To keep track of all my customizations, I create a sitelog.txt file for each website. This becomes my log / diary of my customization's and general notes for the site. Any time I make a change, or even modify certain configuration settings, I update the sitelog.txt with the information. I store my sitelog.txt in the private/ directory (same directory with db-config.php), this keeps it out of the webroot so it cannot be accessed via the browser. I open it up in my FTP program anytime I’m working on the site.
For me, getting into the habit of always updating the sitelog.txt was difficult. Sometimes I would tweak something and forget to log it and almost every time, when I did the next upgrade I spent an hour or two tracking down an issue because I didn’t update a customization. Over time, it has become a habit to always open the sitelog.txt whenever I either open my FTP client or remote into the system.
Each time I upgrade a site, I look at my sitelog.txt and compare it with the What’s New and Template Changes pages in the glFusion Wiki so I know exactly what I need to update to keep everything in sync.
If I see a template that has been updated in the Template Changes matrix that I’ve customized, I immediately make the necessary changes in my customized version of the template.
Having a diary of what I change has proven to be a very valuable tool when upgrading. I have some sites that I don’t touch that often so I tend to forget about my customizations over time. Sitelog.txt has proven to be a valuable additional to my site administration routine.
What Should You Log?
At a minimum, you should always document any customization's. I go so far as to document any configuration changes I make and even what certain static pages do. Here is my sitelog.txt for glfusion.org:
sitelog.txt - glfusion.org Template Customizations ----------------------- - footer.thtml - added CC4 copyright in the footer area (Mar 2016) Template functions.php Customizations ------------------------------------- - functions.php - changed $_SYSTEM['disable_slimbox'] to TRUE - I prefer to use the uikit lightbox custom.css Customizations ------------------------- - none lib-custom Customization's ------------------------- - none Static Pages ------------ - homepage-content - glFusion New / Features displayed below splash image - centerblock - checked (enabled) - Entire Page - Homepage Only - homepage-header - used in the header.thtml (default behavior) - contains the splash image with links to demo / download - dashboard - uses auto tags to display forum, latest news - set to show left blocks General Notes: -------------- - oauth keys stored in glfusion.org.keys in general-sync/keys/ directory (local systems)
I hope this motivates each of you to start logging your modifications. Maybe a good feature request for glFusion would be to have a site administrators log built in so you can access and modify via the web interface….