Posts tagged ‘WordPress’

I recently acquired a short domain name, otto42.com (the otto.com domain is owned by a German company, and I use Otto42 as my alias a lot on sites as “Otto” is usually already taken). So I decided to use it to make my own URL shortener.

I looked at various methods for this, including simply writing my own (honestly, it ain’t that hard), but I wanted to see what was already available first.

First thing I looked at was the shortlinks system built into Google Apps. I’ve used it before, and it’s fairly nifty. They even have an API available for interfacing it to other things. And hey, the redirections would be served up by Google’s servers, which you can’t beat for reliability. Sadly, after screwing around with this for a while, and trying out some example code, I was totally unable to get their API to work. The whole thing is written in Python, which I have an intense dislike of (whitespace my ass!), and when trying to access the thing via direct calls, it gave me nothing but errors and annoyances.

So I searched around a bit more, and was relegated to building my own, when a tweet by @ozh mentioned that he’d put a blog up on yourls.org. This looked promising, as I know Ozh is active in WordPress, and so of course it would have a plugin. After investigating, I went with it. It works pretty well, actually.

How to do it

First thing I did was to point my short domain at a directory on my hosting account. If it’s going to run code, it needs to have a place to do it from. So I made a yourls directory and pointed the domain to it using my hosting control panel.

Next, I grabbed a copy of the yourls code and installed it there. 300+ files to FTP? Yikes. Complex. A quick bit of reading told me that it needed a database and a config file. Very similar to WordPress in this respect, except the config file resides in the includes subdirectory for some reason. Not so obvious, but whatever.

I toyed with the idea of using the same database for yourls that I already use for WordPress, but ended up creating another one for it. I’m now thinking that it might be worth merging them though, as that way, VaultPress would probably back up the yourls tables too.

After some hosting weirdness, the thing was up and running.

Plugin

Installing the WordPress plugin is a snap. Just find it in the Add New Plugin interface and hit install. After Network Activating it for all my sites, I went to configure it. I had to configure it on each site separately, but no big deal.

Configuration is fairly straightforward. Tell it URL of the API interface, give it my username and password, and voila. Worked first try.

There’s a bunch of Twitter stuff there as well which I only set up to make it stop bothering me about it. I don’t want this plugin to send out my tweets on new posts, as I already use my own Simple Twitter Connect for that. Still, it bugs you with an error message if you don’t set it up, so I did. Thankfully, there’s checkboxes to turn the autotweeting on and off, so I just leave these turned off. Honestly, I think this whole Twitter thing should be removed from the plugin, but I can understand the “easy” factor here for new users. Making them totally optional would be a nice enhancement though.

At first, I was confused because when I turned it on, I saw no way to make it back-populate my old posts into the shortener. Turns out I didn’t need to, it started doing it all by itself shortly afterwards. I think it actually does shortening on an on-demand basis, creating a shortlink whenever there isn’t one already there for a post.

The plugin also hooks into the Shortlink API, meaning that my Twitter plugin will automagically use the new shortlink. You can see that the shortlink box below this post has the otto42.com shortlink in it. I had to make zero changes to make that work. Isn’t interoperability fun?

One other thing I did have to do was to turn off the old wp.me shortlinks I used. These are provided by the WordPress.com Stats plugin, and there’s a checkbox in its options page to turn them off. No big deal.

Final thought

So yeah, if you have a short domain and want to make your own shortlinks, then YOURLS is a pretty good choice. I haven’t played with the stats gathering part of it yet, for the simple reason that I only just turned it on and thus have no stats to view. Still very easy to do, on the whole. Of course, if it could be entirely a WordPress plugin, then I might think it much cooler. :)

Update: There is a minor problem in the way the YOURLS plugin handles the WP Shortlink API. I’ve reported it upstream, hopefully it can be fixed soon. Still, it’s a minor issue. The workaround for now is to call wp_get_shortlink(get_the_ID()) when you want to get the shortlink for a post inside the Loop.

Shortlink:

If you don’t get immediate responses from me for the next few days, that’s probably because I’m not here. As you can tell from my new sidebar badge, I’ll be in Savannah, GA for WordCamp Savannah 2010. I’ll be around the SCAD River Club all of Saturday and Sunday, and also Friday (if they’ll let me hang out, I didn’t sign up for that). Looks like it’s going to be awesome, Jane has really pulled it together nicely.

I will be trying though, and the hotel claims to have internet, but this is going to be my first real road-trip for a WordCamp, so I’ll be mostly unavailable for quick answers like I know a lot of people are used to getting from me. Don’t worry, I will get to you. Eventually.

If you’re coming to Savannah, please make it a point to come and ask me anything you like. I’m looking forward to meeting people and getting to know the community better. My only meat-space connection with the WordPress community has actually been meeting (and working for) Matt, and he’s clearly a biased source. ;)

