hacks

How I fixed the “cannot redeclare _checkactive_widgets()” error in WordPress child themes

Update 3/31/2014

So it’s now almost 4 years after I wrote this post and there’s still no new information regarding this issue. I assumed originally that this was some WordPress core function, but WordPress core coding philosophy would prohibit adding code to an individual theme’s files. Now, I haven’t gone through the code that gets added line-by-line to analyze exactly what it’s doing and I’m not going to. But there have been those who have said that this is the result of a worm. Considering I often download themes (and plugins) from clients, I can understand how my local environment could be affected by a worm, but I’m still skeptical that it’s that malicious.

Still, here’s the REAL fix, since when I search for this issue, my post still shows up on the first page of Google. The below instructions still work (for the current theme) but this will take care of it for good (at least so it seems).

Ready? Here it goes:

Step 1:
Go into every single functions.php file on your server. Delete all the code at the end of the file starting with function _checkactive_widgets().

Step 2:
Repeat until you have done this to all your themes.

Note: Some themes (like Responsive, among others) have functions.php files inside a subdirectory. You need to get those, too.

Once all the files have been cleaned, you should be good to go.

Original post below for posterity (and for the cheap, easy fix).


So, I had a problem.  For a while I’ve noticed a whole bunch of code being tacked on to my functions.php file.  I’ve had no idea where it came from since I certainly didn’t write it, so I generally just removed it when I saw it.  Then I noticed this weird php error when I built a child theme saying “cannot redeclare _checkactive_widgets()”.  After a few minutes, I realized that it was that same piece of code that’s been tacked onto my functions.php file, only now, since it’s a child theme with two functions.php files, it’s there twice (redeclared).  What gives?

From what I can tell, indirectly (because I’ve found zero documentation on this issue, and I’ve Googled my fingers numb trying), the _checkactive_widgets function basically looks for whatever widgets you have on your current theme and makes sure they get saved when you switch themes so you don’t have to start over.  A great idea.  But if you’re using a child theme, you get my problem.  The only thing I could think of doing is deleting that piece of code, but, from some trial and error, as far as I can tell, whenever you do just about anything in the back-end, it automagically regenerates the code.  So here’s how you fix it:

Using the “Tip for theme developers” note in the Child Themes entry in the WordPress Codex as a guide, I added this to my functions.php file:

if (!function_exists('_checkactive_widgets')) {
	// do nothing
}

This says “if the _checkactive_widgets function doesn’t exist, do nothing.” If it didn’t exist, presumably WordPress would add it in, and this prevents that. It already exists in the parent theme, and the parent’s functions.php gets run next, so this prevents overlap. This has been bugging the hell out of me for weeks, so hopefully it helps someone else.

How to upgrade your Museum Theme to the most current version after you’ve made changes to the files

Our themes are released under the GPL.  That means that you are free to take them, change them, and even redistribute them under the terms of the GNU Public Licence.  We’ve seen what a couple of you have done with our themes and we couldn’t be happier to see you taking our code and bending it to fit your site.

But what happens when there’s a new version and you want to upgrade?

The first things you’ll want to do to keep your customizations and also keep the core code up-to-date is to create your own “fork” of the theme.  This is a lot less complicated than it sounds, and all it means at this point is to rename the folder that holds the theme files (so if you’re using Museum zine, you could change the folder name from AP-Museum_zine to YourDomain-Museum_zine or YourDomain_zine or just YourDomain — whatever you want as long as it makes sense to you) and to make some minor edits to the main stylesheet (style.css).

Why do you need to edit the stylesheet if you’re not making any CSS changes?  Well, WordPress checks the style.css to grab some basic information that’s used on the Appearance → Themes page.  All of that stuff is located above all the code, so if we’re looking at zine again, you’d see this:

/*
Theme Name: AP-Museum zine
Theme URI: http://www.arcanepalette.com
Description: AP Museum zine is a set of grungy, magazine-style themes inspired by the underground fanzine movement
Version: 1.1
Author: Arcane Palette Creative Design
Author URI: http://www.arcanepalette.com
*/

If you have two themes with the same name in the Themes page, both will display, but it gets confusing (for the record, WordPress tells you the location of the files underneath the description, where it says All of this theme’s files are located in /themes/AP-Museum_zine so even if you skip this step, you can still sort of tell which is which).  So what you may want to do is change the Theme Name so it appears as something different on the Themes page.  All you need to do is change AP-Museum zine next to Theme Name: to something else of your choosing.

Congratulations, you’re now officially a theme developer and have made your own version of a WordPress theme! (If you wanted to distribute it to others at this point, there’s a few more things you’re required to do by the GPL before you’re good to go on that point, and “forks”, in particular, have some special rules.  It’s a good idea to be familiar with the terms of the GPLv3 — which is what our themes are released under — before actually releasing your own theme.  For the most part, however, you probably don’t have any intention of redistributing your theme, so you don’t need to worry about GPL guidelines or restrictions — the GPL only affects you in that sense when you choose to distribute your theme — customizing your theme for your own personal use is fair game.)

