Archive for June 2010

One of the things that changes in WP 3.0 with multi-site is where file uploads and attachments get stored. This can be confusing to people trying to do export/imports and combine sites together.

In the .htaccess file of a multisite installation, you’ll find this little bit of code:

# uploaded files
RewriteRule ^([_0-9a-zA-Z-]+/)?files/(.+) wp-includes/ms-files.php?file=$2 [L]

The effect of this code is to redirect requests that have “files” in the name to the ms-files.php. As you may have guessed, ms-files.php is the multi-site file handler.

Files in multi-site mode are stored in the /wp-content/blogs.dir structure. Inside that directory, you will find subdirectories labeled with numbers (1, 2, 3, etc.).  Each number corresponds to the ID number of the individual site in the multi-site installation. Each one of these directories holds all the uploaded files for that installation. The ms-files.php file handles a bunch of caching parameters and then sends the file off to the browser upon request.

So the resulting URLs always look like and so forth. The “files” name is therefore special and reserved and cannot be used as a post slug and such.

When you export a site from somewhere and then import it into your new multi-site system, if you also choose to import the attachments, then you’ll have a minor problem. The attachments will be imported into this new files structure. However, the links from an older system are still referring to the old /wp-content/uploads/ directory structure that non-multi-site installs use. Therefore, you will need to go back through your posts and fix all these links and references to the attachments. I use the Search Regex plugin for this purpose, it works well enough and has some powerful search and replace capabilities.


I am making a theme today and working on the image attachment templates. I found that I needed the next and previous image links (in the single image templates… image.php) to be of a specific size, regardless of what the settings the admin tool were. Specifically, I want them to always be 100×100 pixels in size, and cropped.

Image sizing is always a problem for themes. Theme designers want their theme to be pixel perfect in all cases, but WordPress wants the user to have some form of control. With image sizes, WordPress lets the user pick the size of their image thumbnails and so forth. In that case, using those becomes problematic for certain places in the theme which need pre-defined image sizes.

Here’s the quick and easy solution: add_image_size. This function lets you create custom image sizes that can be used by your theme. Plugins can do the same sort of things, of course, but this really comes in more useful as a theme developer’s tool.

In my functions.php file, I put this code:

add_image_size( 'themename-nav-thumbnail', 100, 100, true );

That creates a new image size for WordPress. When image files get uploaded, that new image size will be magically created along with all the other sizes. In this case, it’ll be 100 by 100 pixels, and cropped exactly to that (that’s what the “true” means).

Note the use of the “themename” prefix? You can use anything you like here, actually, but it’s a good habit to always use prefixes for custom identifiers you ever make. This prevents things from interfering with each other.

Anyway, to then use that size for my navigational thumbnails, this small bit of code works:

<div class="prev-img">
<?php echo previous_image_link('themename-nav-thumbnail'); ?>
<div class="next-img">
<?php echo next_image_link('themename-nav-thumbnail'); ?>

I wrapped them in DIVs so that I can float them left and right and style them and such.

So custom image sizes are easy enough to do, but it’s a trick I didn’t know about until I needed it just now. Thought somebody else should know about it too.


I found a really stupid mistake in the STC-Publish plugin this morning, so I went ahead and pushed the fix and all the other changes out as well. Here’s a quick rundown of the new features:

  • STC-Publish now doesn’t have that weird case where it posts to Twitter without the shortlink.
  • Followers Widget is available. This shows a random selection your followers on Twitter. In order to use it, you have to have the “AutoTweet” user set using the publish plugin, so it knows which user to look at. You don’t actually have to use AutoTweeting though, just have it set to a user. Also, this widget is unstyled, so you’ll have to add styling for it to your theme to make it not look terrible. There’s a sample set of styling rules at the top of the plugin code. Only advanced users should probably use this widget.
  • The Follow widget now has a shortcode for use in posts. Just put (tweetfollow user=”username”) to put a follow button into a post. There’s also the stc_follow_button() function for advanced users who want to integrate it into their theme.
  • If you have a Multi-Site configuration set up and you want all your sites to use it, then you can define the STC_CONSUMER_KEY and/or STC_CONSUMER_SECRET in your wp-config file.
  • John Bloch sent me a Dashboard widget for Tweeting. After suitable modification, it’s in there too.
  • The Tweet boxes in the Publish widget and the Dashboard widget now use javascript to resize themselves to the correct sizes.