So enjoy your week, everybody! I know I will!

And I WILL be having dinner at the Crab Shack. This is a requirement.

Shortlink:

A while back, I wrote a post detailing why it was a bad idea to generate Javascripts using PHP in WordPress plugins. In that post, I mentioned a couple of better ways to do it.

At the time, I didn’t know about the third, and best way, to accomplish this. Mike’s comment over there reminded me of it. WordPress has it built in.

If you already know about wp_localize_script, you can stop reading now.

The wp_localize_script function was made in order to allow for WordPress translations to be able to also translate some of the JS files inside WordPress. Thus the name “localize”. The way it works is to load up the translated versions of text from the translation files and then include them into the resulting HTML output as a Javascript object. The scripts then use that object to produce any text output they need to produce.

Turns out that’s really similar to our goal of sending arbitrary parameters from WordPress to be used by Javascript code.

How to do it:

1. Make your script static (instead of generated) and enqueue your script as per normal. Example:

wp_enqueue_script('my-script','/path/to/whatever.js',…);

No real changes there. You’ll have to come back and modify your script to use these parameters it’s getting passed, but we’ll get to that in a minute.

2. Build an array of your parameters that you want to send to the script.

$params = array(
  'foo' => 'bar',
  'setting' => 123,
);

Note that my parameters are simple examples, but this is PHP code. You can get your parameters however you like. Such as get_option to pull them from the database, perhaps.

3. Call wp_localize_script and give your parameters a unique name.

wp_localize_script( 'my-script', 'MyScriptParams', $params );

What this will do is make WordPress output an inline script with your parameters (properly encoded) just before the enqueue outputs the script tag that loads your script in the first place. So then those parameters will be available to your script as an instance of an object with “MyScriptParams” (from my example).

This means that Javascript code can now reference them as attributes of the name you gave.

So, step 4. Modify your script to use those parameters. In my example, I used “MyScriptParams” and the parameter names are “foo” and “setting”. In my Javascript code I can use them as “MyScriptParams.foo” and “MyScriptParams.setting”.

Much cleaner. One static and unchanging JS file to cache. Parameters get put into your HTML itself as a one-liner. You can deal with the parameters using a normal PHP array before passing them over. No need to screw around with generating Javascript from PHP or looking for wp-load or even messing with tricky actions.

Perfect.

Shortlink:

While this isn’t affecting a lot of people now, it will be in the future. Especially if you use well-supported themes.

Somewhere in version 2.8 or 2.9, WordPress started supporting Theme Updates. In the same way that it supports automatic plugin updates from the plugin repository, a theme developer can now make updates to their theme in the themes repository, and you can upgrade it directly from the WordPress interface.

This is a great thing. Theme developers can fix problems, add features, and have it easy for the users to get those changes right away.

Unfortunately, the theme has historically been the user’s playground. Themes are frequently modified by the user directly. Whether it be for looks or for adding code to be used by plugins or whatever, the theme you’re using is very probably not the theme you downloaded. So upgrading will blow away your changes. Thus, most people are disinclined to upgrade their themes.

The way to avoid this is with a child theme. Child themes derive from another theme, called the parent theme. A child theme, by default, looks exactly like the parent. Then you make your changes to the child, and those changes are used on the site. The parent remains untouched. So, when you upgrade the parent theme, the changes you made don’t go anywhere. They stay right where they are.

So let’s dive right in:

How to Make a Child Theme

First, obviously, install the parent theme. Take note of what directory name it goes into. You can find this on the Theme’s screen, it will tell you what directory each theme is in. The new default theme in 3.0 is “twentyten”. So let’s use that one as our parent.

Now, create a new directory in your /wp-content/themes directory. This is where we’ll put our child theme. Let’s call it “mytheme”.

In the mytheme directory, create a new style.css file. Put this in it:

/*
Theme Name: My Theme
Template: twentyten
*/
@import url('../twentyten/style.css');

Finally, load up WordPress and go activate your new “My Theme” theme. You’ll notice that WordPress tells you both what directory your child theme is in and what directory its parent is located in.

Now you’re running on a child theme. It doesn’t have any changes in it, so it looks exactly like the twentyten theme does, but still, we’re running it.

How to Change Things

Let’s say I wanted to change the color of the post titles to, say, green. A silly change, but it illustrates the point.

Normally, I’d go edit the theme, find wherever the color of the text is defined, and change it or add to it to make the titles change in the way I want. In this case, I do the same thing, but I modify the child theme, and I do it in a way that overrides the specificity of the parent’s CSS code.

To do this, I add this code to mytheme’s style.css file:

#content h2.entry-title a {
   color: green;
}

Why that change? Well, I looked at the parent theme and found that “#content .entry-title a” was what it used to define the color of the post title links. To override that, I need to be more specific.