Nothing we’ve done so far has actually changed anything. In reality, you’ve already changed the theme, so all we’re doing is changing the name and the directory to reflect that.  (As such, any of the other things in the style.css you want to change, like the version or the author, you’re free to do also.)  Now we’ll concentrate on incorporating the new code into your theme (or vice-versa: your customized code into the new version).  To do that, you first need to know what files you’ve changed.  Every time a piece of GPL software is modified, the new version is required to include some form of documentation saying what you changed and when.  This is primarily to keep developers accountable for their code, so that if you fork a piece of software, someone else can come along and figure out where the software was forked from the original source and what things were added or changed.  But even more than that, keeping this kind of documentation — which can be in the form of a Changelog — keeps you honest, and provides important reference notes for when you need to make future updates.  All our themes include a changelog.txt file in the theme folder which includes all the changes up to that date.  You may want to check this before you start so you know what we updated in the new version.  It might save you some work if you’ve modified a file that we didn’t make any changes to this time around — in that case, you could just keep your version rather than copying your code into the version of the file included in the theme zip package.

Let’s say you’ve edited the header (header.php), the sidebar (sidebar.php) and the single post template (single.php).  The first thing you’ll want to do is put those files aside — create a temp directory within your theme and copy those files in, or just copy them to the desktop.  For that matter, it’s probably a good idea to back up your whole theme, just in case there’s anything you might have forgotten about.  Once you’ve gotten your customized files out of the way — including the style.css that you just modified — copy the contents of the updated theme into your theme folder.  This will most likely involve extracting the zip somewhere on your computer, then navigating to that folder, selecting all the files inside and copying/pasting them into your theme.

Occasionally, we reference specifically in the changelog what files we’ve created or modified, and moving forward we’ll be doing a better job of being more specific in this regard.  If it doesn’t look like we’ve made any changes to any of the files you’ve modified, you can just copy your customized versions into the theme folder and be done.  However, if we (explicitly or implicitly) reference in the changelog that we updated any of the files you’ve customized (including changes to style.css, which should be fairly rare in most cases), you’ll need to go into your version and copy your customizations into the code of the updated version.  Presumably you remember (or at least have a general idea) of what you did last time, and if all the code surrounding yours remained the same (which it should), it will be fairly easy to do a stare-and-compare with the two files and figure out what you need to do.

If you’ve been making the changes live on your site, everything should be ready to check and make sure it worked at this point.  If you’ve been editing the files offline (recommended), you should be good to upload them and see if anything else needs to be tweaked.  Now’s when you’ll find out if your customizations were actually limited to the files you updated in the new version, or if there were other modifications that slipped your mind.  However, if you have a backup of the original theme, you can always go back, find what you added, and copy that into the new version of that file, too.

That’s it.  Now you’ve got all the benefits of the new version of the software with your own customizations.  If you have any questions along the way, feel free to let us know in the Support Forums.  If you’re using a modified version of our Museum Themes, we’d love to see links posted in the comments!

How to add customizable header images and customizable backgrounds to your WordPress theme

One of the coolest new features of WordPress 3.0 is the ability to customize the site header image and background color or image. The custom header actually goes one step further and lets you set a unique header for each of your pages. This means that you can create unique headers that tie into the content of the page without complex if (is_page()) statements or hard coding them into unique page templates. The only problem is that these features need to be added into the theme for them to show up as options in your wp-admin panel and not every free (or even commercial) theme has those options set up and ready to go.

Not all themes are made for big, changeable headers, but for those that are or would adapt well, this gives users a powerful resource far beyond the custom header features that Kubrick, the previous default WordPress theme, offered with its’ ability to change the header color and gradient. Likewise, I’m tentative about giving users the ability to pick a color at random from the 16 million colors at their disposal – it’s too easy to create clashes worthy of the most gaudy GeoCities or MySpace creations. However, used with discretion and a keen eye, these features add a powerful tool to those WordPress users’ arsenal who are just itching to add a little bit of personality to their site without breaking everything.

Our newest free theme, Color Garden includes both custom headers and custom backgrounds, making it our first theme – free or otherwise – to offer both. I also played with custom headers on my recent redesign of jazzsequence.com. For the headers, it’s not the most intuitive thing to add by hand at all, and few of the resources I have found go far beyond quoting the code from TwentyTen’s functions.php file, so we wanted to give our readers just a little bit more to go on if you want to add these features to your blog theme.

Custom backgrounds are dead simple. A single line of code and you’re done:

// This theme allows users to set a custom background
add_custom_background();

