The YASnippet package for Emacs has some pretty awesome power for the developer, especially when you utilize the power of Emacs Lisp.

YASnippet was inspired by TextMate, which was inspired by Emacs, in a highly-out-of-equilibrium whirlwind of self-referential creativity.

The screencast above uses a set of snippets I originally took from this WordPress TextMate bundle, created by Shawn Parker and Gordon Brander

The first snippet in the screencast illustrates YASnippet’s mirrors with transformation, in a WordPress plugin template. The snippet calls Emacs Lisp functions as the plugin name is filled in to create the plugin URI, the “namespace” (used here as a prefix for function and variable names), and the primary class name for the plugin.

The second snippet writes a function skeleton, then calls Emacs Lisp at the end to move the generated function outside the current scope into a correct position in the file. This snippet uses YASnippet’s fields with transformations syntax, but to do a sneaky thing: not transform the field, but move a region of generated text!

Following is the code for the snippets shown in the screencast, with no commentary. So pipe up in the comments if you’re curious about how something works!

# -*- mode: snippet -*-
# name: WP Plugin
# key: plugin
# --
/*
Plugin Name: ${1:Plugin Name}
Plugin URI: http://${2:dynapse.com/plugins/}${1:$(gjg/sanitize text)}/
Description: ${3:Description}
Version: ${4:1.0}
Author: ${5:Gregory Grubbs}
Author URI: http://${6:gregorygrubbs.com/}
Namespace: ${1:$(gjg/acronyminize text)}_
*/
 
class ${1:$(gjg/whitespace-to-underscore text)} {
	/**
	 * constructor for $1
	 *
	 * The constructor is responsible for registering all hooks used
	 * by this class as as WordPress plugin
	 */
	function __construct() {
		 $0
	} // constructor
 
}
$${1:$(gjg/acronyminize text)} = new ${1:$(gjg/whitespace-to-underscore text)}();

Next, the add_action snippet, which moves a generated function at the end:

# -*- mode: snippet -*-
# name: add_action
# key: add_action
# --
add_action('${1:init}', array($this, 'my_${2:$1}'));
${3:$$(gjg/move-next-sexp-past-current-scope)}
function my_$1 () {
}

And finally, (some of) the Emacs Lisp functions that the snippets call:

(defun gjg/acronyminize (text &optional do-capitalize)
  "Make an acronym from the text 
do-capitalize: t means run text through capitalize function, nil will respect CamelCase
"
  (save-excursion
    (setq case-fold-search nil)
    (downcase
     (replace-regexp-in-string
      "[^A-Z]" ""
      (if do-capitalize (capitalize text) text) nil t))))
(defun gjg/move-next-sexp-past-current-scope ()
  "kill sexp following point, move past current scope/sexp/function"
  (beginning-of-line)
  (let ((beg (point)))
    (re-search-forward "^[ \t]*function[ \t]+[^}]+?}" (point-max) nil)
    (mark-defun)
	(kill-region (point) (mark)))
  (forward-line)
  (yank)
  (indent-region (mark) (point)))

Emacs file and directory browsing

Emacs has Dired, a great method for browsing directories; especially in combination with ido-mode, I prefer it to Windows Explorer, OS X Finder, Gnome Nautilus, or anything else I’ve used over the decades to browse file systems. You can quickly begin entering paths, and Dired helps you with directory and file name completion.

As you browse directories, emacs lets you bookmark any path you may visit again. A very cool feature of emacs is the wide variety of shell-based modes: shell, term, interactive SQL, version control, recursive grep, and more. When you are looking at a Dired buffer and invoke any of those commands, the shell is started in the directory you are looking at.

TRAMP: powerful remote file server access

An emacs user will eventually discover that Dired becomes even more powerful with the built-in power of TRAMP (Transparent Remote (file) Access, Multiple Protocol). This extends directory path syntax to include FTP, SSH, Rsync and other protocols for accessing remote files.

An example of accessing a remote file on my development server smeagol from my laptop:

/ssh:gregj@smeagol:work/client1/web/index.php

A directory on an FTP server is accessed the same way:

/ftp:ftpuser@ftp.example.com:

Even sudo is considered a ‘protocol’; so to gain root access without leaving the comfort of your emacs session, use

/sudo::/etc/hosts

Emacs even helps you browse remote servers, providing the same name completion you get on your local directories.

The amazing combo of TRAMP and shell commands

As wonderful as all this is, we are still in the realm of “mere” GUI editors that can browse remote servers. But we are dealing with emacs, the superset of all editors, so we expect even more.