So there you go. Enjoy!


Tried to install a local Apache this morning and couldn’t get it to start. Turned out Skype was the problem. Matt apparently encountered this years ago, but I never really started using Skype until lately.

Anyway, it still happens. But there’s a simple fix.

Go to the Tools->Options menu. In there, find the Advanced->Connections tab. Turn off the option to use port 80 and 443. These are there to allow Skype to try to get through firewalls. They also, incidentally, block Apache from starting since it can’t grab the port it wants.

Just a heads up in case anybody else encounters the problem.


The other day, Klint Finley wrote a very good walkthrough of using the new Multisite functionality of WordPress 3.0. In the comments, a lot of people wanted to know how to use your own domain names. Since I’m doing that now, here’s a quick walkthrough/how-to guide.

Step 1: Manual Plugin Installation

The Domain Mapping plugin is not your regular kind of plugin. You cannot install it through the normal Plugins->Add New menu. Well, actually, you can, it just won’t work.

So first, download the plugin manually.

Note: For this tutorial, I will be using the WordPress MU Domain Mapping plugin. However, I am using the trunk version of the plugin. It has fixes in it that you will need for proper 3.0 support. Don’t try it with the regular version. (Note: The regular version works fine. This was originally written before the latest version, or 3.0, was released.)

The plugin has two main files you need to put in the proper places.

Domain mapping php file location

The first file is the domain_mapping.php file. This needs to go into the mu-plugins folder. The mu-plugins folder is a special folder, which you may not even have yet. Just create it underneath the wp-content folder and put that file into it.

Sunrise php file location

The second file is the sunrise.php file. This is a special filename for WordPress. Don’t worry about it, just put it in the wp-content folder.

Step 2: Activate Sunrise

Now you need to edit your wp-config.php file. Add this line of code to it:

define( 'SUNRISE', 'on' );

Simple, really. This will cause WordPress to go load that sunrise.php file and use it.

Step 3: Server info

Now you have to configure the domain mapping plugin so that it knows what it’s doing properly. This is easy to do, really. Go to your main domain’s admin page and log in as a super admin. Then go to the new Super Admin->Domain Mapping menu.

Domain mapping setup screen

Here you have a few different options, but two main ones that count. You can either put in the IP address of your server (as defined in your domain’s main A record) or you can put in a CNAME that points to your server. The IP address is what most people will want to use. If your server uses more than one, you can enter them all here, separated by commas.

Other options on this page:

  • Remote Login – This will make your login pages for all sites redirect to your main site to do the actual login. The benefit of this is that when you log in to one, you log into all of them. The downside is that the URL changes to another domain in order to log in.
  • Permanent redirect (better for your blogger’s pagerank) – This makes your subdomain or subdirectory sites redirect to their domains. You should leave this on.
  • User domain mapping page – Turn this on if you want users to be able to put in their own domains for mapping.
  • Redirect administration pages to blog’s original domain (remote login disabled if redirect disabled) – This makes all admin pages show up on the original domain instead of on the new domains. You need this enabled for remote login to work.

Generally I leave only the middle two on. Remote-login is iffy at best, and I want my new domain name to show up everywhere.

Step 4: Mapping the Domain

There’s a bit of a prerequisite here before you do this. When you buy a new domain, you will need to edit its DNS settings to actually point to your server IP or CNAME or whatever you do to make the domain connect to your server. For me, I just give it a new A record with my server IP in it. Easy.

Update: Okay, so there may be more to it than just that, depending on your host. Every host is different, and you’ll have to talk to your host to make them able to point the domain name at your existing site. How to do this varies from host to host, but the important thing is that when you visit your new domain (before you do this!) then you want it to go to your main site, as is.

There’s two ways you can actually map a domain to one of your sites. The user screen is the simplest way, if you left that option on before. Log into the site you actually want to map to a new domain, then go to Tools->Domain Mapping.

User Domain Mapping Screen

All you really do is put in a new domain and set it as the primary. Simple.

Note that if you didn’t get the domain pointed at your server before doing this, then your site will instantly vanish from the realm of mortal man. Setting the primary domain takes effect instantly. You won’t be able to access the site through the old domain any more.