Once this is included somewhere in your functions.php file, you will have a Background link under Appearance that gives you options to set a solid color for the background (by hex code or picking from a color map) or upload an file to use as a repeating background image.

Headers are a bit more complex.

To really understand how custom headers work, you need to know how post thumbnails work. Post thumbnails were added to WordPress core in 2.9 and use the built-in resizing process that happens when you upload images to create the thumbnails that will appear next to your post or post excerpt. This is presumably to replace other third-party scripts like the ubiquitous TimThumb which creates its own thumbnails and stores it in a cache folder usually located in the theme folder (although it could really be anywhere). Since WordPress 3.0, what was previously referred to as Post Thumbnail on the Add New Post page is now called Featured Image. This change is reflects the fact that the Featured Image option now controls the post thumbnail or the custom header, and the way it knows the difference is by the size of the image you are using.

Let’s take a look at how to add it to your theme and then we can revisit how to use it once it’s there. The code I will be showing comes from Color Garden although all of it has been adapted from TwentyTen (including much of the comments). Since most other posts I’ve found don’t discuss each piece of the header image function, I will go over each so you understand just what it is that you’re adding and what needs to be changed or left alone.

The first part is here:

// Your changeable header business starts here
// No CSS, just IMG call. The %s is a placeholder for the theme template directory URI.
define( 'HEADER_IMAGE', '%s/images/headers/leaves.jpg' );

The key thing to pay attention to in this snippet is the HEADER_IMAGE definition. This is the default header image. If this is left blank or set to an invalid path, no image will show up, and depending on your CSS, the layout might break. In TwentyTen this is set to %s/images/headers/path.jpg. You’ll probably want to put something here even if you plan on changing it later, and you’ll want to make sure the image actually exists where you say it exists.

The next part sets the height and width of your header image:

// The height and width of your custom header. You can hook into the theme's own filters to change these values.
// Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values.
define( 'HEADER_IMAGE_WIDTH', apply_filters( 'cg_header_image_width', 1000 ) );
define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'cg_header_image_height', 343 ) );
 
// We'll be using post thumbnails for custom header images on posts and pages.
// We want them to be 1000 pixels wide by 343 pixels tall.
// Larger images will be auto-cropped to fit, smaller ones will be ignored. See header.php.
set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true );

Notice that we’re using set_post_thumbnail_size with the header image’s dimensions. This is because the custom header function uses the existing post thumbnails function from 2.9 and builds onto it. As the comments indicate, images that are equal to or larger than the height and width definitions will be resized to fit and set as the header image when you add it to your post or page. Anything smaller will be ignored and set as the post thumbnail (if post thumbnails are enabled).

The last part of the custom header function is this:

// Don't support text inside the header image.
define( 'HEADER_TEXTCOLOR', '' );
define( 'NO_HEADER_TEXT', true );
// ... and thus ends the changeable header business.

The NO_HEADER_TEXT and HEADER_TEXTCOLOR add the ability to change the color of the text that appears in the header. The alternative (pulled from the WordPress Codex) would be to use:

define('HEADER_TEXTCOLOR', 'ffffff');

and omitting the NO_HEADER_TEXT line.

Now this part is done, you’ve enabled custom headers and defined a default. But what if you want to have multiple defaults like TwentyTen? In that case, we go back to TwentyTen’s functions and keep digging:

// Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI.
register_default_headers( array(
 
'leaves' => array(
'url' => '%s/images/headers/leaves.jpg',
'thumbnail_url' => '%s/images/headers/leaves-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Leaves', 'cg' )
),
 
'sunset' => array(
'url' => '%s/images/headers/sunset.jpg',
'thumbnail_url' => '%s/images/headers/sunset-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Sunset', 'cg' )
),
 
'beach' => array(
'url' => '%s/images/headers/beach.jpg',
'thumbnail_url' => '%s/images/headers/beach-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Beach', 'cg' )
),
 
'blueberries' => array(
'url' => '%s/images/headers/blueberries.jpg',
'thumbnail_url' => '%s/images/headers/blueberries-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Blueberries', 'cg' )
)
) );

Again, we’re looking at the code from Color Garden but it’s adapted from TwentyTen’s functions.php. Each item in the array above defines one of the default header image options. Color Garden has four default headers to choose from to go with the four color schemes built into the theme. All we’re really doing here is adding the path to the image, the path to the thumbnail of the image that appears on the Headers page in the WordPress backend, and the description which – as far as I have been able to tell – really only affects the alt text of the image in the backend.

All said, what you should be looking at in your functions.php file when you’re done is this (if you’re including multiple default header images):

// Your changeable header business starts here
// No CSS, just IMG call. The %s is a placeholder for the theme template directory URI.
define( 'HEADER_IMAGE', '%s/images/headers/leaves.jpg' );
 