Imagine we are looking at a directory on a remote server at /ssh:myuser@remote.com:web/public_html, and decide to type

M-x shell

What happens? Why, emacs looks at our current directory, sees that it is a TRAMP remote path, and just does the Right Thing™: in this case, invokes ssh, sets the directory on the remote server to ~myuser/web/public_html, and sets us at the shell prompt.

Similarly, if we invoke version control (vc-dir, for example), or recursive grep (rgrep), or most other shell-based commands, emacs will open a secure shell first, then run the vc command (svn, git, etc) or grep on the remote server!! So for example, if I innocently invoke rgrep at the root of a remote WordPress installation, the grep command looks through all the files from the remote server. If on the other hand I were accessing the server using something like SSHFS, all those files would be transferred to my local machine first and then searched!

Some examples

I’ll save my favorite uses of this magic called Dired with TRAMP for last. I often need to access a development system or a live WordPress installation remotely. To access the SQL client, I found I often had to browse for the WordPress config file, open it, search for the database access info, open a SQL session using M-x sql-mysql and fill in all the prompts to authenticate to the MySQL server. It’s great that emacs with TRAMP starts a shell on the remote machine, and initiates the mysql client on that machine. But emacs allows you to do damn near anything you can imagine, so I realized I could write a function that does the following:

1. Looks for wp-config.php in the current directory
2. If not found, moves up a directory until it either finds the file or reaches the root of the filesystem
3. If found, opens the config file and parses the database authentication parameters
4. Feeds those parameters to the sql-mysql function and
5. plops me into the MySQL prompt all logged in and ready to go!

Another example: my iPod Touch has an SSH server running on it (don’t ask me how it got there). I have discovered that many apps use SQLite to store their data. I have been losing weight lately, and have been using the excellent Lose It! app to track my meals and exercise. The app gives me nice weekly summaries of my caloric intake, but does not give a weekly summary of my aerobic exercise. Here’s how I get that information now:

1. I have a nice bookmark to the Lose It! application directory at
   /scpc:mobile@172.16.17.118:/var/mobile/Applications/C6503545-700B-4395-9C8B-FE5B75CF6CD8/,
   so I hit the Return key on that bookmark and wait for Dired to show me the files there.
2. Browse to the Documents directory, wherein is stored the database for my personal history
3. Invoke M-x sql-sqlite and enter the database file UserDatabaseV1.sql (using dabbrev as a shortcut)
4. Wait for the SQLite prompt to appear, and run a lovely little SQL query using a YASnippets shortcut:

SELECT date('2001-01-01', '+' || Date || ' day', '-1 day', 'weekday 1', '-7 day') AS Weekdate, strftime('%W',date('2001-01-01', '+' || Date || ' day', '-1 day')) AS Week,   ExerciseName, ExerciseCategoryId, SUM(Minutes), SUM(CaloriesBurned)   FROM ExerciseLogEntries  GROUP BY Week;

Summary

I hope that this post gives an idea of the power of TRAMP on emacs. It should at least explain the occasional ecstatic post you may see from your geekier tweeps.

As a bonus, here’s what the above examples look like in use: it’s unbelievable how fast emacs makes you after a quick 15 years of study.

And here’s my emacs lisp code that opens up a SQL prompt for any WordPress installation. To use, eval the code and invoke M-x gjg/sql-mysql-wordpress

