In customizing a theme in 1.4.x or upgrading a theme from a previous version, many people are seeing the error message "Template error - failed to find block BLOCK_ID", where BLOCK_ID is one of the buttons/links on the SYS_MENU or SUB_MENU, or one of the other template variables. This post will describe in detail why this error occurs and how to properly customize your SYS_MENU or SUB_MENU. These techniques can easily be applied to the other template variables that give this error.
The first thing you need to do is to find out where the BLOCK_ID mentioned in the error message is found. Go to the sample/theme.php and search for the BLOCK_ID. Look on the line or above the line where BLOCK_ID is mentioned to figure out which template variable is the relevant one. If the template variable is not the sys_menu or sub_menu, then you merely have to copy the template variable from sample/theme.php to your theme.php and customize the HTML as desired, leaving the BLOCK_ID lines alone. Please still read the rest of this post so you understand why the error occurs.
In previous Coppermine versions, the SYS_MENU and SUB_MENU were defined by straight HTML in $template_sys_menu and $template_sub_menu respectively (see the 'hardwired' theme for a current theme that still uses straight HTML). Coppermine 1.4.x uses a couple of shortcut functions to make modifying these menus more clear & organized, but it also makes it easier to break your theme if you don't understand what these shortcut functions do. The main reason why you get the error message "Failed to find block" is that you removed or renamed a button/link that Coppermine expects to find in one of those menus. If you want to remove a button, you instead need to make an empty button; you are required to leave the button label in place so that Coppermine knows where to find the button - even though it is an empty button. It won't show up, as you want, but Coppermine will also be happy to know you specifically don't want that button instead of flaying around finding no clue if you really want to remove the button or merely neglected to specify one way or the other. Receiving the error message "failed to find block" tells you that you did the latter. You need to specifically say, in effect, "I want this button not to be displayed". I hope that this is clear. Everything described below depends on understanding what Coppermine expects from your custom theme. Note that I'm describing here how to customize your theme. Overall - not theme-related - the best way to remove Coppermine items is with this plugin:
http://forum.coppermine-gallery.net/index.php?topic=26893.0.
In all theme customizations, you copy code from the sample/theme.php to your theme.php. In case you skipped this step, please make sure you copied a theme to a new folder before you start to customize it. If you are creating your own theme by customizing another, you need to create your own folder & theme name, for the sanity of all involved (and future clarity). Do not copy the sample/theme.php; this theme includes all the customizations you can use in your theme - it's intended as a central repository to be copied from, not used directly.
Unlike other theme customizations, it's a bit more difficult to figure out which blocks to copy to customize the SYS_MENU and SUB_MENU (which are the labels used in template.html). All other customizations have a single variable or function to copy and customize. This one requires copying 2 functions and bunch of other lines. Start by copying the whole block to your theme, starting from and including these 3 lines:
// Creates buttons from a template using an array of tokens
// this function is used in this file it needs to be declared before being called.
function assemble_template_buttons($template_buttons,$buttons) {
and continuing through and including these lines:
$params = array('{BUTTONS}' => assemble_template_buttons($template_sub_menu_button,$sub_menu_buttons));
$template_sub_menu = template_eval($template_sub_menu,$params);
}
This is a total of 94 lines (approximately - future releases may add or delete some).
A summary of this block is as follows:
- function assemble_template_buttons
- function addbutton
- variable $template_sys_menu
- variable $template_sub_menu
- block to fill in $template_sys_menu
- block to fill in $template_sub_menu
If you are upgrading your custom theme from a previous version, please refer to the documentation for upgrading themes. Some of this block is described in the theme upgrade docs. What I'll describe here supplements those docs but it doesn't replace them.
I'll describe how to customize the addbutton lines in the sys_menu and sub_menu blocks. Here's one of those buttons:
// {HREF_LNK}{HREF_TITLE}{HREF_TGT}{BLOCK_ID}{SPACER}
addbutton($sys_menu_buttons,'{HOME_LNK}','{HOME_TITLE}','{HOME_TGT}','home',$template_sys_menu_spacer);
There are 6 parameters in the addbutton function. The important ones to customize are the 2nd, 3rd, and 4th ones. In order, they are:
- {HREF_LNK} - the link text you see on the web page
- {HREF_TITLE} - the title of the link, usually seen as a tooltip or mouse hover box
- {HREF_TGT} - the URL of the link, i.e. the webpage to go to
The 5th parameter is the BLOCK_ID and
must not be modified. Coppermine uses the BLOCK_ID to identify this button and uses it when it wants to do something in the core code with this button. In the example above, 'home' is the BLOCK_ID. If for example you want to replace the home link with a link to your BBS so you can switch back & forth between your Coppermine gallery and your forum boards, replace the _LNK, _TITLE, and _TGT, but keep the BLOCK_ID as 'home' even though it might not be your home page. If you want to add a link in addition to the home link, you add a new addbutton line in the appropriate place. The curly braces in the default buttons are used by Coppermine as labels to be replaced with language-compatible text or URLs. If you want to replace something with custom text & URL, do not use curly braces - just type in the text & URL in single quotes. So, in this example, you would modify the home addbutton as follows:
addbutton($sys_menu_buttons,'Forum','Go to the forums.','../phpBB/index.php','home',$template_sys_menu_spacer);
As you see, I didn't touch the BLOCK_ID 'home'.
To remove menu items, you cannot comment out the relevant addbutton line. If you do so, Coppermine cannot find the BLOCK_ID anymore because you have removed it completely by commenting it out. A quick & dirty way to remove menu items is to send blank strings for the _LNK, _TITLE, and _TGT parameters along with the spacer parameter (the last one), leaving the BLOCK_ID alone as shown:
addbutton($sys_menu_buttons,'','','','home','');
This is dirty because it produces an empty <a href> tag which is not shown anywhere and doesn't cause display issues, but is not clean since it is there in the source of the web page. The best way to remove menu buttons and any other Coppermine items is with the Final_Extract plugin, which removes the block after Coppermine has done its thing and just before it is to be displayed on the web page. Here's the thread for the plugin:
http://forum.coppermine-gallery.net/index.php?topic=26893.0.
So, what's the bottom line? Leave the BLOCK_IDs intact for all theme variables, for those specified by HTML (using <!-- BEGIN BLOCK_ID --> and END comment tags), and for those specified by addbutton(). Modify the links, titles, and targets of those items you want to replace, but leave the BLOCK_ID alone so Coppermine knows you want to replace this BLOCK_ID. To add items, insert new addbutton() lines and HTML as appropriate. To remove items, use the plugin noted above, or use the quick & dirty method, but do not comment out the addbutton() line or remove the BEGIN & END tags.
p.s. If you want to customize the buttons to be images instead of text, you need to use straight HTML as exemplified in the 'hardwired' theme (and some other themes). Respect the BLOCK_IDs and you'll be all set.