// The height and width of your custom header. You can hook into the theme's own filters to change these values.
// Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values.
define( 'HEADER_IMAGE_WIDTH', apply_filters( 'cg_header_image_width', 1000 ) );
define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'cg_header_image_height', 343 ) );
 
// We'll be using post thumbnails for custom header images on posts and pages.
// We want them to be 1000 pixels wide by 343 pixels tall.
// Larger images will be auto-cropped to fit, smaller ones will be ignored. See header.php.
set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true );
 
// Don't support text inside the header image.
define( 'HEADER_TEXTCOLOR', '' );
define( 'NO_HEADER_TEXT', true );
 
// ... and thus ends the changeable header business.
 
// Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI.
register_default_headers( array(
 
'leaves' => array(
'url' => '%s/images/headers/leaves.jpg',
'thumbnail_url' => '%s/images/headers/leaves-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Leaves', 'cg' )
),
 
'sunset' => array(
'url' => '%s/images/headers/sunset.jpg',
'thumbnail_url' => '%s/images/headers/sunset-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Sunset', 'cg' )
),
 
'beach' => array(
'url' => '%s/images/headers/beach.jpg',
'thumbnail_url' => '%s/images/headers/beach-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Beach', 'cg' )
),
 
'blueberries' => array(
'url' => '%s/images/headers/blueberries.jpg',
'thumbnail_url' => '%s/images/headers/blueberries-thumbnail.jpg',
/* translators: header image description */
'description' => __( 'Blueberries', 'cg' )
)
) );

What I haven’t said yet is that in every instance that cg appears in the code, this specifically references Color Garden. In TwentyTen it’s twentyten. You can put whatever you want here so long as it remains internally consistent.

After you’ve got your functions.php set up, you still need to add in some code in your header.php to actually display the custom header image. What we have in Color Garden is taken almost verbatim out of TwentyTen.

	  <?php
          // Check if this is a post or page, if it has a thumbnail, and if it's a big one
          if ( is_singular() &&
                  has_post_thumbnail( $post->ID ) &&
                  ( /* $src, $width, $height */ $image = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'post-thumbnail' ) ) &&
                  $image[1] >= HEADER_IMAGE_WIDTH ) :
              // Houston, we have a new header image!
              echo get_the_post_thumbnail( $post->ID, 'post-thumbnail' );
          else : ?>
              <img src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="" class="masthead" />
          <?php endif; ?>

This is where the theme asks “what is the size of the featured image?” and, based on the size, determines whether it is a header image or a post thumbnail.

Now, obviously there needs to be some CSS styling involved and you may or may not want your header image to be 1000 pixels wide by 343 high like ours is in Color Garden. We added a “masthead” class to the image so we could isolate styles to our header image. But, if you’ve made it this far, you’ve got everything you need to tweak the code to suit your theme. The custom headers function is exciting because it doesn’t need to be limited to just header images. You can use it wherever you might want a customizable image in your theme, and there’s more than a few creative uses I can think of beyond headers for something like that.

What’s coming from Museum Themes

First of all, I’d like to thank everyone reading this blog for a successful first week.  We’ll be posting more promo codes on Twitter and Facebook, and we can’t wait to see our affiliate badges start popping up around the ‘Net.  Keep an eye out in those places and maybe bookmark #MuseumThemes to keep up-to-date on new happenings and see what people are saying.

Yesterday, I decided on a direction for this blog.  In addition to normal periodic news updates and the Museum Theme-specific support we provide in the Support Forums, we’ll be posting tips and hacks for customizing your WordPress theme.  These tips will be more general, not limited to support questions or our own Museum Themes.  The first post I’m planning, for example, will be on how to create a YouTube shortcode for WordPress to easily embed YouTube videos into your posts without the need for a plugin or jockeying with code.  In the future we may cover topics like adding custom header functionality (a new feature to WordPress 3.0 and used in the new TwentyTen default theme) and using an RSS aggregator like FeedWordPress or WP-o-Matic to aggregate content from other sites (Twitter, Tumblr, WordPress.com blogs, anywhere with an RSS feed, really).  In the past, when I’ve had something like that to write about, I’ve posted it to Arcane Palette (like our post on adding social bookmarking links to your posts or tweaking the search box to have a little “search this site” or other message inside the box that disappears when you click) or to my personal blog (like my original post on WordPress shortcodes and my piece about changing the default WordPress logo in the dashboard).  From now on, if it’s WordPress, it will go here.  We’ll still post on more general topics on Arcane Palette (like the recent post on using embedded web fonts with @font-face) in addition to our regular barrage of freebies and posts about art, and I’ll always post whatever is on my mind on jazzsequence.  Just, you know, not WordPress.

So that’s what’s on the horizon.  Check back here tomorrow for how to create a WordPress shortcode for YouTube embeds.