The other way to set domain mapping is through the Super Admin->Domains menu. Here you’ll find a list of sites and their ID numbers. You can map an id number directly to a domain name here. The Tools approach is a bit easier to use, but this will allow you to map domains without visiting them, as you can access this list from your main domain. You can also correct broken domain mappings from here.

Step 5: Seeing the Mapped Domains

If you go to Super Admin->Sites, you’ll find this type of a listing:

Sites listing

You’ll note that on the right hand side you can see the column showing the mapped domains.

Special Note: See in the picture how I’m using a subdirectory install? That’s relatively new. In older versions of the domain mapping system, you had to use a subdomain installation and wildcard DNS for domain mapping to work. This is no longer the case, domain mapping works just fine with subdirectories.


And that’s how it’s done. It’s not super complex, but it does require some knowledge of DNS and how servers work. If you can successfully set up a multi-site install to begin with, you can probably do this as well. Just be aware that it is slightly finicky, and know that you will break your site if you put in the wrong settings somewhere. However, your main domain will always be accessible as long as you don’t try to map it, so you’ll be able to go in from there to correct your mistakes.


Update: Since writing this, Facebook has altered the look of the Application Settings page. Now there’s only two major settings that you need to set, and they’re both on the Web Site tab: The Site URL and the Site Domain. Set those correctly and your App will work with SFC. Set them incorrectly, and it will not. So, much simpler, really. :)

The majority of the email I get from users of the Simple Facebook Connect plugin is questions regarding how to setup their Facebook Application. It’s really not that hard to do, but the plethora of options can seem somewhat intimidating. So here’s the basics of what you need to do.

After creating your application, you’ll need to visit the Apps section in the Facebook Developer Home area. Here you’ll find your application, and the all critical “Edit Settings” link.

Main Application Screen

Firstly, never give out your Application Secret. If you give this out by accident, then use the Reset Secret Key link to get a new one.

Anyway, from here, you want to go into the settings. The settings area is divided into six main sections, but most of the settings are irrelevant. See, you’re building a “Connect” application, not a “Canvas” one. So most of these are meaningless for you. The following ones are what you actually care about:

Application name

Obviously, you want the name of your Application to make sense. I suggest using the same name as your website. You can even use your domain name here if you like. Just be aware that this name is what the Fans of your site will see in their Applications area.

Basic Information

The Basic Information section is important as well, fill it in as you see fit. I also recommend uploading good icons and/or logos for your site. Gives it that finished look.

Contact Information

Contact Information is obviously important as well, but don’t worry about all those extra URLs. They really apply more to Canvas apps. Of course, if you want to make special pages on your site for them and provide the URLs here, feel free.

Authentication Settings

The Authentication Settings page is surprisingly important. Those top two boxes need to be unchecked for a Facebook Connect application. Why? Because when they are unchecked, your Application becomes an “External Website” as far as Facebook is concerned. If you have either them checked, then your app’s Canvas section becomes active and you might have users trying to add it to their profiles and such, resulting in broken pages and a general bad user experience.

Connect Settings

The Connect Settings page is probably the most important one. These settings must be filled in and they must be absolutely accurate. Specifically, the URLs must be the URLs that are actually used by your site. Capitalization matters. The leading “www” or lack of one matters. Whatever the URL your site is in the browser is what you MUST put into these fields. Anything less and your site will not work.

Advanced Settings

The Advanced Settings screen contains these three fields which you need to set in the same way I did. The email domain no longer exists, however. They removed that in favor of a different approach, so you can ignore that field.

Application Profile

Finally, after you have saved those settings, take the time to go back to the main application screen and click the “Edit Application Profile” link. You’ll be taken here, where you can set up the “look” of your application page on Facebook. This includes what tabs are visible, the stuff in the Info section, etc. You can add extra Applications tabs to this page and generally customize all sorts of stuff. None of that affects your site, but it does affect how the App Page looks in Facebook. The more polished it is, the more likely people will “Fan” your Application. And Fans get updates from when you publish posts to the Wall. Great way to drive traffic to your content.

Hope this helps! Mainly, I hope this reduces the number of questions I get about this process. Enjoy SFC!