(defun gjg/parse-wp-config-db (wpconfig-path)
  "Read in and parse the DB settings from a WordPress config file; binds 'global' vars for use by sql-mode"
  (save-excursion ;; will restore current buffer and default dir afterwards
      (set-buffer (get-buffer-create (generate-new-buffer-name " wp-config.php")))
  (insert-file-contents wpconfig-path)
  ;; in regex: subexpr 1 is variable name, subexpr 3 is value: DB_{HOST,NAME,PASSWORD,USER}
      (while (search-forward-regexp "define\s*(\s*['\"]\\(DB_\\(HOST\\|NAME\\|PASSWORD\\|USER\\)\\)['\"]\s*,\s*['\"]\\([^'\"]*\\)['\"]\s*)" (point-max) 42   )
  (cond
  ((equal "DB_HOST" (match-string-no-properties 1))
  (setq sql-server (match-string-no-properties 3)))
  ((equal "DB_NAME" (match-string-no-properties 1))
  (setq sql-database (match-string-no-properties 3)))
  ((equal "DB_PASSWORD" (match-string-no-properties 1))
  (setq sql-password (match-string-no-properties 3)))
  ((equal "DB_USER" (match-string-no-properties 1))
  (setq sql-user (match-string-no-properties 3)))))
  (kill-buffer )))

  (defun gjg/sql-mysql-wordpress ()
  "Find WordPress config file in current tree, log into WP database if found."
  (interactive)
  (let ((mypath (locate-dominating-file default-directory "wp-config.php")))
  (if mypath
  (progn
  (gjg/parse-wp-config-db (concat mypath "wp-config.php"))
  (pop-to-buffer (sql-connect-mysql))
  (setq sql-interactive-product 'mysql)
  (setq sql-buffer (current-buffer))
  (sql-interactive-mode)
  (let* ((match (string-match (nth 0 tramp-file-name-structure) mypath))
  (myformat (if (eq nil match)
  (format " WordPress: local; %s; dbhost %s "
  mypath
  sql-server
  )
  (format " WordPress: Remote %s@%s %s; dbhost %s "
  (match-string (nth 2 tramp-file-name-structure) mypath)
  (match-string (nth 3 tramp-file-name-structure) mypath)
  (match-string (nth 4 tramp-file-name-structure) mypath)
  sql-server))))
  (setq header-line-format myformat))
  )
  (message "Did not find wp-config.php in current path"))
  ))

LocalWords: Dired emacs SQL Rsync smeagol pre rgrep WordPress MySQL iPod
LocalWords: SQLite

I’m kinda loving on WordPress MU. One of my recent projects required building web sites that pulled from a shared database. WordPress MU allowed me to create a one-button website builder for my client. WordPress MU calls them blogs, but my client will map a unique domain to each blog, and, well, doesn’t use them as blogs at all. So I’m calling them sites here.

By filling in three fields and clicking a button, my client creates a website that

• Associates metadata with the site that specifies filter criteria to select records from the shared database
• Sets the permalink structure for the new site to a custom setting
• Creates a key category for the new site, one that is used for the posts generated in a later step
• Sets the theme
• All the initial pages are created, including content. The “slug” is set specifically to support the URL structure we want. Page template is also set here because our design calls for a hierarchy of pages.
• If the PageMash plugin is active (it is auto-activated for all new blogs using Plugin Commander), certain pages are hidden, and a specific order is set so that page navigation comes out looking good
• The front page is set, because we are creating CMS sites, not blogs
• Several hundred posts are generated out of the underlying shared non-WPMU database tables

All of this takes something like 20 seconds, at which point the admin can visit the new site as a subdomain.  The theme has been applied, navigation works correctly, it is beauty.

Here’s how it is done in code.  All you need to do is register a function for the action hook that WordPress MU runs when a new blog is created.

function mypp_initialize_blog($blog_id) {
  global $wp_rewrite;
 
  // first, switch to the new blog; we will undo this at the
  // end of the function with restore_current_blog()
  switch_to_blog($blog_id);
  // add a blog option, here a filter with a default value
  add_option($blog_id, 'campus_selection_criteria', "CampusStateID='CA'");
  // Set a custom permalink structure
  $wp_rewrite->set_permalink_structure('/%category%/%postname%');
  $wp_rewrite->flush_rules();
  if (function_exists('wp_create_category')) {
      wp_create_category('schools');
  }
 
  // switch theme - this one specifies a child theme
  switch_theme('corporate', 'tweaked-corporate');
  // Prepare options used by the pageMash plugin, auto-activated for new sites
  if(!is_array(get_option('exclude_pages')))
    $excludePagesList=array();
  else
    $excludePagesList = get_option('exclude_pages'); //if it's empty set as an empty array
  // add pages to support the basic page structure
  // NOTE: the full code is not shown, standard use of wp_insert post
  // for each page:
  $newid = wp_insert_post($postdata);
  if ($newid && !is_wp_error($newid)) {
    add_meta($newid);
    if ( IWANTOEXCLUDETHISPARTICULARPAGEFROMNAVIGATION )
      $excludePagesList[] = $newid;
    if (THISPARTICULARPAGE == 'home') {
      update_option('show_on_front', 'page');
      update_option('page_on_front', $newid);
    }
  } else {
    // error handling if insert post failed
  }
  // end for each page
  update_option('exclude_pages', $excludePagesList);
  // now generate posts for schools from the shared database
  createSchoolAsPost('', $blog_id);
  // we're done! restore our initial blog
  restore_current_blog();
} // function mypp_initialize_blog
 
add_action('wpmu_new_blog', 'mypp_initialize_blog');

OK, this one is obscure. I only post about what I can’t find on Google!

Until recently it has been possible to run command-line PHP scripts that include wp-config.php or wpmu-settings.php, in order to give those scripts access to WordPress globals like $wpdb, functions such as wp_insert_post etc.

These scripts worked with WordPress-MU until recently — now the scripts just exit with no output.

The reason? WPMU now initiates a redirect in the bootstrap process (search for ‘header( “Location: “‘ in wpmu-settings.php). A browser can follow that redirection, but a command line script cannot. So, if you want to initiate scripts that run from the command line, you will have to get the web server involved by invoking a text browser such as curl, wget, or links.

It’s best not to force your scripts to figure out where to find wp-config.php anyway. I have taken to using a method suggested in this thread, as shown in the code sample below. The good news is, you know that your script will work the same whether initiated from a plugin in a graphic browser, used in an Ajax call, or initiated from cron or the command line shell.

So instead of kicking your script off with something like

/usr/bin/php -q myscript.php

You will create the script as a proper plugin and do something like

/usr/bin/curl -d mypp_cmd=status http://mywpmusite.com

Sample plugin code used for the above example follows. The prefix for the functions is ‘mypp’, which of course stands for ‘MY Plugin Prefix’ to create a unique namespace. The code below returns results as JSON encoded, and calls die()/exit() at the end to prevent an entire page being created. For log files run from cron, you may choose to return plain text instead.

  /**
   * Add a query var for this plugin
   * This allows Ajax programs to operate without requiring file paths
   * Instead, Ajax functions look for the query var 'mypp_cmd'
   */
  function mypp_query_vars($qvars) {
    $qvars[] = 'mypp_cmd';
    return $qvars;
  } // function mypp_query_vars
 
  /**
   * Handle AJAX requests in the template_redirect action
   * We recognize our requests from the query var 'mypp_cmd'
   * Here we allow GET requests using $_REQUEST; to restrict to POST, use $_POST instead
   */
  function mypp_template_redirect() {
    global $wpdb;
    $cmd = get_query_var('mypp_cmd');
    $response = array();
    if ($cmd) {
      switch($cmd) {
      case 'status':
	$response['status'] = array('success' => true,
				    'message' => 'Sample status message');
	break;
      default:
	$response['status'] = array('success' => false,
				    'msg' => 'Unknown command',
				    'cmd' => $cmd);
	break;
      } // switch $cmd
      header('Content-type: text/x-json; charset=utf-8');
      print utf8_encode(json_encode($response));
      die();
    } // $cmd is set
  } // function mypp_template_redirect
 
add_filter('query_vars', array($this, 'mypp_query_vars'));
add_action('template_redirect', array($this, 'mypp_template_redirect'));

use the hook!

It is easy to go in and hack the core WordPress files to change the hard-coded number, but I wanted to find a way to do it with a hook.  That way, I could one day change the number of posts shown using controls in the interface.

Though there is no filter provided for the number of posts displayed, I hit upon a method of doing this which I would like to share.  Perhaps someone will point out a better way, but for now this is making me happy

The trick is to hijack the query string just for the query that produces the table of posts.  Here’s what I did:

/**  * Extend the number of posts displayed in the Edit Posts  */ 
function dapl_query_string($query_string) {   
    global $pagenow;   
    if (is_admin() && $pagenow == 'edit.php') {
        $query_string = str_replace('posts_per_page=15', 'posts_per_page=100', $query_string); 
    }
    return $query_string; 
}  
add_filter('query_string', 'dapl_query_string');

When new web sites are generated by my client, I wanted the experience to be painless; a one-button ready-to-go web site.

It turns out there is an action hook (of course there is!) when a new blog is created.  So let’s get down to the nitty gritty and see how to implement it.

I wanted to create a property that would apply to the new web site, which would allow my client to limit what data gets displayed on that site.  I also wanted to generate the basic set of pages that I am using to support the sites’ URL structure.  Each page has a unique template that gives it some special navigation and content mojo.

So first I set the site-global option:

add_blog_option($blog_id, 
	        'campus_selection_criteria', 
                "CampusStateID LIKE '%'");

Now for the pages with their templates.  In order to let wp_insert_post know which blog to use, we use a handy function call:

switch_to_blog($blog_id);

We will also need to specify the theme we are using so that the starting theme will be selected and the templates will be correctly associated.

I can then create the pages as I would in Wordpress-non-MU.  The final step is to call add_action() to hook this code into the blog creation event.

Here is the code in its entirety

function dscp_initialize_blog($blog_id) {
   add_blog_option($blog_id, 
                   'campus_selection_criteria', 
                   "CampusStateID LIKE '%'");
   switch_to_blog($blog_id);
   // switch theme
   switch_theme('thematic', 'mychildtheme');
   $postdata = array('post_parent' => 0,
   'post_status' => 'publish',
   'post_title'   => 'DESCRIPTIVE TITLE',
   'post_name'  => 'descriptive-title', /* the slug */
   'page_template' => 'template-whatever.php',
   'post_type'   => 'page');
   $newid = wp_insert_post($postdata);
   if ($newid && !is_wp_error($newid)) {
      add_meta($newid);
   } else {
      // your error handling code
   }
}
 
add_action('wpmu_new_blog', 'dscp_initialize_blog');

Now theoretically I should simply be able to use the svn merge command in a working directory. But I have encountered serious problems, including file corruption warnings, when using svn merge in an actively developed working directory. Additionally, svn merge will delete files and directories that you added to the core Wordpress install.

The method outlined here will be safe even if you have hacked core Wordpress files, as long as you are very careful in constructing your rsync command.

1. Import and tag the latest Wordpress release into the repository

   cd /tmp
   tar zxf /path/to/archive/wordpress-2.6.2.tar.gz
       OR
   unzip /path/to/archive/wordpress-2.6.2.zip
   svn import -m "Vanilla 2.6.2" wordpress file:///repository/wordpress/tags/2.6.2

2. Remove the directory in /tmp

   rm -rf /tmp/wordpress

3. Check out a fresh copy of your Wordpress project, and export a copy of the latest vanilla Wordpress

   cd /tmp
   svn co --ignore-externals file:///repository/wordpress/projects/myhappyblog
   svn export file:///repository/wordpress/tags/2.6.2 wordpress-2.6.2

4. Do a dry run of rsync, starting with something like the following

   rsync --dry-run -av --delete --svn-exclude --exclude '.svn/' --exclude favicon.ico wordpress-2.6.2/ myhappyblog/|less -SiX

5. Now begins an iterative process – carefully examine the output from the above rsync dry run, paying special attention to files that will be deleted, since those will show you directories and files you have added. Add those directories or files as required using multiple ‘–exclude’ options. Here is an example from a recent upgrade I did:

   rsync --dry-run -av --delete --svn-exclude --exclude '.svn/' --exclude favicon.ico --exclude 'images/' --exclude 'wp-content/plugins/podpress' --exclude 'wp-content/themes/sandbox' --exclude 'wp-content/uploads' wordpress-2.6.2/ myhappyblog/|less -SiX

6. Once you are satisfied that you are not asking rsync to delete files and directories you need, run the command without ‘–dry-run’

   rsync -av --delete --svn-exclude --exclude '.svn/' --exclude favicon.ico --exclude 'images/' --exclude 'wp-content/plugins/podpress' --exclude 'wp-content/themes/sandbox' --exclude 'wp-content/uploads' wordpress-2.6.2/ myhappyblog/

7. Now change to your project working directory and look at the output of ’svn stat’, here including sample output:

   svn stat
   
   M      wp-login.php
   M      wp-includes/post.php
   M      wp-includes/version.php
   M      wp-includes/query.php
   M      wp-includes/formatting.php
   M      wp-includes/pluggable.php
   M      wp-includes/widgets.php
   M      wp-settings.php
   M      wp-admin/includes/template.php
   M      wp-admin/includes/image.php
   M      wp-admin/import/textpattern.php
   M      wp-admin/css/press-this-ie.css

8. (conditional) In major upgrades, there will be Wordpress core file deletions and additions. Handling these will require an extra couple commands, shown below. These commands are only necessary if there are additions and deletions.

   # tell repository about deleted files that were removed by rsync
   svn remove --force `svn stat |egrep '^\!' | cut -d' ' -f2-999`
   # add new files to repository
   svn add `svn stat|egrep '^\?' | cut -d' ' -f2-999`

9. You may choose to look through all the changes, or you may decide that the files that have been changed are safe (ie, unhacked Wordpress core files).Now you are ready to commit the changes to the repository.

   svn diff | less # optional
   svn commit -m "Upgraded to Wordpress 2.6.2"

10. At long last, you can go to the working directory where you are actively developing, and update that. Once you have tested thoroughly, you will be ready to update your live site (possibly with the same ’svn update’ command).

    cd /path/to/my/development/myhappyblog
    svn up

11. Repeat from Step 3 for each of your SVN-managed Wordpress projects!
12. Drink. Pray that Wordpress is not upgraded for at least another 6 months.