=== Ping.fm Custom URL === Contributors: mjacob Tags: ping.fm, pingfm, wp-pingfm, status, custom url, social networks Requires at least: 2.8 Tested up to: 2.9.2 Stable tag: 1.3.3 Receives blog entries, microblog entries, and status updates via Ping.fm's Custom URL feature and posts them to your self-hosted WordPress blog. == Description == = Minimum System Requirements = * WordPress 2.7 * PHP 5.1.0 * MySQL 4.0 = More Features Than a Ford Model T = * Works with Ping.fm's Custom URL feature to collect blog entries, microblog entries, and status updates and post them to your blog. * Status updates are posted to the sidebar and displayed with a widget. A standard template tag is also provided for those of you who are anti-widget. * The sidebar widget is customizable with the number of status updates to show and an optional string to prepend all updates with (e.g. you might use your first name if all your status updates begin with a verb like mine do: Matt is...). Sensible CSS and examples are provided for you to customize the look and feel of your widget. * Provides an RSS feed and permalinks for your pings so that you can share them with the rest of the world. * Blog entries and microblog entries can have certain metadata applied to them automatically. You can set the author, category, tags, and post status (published or draft) for all incoming pings. * Your blog is safe from updates by random outsiders thanks to a highly random and highly secure authentication token that only you know. * All the cool features of Ping.fm: post to your self-hosted WordPress blog using SMS, IM, email, desktop gadgets, mobile apps, etc. == Installation == = Upgrading to a new version? Read This! = Upgrading is simple! Here are the steps you should take: 1. Disable/deactivate the plugin. 2. Delete the old version of the plugin from your server. You can simply overwrite the old files if you're more comfortable with that, but deleting is more foolproof and more dangerous (and therefore, more exciting). As of 1.1.0, the `ping.php` file is no longer necessary, so you can safely delete that one for sure. 3. Follow the installation instructions to re-install. Basically, upload the contents of the .zip file under your `/wp-content/plugins/` directory. You can also use the new plugin installer that was added in WordPress 2.7 (Admin > Plugins > Add New). 4. Activate the plugin. 5. Done! Head over to the plugin's settings page and adjust any new settings that might have been added. (Sometimes there won't be any, but it doesn't hurt to check.) Finally... for those about to ping, we salute you! = Installing a Fresh Copy = 1. Extract the .zip file you downloaded to a directory under `/wp-content/plugins/` (something short and sweet like `pingfm` or `wp-pingfm` will work nicely). This directory probably doesn't exist yet (unless you're upgrading), so you'll need to go ahead and create it yourself. 2. Activate the plugin through the 'Plugins' menu in WordPress. 3. Go to WordPress Admin > Plugins > **Ping.fm Settings** to get your custom URL and then follow the instructions on that page to link up with your Ping.fm account. Essentially, you just want to copy and paste the given URL into your Ping.fm Custom URL settings. Feel free to change any other settings on that page (it is *your* blog, after all). If you need to specify a default category for incoming posts, and that category doesn't exist yet, go and create it first, and then come back and select it. 4. Head over to WordPress Admin > Design > **Widgets** and add the 'Ping.fm' widget to your sidebar. If you click the 'Edit' link in the activated widget, you'll be able to configure a whole slew of options to your liking. If your theme is non-widgetized, or if you just have a bias against widgets for some reason, you can use the `wp_pingfm_status()` template tag instead. More information about that is on the page that bears the same name. 5. Post something to your Ping.fm account and let the good times roll! If nothing shows up at first, it's probably because you haven't posted anything yet. (It seems obvious, but you'd be surprised.) Only updates made *after* you install the plugin will show up, and even then, only after you've told Ping.fm to post to your custom URL. And, on the Ping.fm side, be sure to check the appropriate boxes for the kinds of updates you'd like to send to your custom URL. Finally, if you don't think your status updates are showing up, make sure the widget has been added to your sidebar and that you've saved the changes. 6. Buy the developer of this plugin a pint! He's partial to Guinness, though Fat Tire, Negra Modelo, Stella Artois, and Blue Moon garnished with an orange are also acceptable. = Creating the Database Table Manually = During installation, the plugin attempts to create a new database table for you automatically. This is necessary because we need a place to store all those pings you'll soon be shooting over to the system. Sometimes, the table can't be created due to insufficient privileges on your WordPress database user account. If that's the case, you can execute the following SQL as a privileged user (be sure to substitute `wp_` for the actual prefix you're using if it's different): CREATE TABLE `wp_pingfm` ( `id` int(10) unsigned NOT NULL auto_increment, `status` text NOT NULL, `timestamp` timestamp NOT NULL, PRIMARY KEY (`id`) ); = Using mod_rewrite for a Cleaner URL = **Important!** This is no longer necessary as of version 1.1.0, but it's included here for historical reasons. So, you think the default URL generated by this plugin is long and ugly, huh? Well, I can't really blame you, and that's why I use `mod_rewrite` to shorten mine up a little. Teaching `mod_rewrite` is way, way, *way* outside the scope of this document, but I'll give you the code I use and you can figure out the rest on your own. Deal? Note: I do this inside a `VirtualHost`, but you can probably adapt it to work with per-directory settings (.htaccess) by removing the leading slash in the search path. If what I just said doesn't make any sense at all to you, you should probably just sit down on the couch and enjoy a Coke. RewriteEngine On RewriteRule ^/p/([A-Za-z0-9]{32})$ /wordpress/wp-content/plugins/pingfm-custom-url-status-updates/ping.php?k=$1 [L] That'll make it possible to use a new URL that looks like this: http://example.com/p/ae01e15d6ac3769ad5048a36e47ec32e == Frequently Asked Questions == = Can I change the number of status updates displayed? = Yes, of course you can! Go to your sidebar widgets and hit the 'Edit' link for the Ping.fm widget. This is all mentioned in the installation instructions, but I can see that you're the impatient type that never reads anything. I bet you didn't read the owner's manual for your car, either, huh? = Why am I not seeing any updates in my sidebar? = Well... have you posted any yet? Only status updates posted to Ping.fm *after* installing the plugin and *after* configuring the custom URL will show up on your blog. If you're confident you've done everything right, there might be something else going on. You might have discovered a bug, or an "undocumented feature" as we software engineers like to call them. Send me some sugar at and I'll see what I can do. = Why aren't pings coming through to my site? = Read the question immediately preceding this one once more. Done? Now go through the checklist below and make sure everything is kosher: * Are you using PHP 5? I think the exact minimum version is 5.1.0, but the higher, the better. You can't go wrong with something newer. * Is your site blocked off from others using HTTP Basic Authentication or some other method? Do you have firewall rules restricting users to a certain IP range? * Are you using any WordPress plugins that limit outside access? I've seen problems related to the Bad Behavior plugin in the past. * Can you hit the "secret posting URL" from your browser? You should get an error message, which is a good sign that the plugin is installed and working. * Do you have some boxes checked over at the [Custom URL Settings](https://ping.fm/custom/) page? Next to *Use for:*, you need at least one of those options selected (preferably all three). * Under the main [Ping.fm Service Settings](http://ping.fm/settings/), is the box checked next to the *Post messages to Custom URL* option? This is important. * If you're only posting status updates to the widget and not as full posts, is the widget activated and placed somewhere? = Can I post blog entries or pages from my Ping.fm account? = The original answer was a defiant "get off my lawn, you damn kids!" That lasted for a whole point release. By popular demand---and thanks in no small part to Rocco and Vinny, who were sent to convince me---the ability to post blog entries has been available since 0.9.2. Support for creating pages might be added in a future release. Give the people want they want, right? = Will this plugin work with WordPress.com blogs? = Definitely not. That would be goofy. Plus, Ping.fm already has [support](http://ping.fm/blog/wordpress-bots-you-betcha/) for WordPress.com hosted blogs. = Can you add feature X, Y, and Z? And Q? And L? = I *could* add all kinds of features, but the real question is whether I *should*. The intent and operation of this plugin was meant to be simple, but go ahead and pitch your feature idea to me. If it's not too outrageous and I think others would benefit from it, I'll probably add it to a future version of the plugin. == Screenshots == 1. Behold, the settings page in all its glory. Now with 100% more Ping.fm logo than before! 2. Some more settings. There's a lot to configure if you're into that sort of thing, but the defaults were designed to work for most people. 3. The illustrious status widget. You feed it status updates, it feeds widgety goodness to all your blog's readers. == Changelog == = 1.3.3 = * Fixed timezone handling throughout the plugin. Be sure to set a named timezone (the city closest to you) in *General Settings*, or else your timestamps might not be correct. * Fixed invalidly-nested `` element in the widget. * Minor code beautification. Very minor. = 1.3.2 = * Further tweaking of the way rewrite rules are filtered and flushed. In some cases, rewrite rules weren't taking affect immediately after a brand-new installation of the plugin, but that should be remedied with this release. = 1.3.1 = * Tweaked the rewrite rules a little more. There were some edge cases where other things would overwrite our rules, but that should be fixed now. = 1.3.0 = * Added support for displaying images associated with pings. A corresponding option has been added to the settings page. * Added specific check for PHP 4 to prevent code from even being parsed if an insufficient version of PHP is found. * Failure for PHP 4 now handled gracefully instead of with a syntax error. * Moved flushing of rewrite rules to only happen on plugin activation and not on every page load. This should have a noticeable positive impact on performance. The only downside is that the plugin will have to be deactivated and reactivated if pretty permalinks are enabled (a worthy trade-off in my opinion). * Cleaned up the code in various places to make it more readable (especially with regard to the error message pseudo-constants). = 1.2.1 = * Primarily a documentation release. Lots of stuff in the README was clarified, fortified, beautified, and just plain shifted around. * Fixed a small bug related to a new option that was added in 1.2.0. After saving the options twice, the problem would have fixed itself anyway. * Added screenshots for the benefit of the WordPress Plugin Directory. * Moved the changelog off of my site and into the Plugin Directory to give people a more central point of contact. = 1.2.0 = * Added option to force all status updates to become actual posts. * Added option in widget to "permalinkify timestamps" (archive page is editable via `tmpl-single.php`). * Invented new English word: *permalinkify*. * Tried to make the settings page clearer and easier to understand. * Did some code housekeeping. * Added Ping.fm logo to settings page. = 1.1.0 = * Complete code rewrite (PHP 4 procedural to PHP 5 OO) and new way of storing settings in the database. * Did away with external `ping.php` file for receiving updates. * Added native WordPress URL hooks and internal support for `mod_rewrite`. * Added RSS feed containing 20 most recent status updates. * Added archive/permalink pages for individual pings (mostly in conjunction with RSS feed, but can be used elsewhere as well). Page is templated for easy customization. * Provided interface for user-supplied widget styles (CSS). * Widget HTML/CSS makes more sense. Widget container has an ID of `wp-pingfm` and a class of `wp-pingfm-widget`. * Added `wp_pingfm_status()` for people using non-widgetized themes. See *Other Notes* section for docs. = 1.0.1 = * CSS is now targeting `#pingfm` in a less specific way (because it broke on themes with multiple sidebars). * Fixed random bug only seen in WebKit where a space preceding a status update was considered significant whitespace. (Don't ask me---I don't build it, I just code to it.) = 1.0.0 = * The first non-beta release! * Modified `CREATE TABLE` for installer after reports of it failing on MySQL versions < 4.1. * Added check for widget to determine if database table was created properly. * Tweaked a few textual things here and there. = 0.9.7 = * This version was never released publicly and the changes made for it were rolled into 1.0.0. = 0.9.6 = * Added [this page](http://mattjacob.com/pingfm-wordpress-plugin) as a home base for the plugin on my site. * Made the README more readable (hopefully). The documentation should be easier to understand now. * Fixed the `mod_rewrite` example to include the `[L]` flag. The entire line didn't get copied from my conf file the first time around. = 0.9.5 = * Minor textual changes and a speed enhancement (eliminated a DB call using some crafty coding). = 0.9.4 = * Added widget options to specify colors used in injected style sheet (CSS). * Reorganized, streamlined, and beautified some code. = 0.9.3 = * Fortified README with some additional information and a `mod_rewrite` example for shortening the inevitably long URL. * The plugin now auto-detects the directory it's running from. Anything under `/wordpress/wp-content/plugins` should work reasonably well. If the WordPress Plugin Directory wants to create a really long folder structure, so be it. = 0.9.2 = * Added support for all types of Ping.fm updates. Blog and microblog posts now show up as actual entries in WordPress. = 0.9.1 = * The initial public release! After being hacked together with loving care during a couple late nights, the code finally sees the light of day. Cue angelic choir and bright background light... == Template Tag Usage == The function definition for the template tag is below. All parameters are optional. void **wp\_pingfm\_status** ( [ string `$title` [, int `$limit` [, string `$prefix` [, bool `$permalink` [, string `$id` ]]]]] ) Displays status updates in an unordered list (`