Specificity is a difficult concept for some people, but basically it breaks down to this: When the browser is parsing the CSS, more specific rules take precedence over less specific rules.

In my case I needed to be more specific than “#content .entry-title a“. By adding the h2 to the .entry-title rule, I achieve that because h2.entry-title only will affect h2′s with the entry-title class, while just .entry-title can affect any tag on the page with that class.

The fact that only the h2′s on my page have .entry-title is irrelevant. The HTML doesn’t actually matter in regards to specificity. A rule is more specific based on what it can affect, not on what it actually affects.

So by making my rule more specific, I can override the color of those title’s in my own CSS file separately, and without changing anything about the parent theme.

Overriding Templates

Child themes are not limited to overriding only styling, although in many cases that may be the only customization you need. Best to stick with the rule of the minimum; try to make the most minimal change you can make to accomplish what you want to accomplish. But if you do want to change the way some of the templates work, you can do that too.

All you have to do is to copy the specific template file you want to alter from the parent theme into the child theme’s directory, then make your changes. The way WordPress works is when it looks for some template file, it looks in the child theme first, then it goes to the parent theme if the file it wants isn’t there.

Note that you’re not limited to overriding existing files in the parent. The entire Template Hierarchy applies to child themes too, so if you want to define a category.php file for Category Templates, and the parent theme doesn’t have that file, then you can create a new one in your child and it will be used. You will probably still want to start out with some existing template from the parent though, so look at the Template Hierarchy to see which template the parent is using for your case. The index.php is the usual suspect in these cases, so you can probably just copy that to the child theme and rename it to the template file you want it to be.

Overriding Functions

One exception to the overriding mechanism of child themes has to do with the functions.php file. In a child theme situation, both functions.php files from both themes are loaded. This is necessary because elements of your parent theme might require pieces of the functions.php file to be loaded. This can make overriding functions in the parent theme tricky unless it’s written to allow you to do just that.

The key to this is that the functions.php file of the child theme is loaded first. So if the parent theme is written in a manner WordPress calls “pluggable“, then you can override those functions.

In the twentyten theme’s functions.php file, several of the functions are defined like this:

if ( ! function_exists( 'twentyten_admin_header_style' ) ) :
function twentyten_admin_header_style() {
...
}
endif;

That is a pluggable function. Basically, before it defines the function, it checks to see if the function is already defined. If the parent theme uses this mechanism, then a child theme can override this function by simply defining a function of the same name first. So all you have to do to change it is to copy the function into your child’s functions.php file and make your changes. When the parent theme loads, it will see that you already defined the function and continue on.

Another way to override things is through the normal WordPress action and filter hook mechanisms. If a theme’s functions.php file uses those, then you can simply add your own hooked functions with different names. However, because the child’s functions.php file loads first, it can’t actually unhook things defined by the parent theme.

The way to get around this is to use the after_setup_theme action hook. This action is called immediately after both functions.php files are loaded.

For example, if I look at the twentyten theme, I’ll find this:

function twentyten_excerpt_length( $length ) {
	return 40;
}
add_filter( 'excerpt_length', 'twentyten_excerpt_length' );

I don’t want that, I want my excerpts to be 55 words instead. So I add this to my functions.php file:

function my_excerpt_length( $length ) {
	return 55;
}
add_filter( 'excerpt_length', 'my_excerpt_length' );

Whoops! It doesn’t work. Why not? Because I didn’t remove twentyten’s hook, and its filter is overriding mine. So I have to add this too:

function my_undo_hooks( $length ) {
	remove_filter( 'excerpt_length', 'twentyten_excerpt_length' );
}
add_action( 'after_setup_theme', 'my_undo_hooks' );

And then it works. I’ve added my filter, and removed the one in twentyten. Voila.

Programmer Note

In a WordPress theme you’ll often find references to “stylesheet_uri” and “stylesheet_dir”. You’ll also find references to “template_uri” and “template_dir”. Normally, these are the same thing. In a child theme case, they’re not. Stylesheet refers to the child theme. Template refers to the parent theme. This is an important distinction that you’ll want to make when creating your theme. You should probably use stylesheet in most cases, except for when you need to specifically refer to the parent (for image URL creation and such).

Conclusion

Child themes are a very good way to survive theme upgrades, and if you’re using a well supported theme, these are likely to become more common. It’s still perfectly safe to modify your theme directly (except for twentyten! Normal WP upgrades overwrite twentyten), but it’s always a good idea to keep your customizations separate. They’re a lot easier to manage that way.

Shortlink:

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 http://example.com/files/2010/whatever.jpg 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.

Shortlink:

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>
<div class="next-img">
<?php echo next_image_link('themename-nav-thumbnail'); ?>
</div>

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.

Shortlink:

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.

Conclusion

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.

Shortlink: