GeneralThreat.com » David http://www.generalthreat.com Dangerously different projects and code Sun, 19 Jan 2014 20:00:34 +0000 en-US hourly 1 https://wordpress.org/?v=4.2.38 Grappling with BP theme compatibility http://www.generalthreat.com/2013/08/grappling-with-bp-theme-compatibility/ http://www.generalthreat.com/2013/08/grappling-with-bp-theme-compatibility/#comments Wed, 28 Aug 2013 18:16:26 +0000 http://www.generalthreat.com/?p=104 Theme compatibility was introduced in BuddyPress 1.7 and allows site operators to use BP with any available WordPress theme. I have been way behind at updating BP Group Hierarchy to support theme compatibility, and as a result the Group Tree page looks like garbage when not using a theme that was written for BuddyPress. This post is about the effort to fix that.

If you are writing a normal BuddyPress plugin — one that adds pages rather than replacing them — see this excellent article (and this one too) at the BuddyPress Codex for info on how to implement BP theme compatibility.

First idea: Replace the content from directory_content with the group tree.

BP_Groups_Theme_Compat::directory_content() is the native BP function that displays the group list page. It’s called as a hook to a filter called bp_replace_the_content, so the content should be available for further filtering after it runs.

 
/**
 * (BP 1.7+) Filter the theme-compatibility content for a group tree page
 */
function bp_group_hierarchy_inject_group_tree() {
        add_filter( 'bp_replace_the_content', 'bp_group_hierarchy_buffer_group_tree', 100 );
}
function bp_group_hierarchy_buffer_group_tree( $content ) {
 
        ob_start();
 
        $loop_template = apply_filters( 'bp_located_template', locate_template( array( "tree/index.php" ), false ), "tree/index.php" );
        load_template( $loop_template );
 
        $output = ob_get_clean();
        return $output;
}
 
// If admin says only show the group tree (and we are in theme compat), do it:
add_action( 'groups_directory_groups_setup', 'bp_group_hierarchy_inject_group_tree' );

Result: No dice. Directory content is echoed to the screen, not returned to the filter chain. The group tree appears below the flat group list.

Workaround / second idea: Unhook the directory_content function so it doesn’t echo.

Here’s a snippet that I threw together testing this out (warning: closure => PHP 5.3+ !):

/**
 * (BP 1.7+) Filter the theme-compatibility content for a group tree page
 */
function bp_group_hierarchy_inject_group_tree() {
 
        add_filter( 'bp_replace_the_content', function() {
                /**
                 * Filter is hooked by a method of an anonymous instance...
                 * Search all registered listeners and pick off the BP_Groups_Theme_Compat one.
                 */
 
                global $wp_filter;
 
                foreach( $wp_filter['bp_replace_the_content'][10] as $key => $filter ) {
                        if( is_array( $filter['function'] ) && is_a( $filter['function'][0], 'BP_Groups_Theme_Compat' ) ) {
                                // Found and removing the native content
                                unset( $wp_filter['bp_replace_the_content'][10][$key] );
                        }
                }
 
        }, 1 );
 
        add_filter( 'bp_replace_the_content', 'bp_group_hierarchy_buffer_group_tree', 100 );
}
function bp_group_hierarchy_buffer_group_tree( $content ) {
 
        /* Same as before */
        return $output;
}
 
// If admin says only show the group tree (and we are in theme compat), do it:
add_action( 'groups_directory_groups_setup', 'bp_group_hierarchy_inject_group_tree' );

Result: Works well but is pretty awkward and brittle. It looks like the kind of solution I’d really like to avoid.

Let’s try something completely different. :)

Third idea: Use BP Theme Compat functions to replace the loop template file.

BuddyPress theme compatibility adds a lot of flexibility in how content is gathered for the site. I actually find the theme compatibility process much more intuitive to work with than the traditional template loading process.

Here are some highlights:

  1. bp_register_template_stack() lets you add a source of template files without filtering bp_located_template. Nice!
  2. bp_get_template_part() offers an easy way to switch out template files on the fly that is just not possible with load_template.

Is it really this easy?

SPOILER ALERT: This does not work for BP Group Hierarchy. But for most applications, I think this is the best way to conditionally replace a BP page with content from a plugin.

 
/**
 * (BP 1.7+) Add plugin templates folder to list of available template paths
 */
function bp_group_hierarchy_register_template_location() {
	return dirname( __FILE__ ) . '/templates/';
}
 
/**
 * (BP 1.7+) Replace groups/groups-loop with tree/tree-loop depending on user settings
 */
function bp_group_hierarchy_maybe_replace_group_loop_template( $templates, $slug, $name ) {
 
	if( 'groups/groups-loop' != $slug )
		return $templates;
 
	return array( 'tree/tree-loop.php' );
}
 
if( function_exists( 'bp_register_template_stack' ) )
	bp_register_template_stack( 'bp_group_hierarchy_register_template_location' );
 
// If admin says only show the group tree (and we are in theme compat), do it:
add_filter( 'bp_get_template_part', 'bp_group_hierarchy_maybe_replace_group_loop_template', 10, 3 );

Result: Works(!)
But when you trigger an AJAX request, the unaltered ID on the “All Groups” tab leads BP to load the flat list.
We also still need to hook the bp_located_template filter to find stylesheets, since we are enqueue-ing them instead of loading the contents inline.
It also also removes the ability to customize the “Group Tree” label, a feature added by popular demand.

Fourth idea: Use BP Theme Compat functions to replace the whole Groups list page.

This is really just a twist on how things are currently handled, and it looks like the current way will be around as long as BP-compatible themes bypass bp_get_template_part.

 
/**
 * (BP 1.7+) Add plugin templates folder to list of available template paths
 */
function bp_group_hierarchy_register_template_location() {
	return dirname( __FILE__ ) . '/templates/';
}
 
/**
 * (BP 1.7+) Replace groups/index with tree/index-compat depending on user settings
 */
function bp_group_hierarchy_maybe_replace_group_index_template( $templates, $slug, $name ) {
 
	if( 'groups/index' != $slug )
		return $templates;
 
	return array( 'tree/index-compat.php' );
}
 
if( function_exists( 'bp_register_template_stack' ) )
	bp_register_template_stack( 'bp_group_hierarchy_register_template_location' );
 
// If admin says only show the group tree (and we are in theme compat), do it:
add_filter( 'bp_get_template_part', 'bp_group_hierarchy_maybe_replace_group_index_template', 10, 3 );

Result: Works seamlessly. It even allows BP to load templates from the stylesheet and template directories before falling back to those included with the plugin.

The only drawback is that it requires a new template file, the group tree version of the bp-templates/bp-legacy/buddypress/groups/index.php file from BP. Which is to say that it adds another layer of template hijinks and possible theme compatibility issues rather than removing an existing one.

Wrap up

I don’t know if this is the strategy that will ultimately make it into the plugin, but it is straightforward and has performed well in early tests. In the meantime, I hope this post will be useful to anyone else trying to do something crazy and ill-advised with BuddyPress.

If you use any of the techniques on this page, please drop me a line in the comments and let me know how they worked for you. And if you have any suggestions on techniques that work even better than these, please send those along too. 😉

]]> http://www.generalthreat.com/2013/08/grappling-with-bp-theme-compatibility/feed/ 1 Make P2 posts private by default (and control them with tags) http://www.generalthreat.com/2013/06/make-p2-posts-private-by-default-and-control-them-with-tags/ http://www.generalthreat.com/2013/06/make-p2-posts-private-by-default-and-control-them-with-tags/#comments Sun, 30 Jun 2013 20:02:24 +0000 http://www.generalthreat.com/?p=101 P2 is great for collaboration and team discussion. Sometimes that discussion can be entirely public, and at other times it makes sense to put the entire site behind a login screen. But what if you want to combine a private discussion stream with public pages? Or mix public posts with private ones? This post will show you how to mix and match private and public posts on your P2 blog and will set up a framework for controlling post behavior through tags.]]> The WordPress theme P2 is great for collaboration and team discussion. Sometimes that discussion can be entirely public, and at other times it makes sense to put the entire site behind a login screen. But what if you want to combine a private discussion stream with public pages? Or mix public posts with private ones? P2 emphasizes quick and easy posting by streamlining the process, but this comes at the expense of options.

This post will show you how to mix and match private and public posts on your P2 blog and will set up a framework for controlling post behavior through tags.

No changes to P2’s files are needed, and this trick will work even with older versions on the theme. This code should be placed in your child theme’s functions.php file or in a plugin of your own. There’s a combined block at the bottom of this post for easy copy and paste.

1. Hook P2’s post save mechanism

While P2 exposes limited posting options, authors using the back-end dashboard have access to the full publishing UI. So we want to make sure to target only posts made from the front-end to avoid confusion for authors using full UI.

Loading our handlers this way allows us to ensure that only P2 posts are affected by these magic tags.

1
2
3
4
5
6
7
8

/**
 * Use this action to catch requests to P2 AJAX functions
 */
function gtp2_add_hooks() {
	add_filter( 'wp_insert_post_data', 'gtp2_maybe_make_post_private', 10, 2 );
	add_action( 'pre_get_posts', 'gtp2_include_private_posts' );
}
add_action('p2_ajax', 'gtp2_add_hooks' );

2. Check for magic tags when saving

Having hooked the action above, we know that the function below will only run on P2 posts. First, the list of tags is split into an array so we can look for them more easily. Then, we search for any tags we have decided will control post behavior, and change the post accordingly.

Check out lines 21-24 — this is where the magic happens. We check whether the post is tagged public. If it is, we leave it alone (P2 posts are public by default). If it isn’t, we change its status to private.

This example only implements a single check, but you can create as many as you want.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

/**
 * Change post status to private unless it is tagged "public"
 */
function gtp2_maybe_make_post_private( $data, $postarr ) {
 
	$tags = $postarr['tags_input'];
 
	/**
	 * Tag processing borrowed from wp_set_post_terms()
	 */
	if ( ! is_array( $tags ) ) {
		$comma = _x( ',', 'tag delimiter' );
		if ( ',' !== $comma )
			$tags = str_replace( $comma, ',', $tags );
		$tags = explode( ',', trim( $tags, " \n\t\r\0\x0B," ) );
	}
 
	/**
	 * Look for tags and control what they do here
	 */
	if( ! in_array( 'public', $tags ) ) {
		// Change attributes of the post here
		$data['post_status'] = 'private';
	}
 
	// Make sure to return the data!
	return $data;
 
}

3. Fix the in-page refresh

P2’s fancy in-page refresh only loads public posts. To make our change seamless to users, this needs to be expanded to load private posts too. We’ll need to add one more short function to accomplish this. You may have seen a hint of it in Step 1, but here’s the function itself.

1
2
3
4
5
6

/**
 * Expand query to include all post status values visible to current user
 */
function gtp2_include_private_posts( $obj ) {
	$obj->set( 'post_status', 'any' );
}

That’s it! Users logged in with Editor or Administrator privileges won’t notice a difference, but other users and anonymous visitors will see only their own posts and those tagged public.

Feel free to drop me a line in the comments if you have any questions or find a use for this on your own sites!

The whole thing

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

/**
 * Make all P2 posts Private unless they are tagged "public"
 */
 
/**
 * Use this action to catch requests to P2 AJAX functions
 */
function gtp2_add_hooks() {
	add_filter( 'wp_insert_post_data', 'gtp2_maybe_make_post_private', 10, 2 );
	add_action( 'pre_get_posts', 'gtp2_include_private_posts' );
}
add_action('p2_ajax', 'gtp2_add_hooks' );
 
/**
 * Change post status to private unless it is tagged "public"
 */
function gtp2_maybe_make_post_private( $data, $postarr ) {
 
	$tags = $postarr['tags_input'];
 
	/**
	 * Tag processing borrowed from wp_set_post_terms()
	 */
	if ( ! is_array( $tags ) ) {
		$comma = _x( ',', 'tag delimiter' );
		if ( ',' !== $comma )
			$tags = str_replace( $comma, ',', $tags );
		$tags = explode( ',', trim( $tags, " \n\t\r\0\x0B," ) );
	}
 
	/**
	 * Look for tags and control what they do here
	 */
	if( ! in_array( 'public', $tags ) ) {
		// Change attributes of the post here
		$data['post_status'] = 'private';
	}
 
	// Make sure to return the data!
	return $data;
 
}
 
/**
 * Expand query to include all post status values visible to the current user
 */
function gtp2_include_private_posts( $obj ) {
	$obj->set( 'post_status', 'any' );
}
]]> http://www.generalthreat.com/2013/06/make-p2-posts-private-by-default-and-control-them-with-tags/feed/ 0 Serving koha-common with Plack http://www.generalthreat.com/2013/04/serving-koha-common-with-plack/ http://www.generalthreat.com/2013/04/serving-koha-common-with-plack/#comments Tue, 16 Apr 2013 01:21:59 +0000 http://www.generalthreat.com/?p=98 This post builds on my last Koha post about running the OPAC on Plack and will modify some of the files from that post. If you haven’t read it, it is a good background post but the snippets are no longer up-to-date.

Except where noted, I put these files in a new /usr/share/koha/misc/plack folder. This guide and these code samples assume you will too.

Hey! Do you want the speed of Plack but don’t want to deal with all of these files? Check out Plackify koha-common on github! This post will eventually go out of date, but the github project will always have the latest scripts and a painless installer.

Let’s begin!

1. Create the PSGI application file

koha.psgi:

This is the file that will do the heavy lifting for your Koha install. It is used to run both Intranet and OPAC front-end sites.

#!/usr/bin/perl
use Plack::Builder;
use Plack::App::CGIBin;
use Plack::App::Directory;
 
use lib("/usr/share/koha/lib");
use C4::Context;
use C4::Languages;
use C4::Members;
use C4::Dates;
use C4::Boolean;
use C4::Letters;
use C4::Koha;
use C4::XSLT;
use C4::Branch;
use C4::Category;
 
my $root = ( $ENV{INTRANETDIR} ) ?
                $ENV{INTRANETDIR} . '/cgi-bin' :
                $ENV{OPACDIR} . '/cgi-bin/opac' ;
 
my $app=Plack::App::CGIBin->new(root => $root);
 
builder {
 
        mount "/opac-tmpl" => Plack::App::File->new(root => "/usr/share/koha/opac/htdocs/opac-tmpl");
        mount "/intranet-tmpl" => Plack::App::File->new(root => "/usr/share/koha/intranet/htdocs/intranet-tmpl");
 
        mount "/cgi-bin/koha" => $app;
 
};

2. Create startup scripts for both the intranet and OPAC

These scripts will handle starting your Plack OPAC and Intranet (respectively) in a way that can be controlled by `koha-common` style start and stop commands.

Note: These scripts assume that you installed Starman from CPAN. If you used your distro’s package manager, you should check your starman path and update these scripts if needed.

opac-plack.sh:

Make sure this script is executable!

#!/bin/sh
# --max-requests = decreased from 1000 to 50 to keep memory usage sane
# --workers = number of cores on machine
 
test ! -z "$1" && site=$1 && shift
dir=`dirname $0`
 
export KOHA_CONF=/etc/koha/sites/$site/koha-conf.xml
export OPACDIR="$( xmlstarlet sel -t -v 'yazgfs/config/opacdir' $KOHA_CONF | sed 's,/cgi-bin/opac,,' )"
export LOGDIR="$( xmlstarlet sel -t -v 'yazgfs/config/logdir' $KOHA_CONF )"
 
export MEMCACHED_SERVERS=localhost:11211
export MEMCACHED_NAMESPACE=$site
 
PIDFILE=/var/run/koha/$site/opac-plack.pid
 
SOCKET=/var/run/koha/$site/opac-plack.sock
#PORT=5000
 
# uncomment to enable logging
opt="$opt --access-log $LOGDIR/opac-access.log --error-log $LOGDIR/opac-error.log"
opt="$opt -M FindBin --max-requests 50 --workers 2 -E deployment"
 
if [ $SOCKET ]; then
    opt="$opt --listen $SOCKET -D --pid $PIDFILE"
elif [ $PORT ]; then
    opt="$opt --port $PORT -D --pid $PIDFILE"
fi
 
/usr/local/bin/starman $opt $dir/koha.psgi

intranet-plack.sh:

Make sure this script is executable!

#!/bin/sh
# --max-requests = decreased from 1000 to 50 to keep memory usage sane
# --workers = number of cores on machine
 
test ! -z "$1" && site=$1 && shift
dir=`dirname $0`
 
export KOHA_CONF=/etc/koha/sites/$site/koha-conf.xml
export INTRANETDIR="$( xmlstarlet sel -t -v 'yazgfs/config/intranetdir' $KOHA_CONF | sed 's,/cgi-bin,,' )"
export LOGDIR="$( xmlstarlet sel -t -v 'yazgfs/config/logdir' $KOHA_CONF )"
 
export MEMCACHED_SERVERS=localhost:11211
export MEMCACHED_NAMESPACE=$site
 
PIDFILE=/var/run/koha/$site/intranet-plack.pid
 
SOCKET=/var/run/koha/$site/intranet-plack.sock
#PORT=5000
 
# uncomment to enable logging
opt="$opt --access-log $LOGDIR/intranet-access.log --error-log $LOGDIR/intranet-error.log"
opt="$opt -M FindBin --max-requests 50 --workers 2 -E deployment"
 
if [ $SOCKET ]; then
    opt="$opt --listen $SOCKET -D --pid $PIDFILE"
elif [ $PORT ]; then
    opt="$opt --port $PORT -D --pid $PIDFILE"
fi
 
/usr/local/bin/starman $opt $dir/koha.psgi

2a. Scripts for opening access to socket files

Note: If you’re using sockets instead of TCP ports on Linux, you’ll need to make sure they are world-writable. The following two scripts can be run by koha-start-plack to make sure the sockets are available to any application.

unlock-opac-plack.sh:

Make sure this script is executable!

#!/bin/sh
 
test ! -z "$1" && site=$1 && shift
 
timeout=0
 
echo "Waiting for OPAC Plack socket for $site"
while [ ! -S /var/run/koha/$site/opac-plack.sock ] && [ $timeout -lt 10 ]
do
        sleep 1
        timeout=$(($timeout + 1))
done
 
chmod 777 /var/run/koha/$site/opac-plack.sock
echo "OPAC Plack socket open for $site"

unlock-intranet-plack.sh:

Make sure this script is executable!

#!/bin/sh
 
test ! -z "$1" && site=$1 && shift
 
timeout=0
 
echo "Waiting for Intranet Plack socket for $site"
while [ ! -S /var/run/koha/$site/intranet-plack.sock ] && [ $timeout -lt 10 ]
do
        sleep 1
        timeout=$(($timeout + 1))
done
 
chmod 777 /var/run/koha/$site/intranet-plack.sock
echo "Intranet Plack socket open for $site"

3. Create control scripts for startup and shutdown

Finally, create the koha-common style start and stop scripts to control your Plack processes.

/usr/sbin/koha-start-plack:

This script will start Plack processes for both the Intranet and the OPAC. Like other koha-common scripts, it takes the name of the instance as a parameter. Make sure it’s executable!

#!/bin/sh
#
# koha-start-plack -- Start plack processes for named Koha instances
#
 
set -e
 
for name in "$@"
do
    echo "Starting OPAC Plack server for $name"
    exec start-stop-daemon \
        --start \
        --chuid $name-koha \
        --exec /usr/share/koha/misc/plack/opac-plack.sh -- $name \
        | /usr/share/koha/misc/plack/unlock-opac-plack.sh $name
 
    echo "Starting Intranet Plack server for $name"
    exec start-stop-daemon \
        --start \
        --chuid $name-koha \
        --exec /usr/share/koha/misc/plack/intranet-plack.sh -- $name \
        | /usr/share/koha/misc/plack/unlock-intranet-plack.sh $name
 
done

/usr/sbin/koha-stop-plack:

This script will stop Plack processes for both the Intranet and the OPAC. It also takes the name of the instance as a parameter. Make sure it’s executable!

#!/bin/sh
#
# koha-stop-plack -- Stop plack processes for named Koha instances
 
stopopac() {
   local name="$1"
   exec start-stop-daemon \
        --stop \
        --quiet \
        --pidfile /var/run/koha/$name/opac-plack.pid
}
 
stopstaff() {
   local name="$1"
   exec start-stop-daemon \
        --stop \
        --quiet \
        --pidfile /var/run/koha/$name/intranet-plack.pid
}
 
for name in "$@"
do
echo "Stopping Plack servers for $name"
    stopopac "$name" | stopstaff "$name"
 
done
echo "Servers stopped"

4. Prepare Koha to launch Plack

/etc/init.d/koha-common:

There are two final changes needed to make Plack a first class part of your koha-common install. Both are made to your /etc/init.d/koha-common file, but they’re both really simple.

First, add the new koha-start-plack script to the do_start() function, just after the koha-start-zebra line.

     koha-start-plack $(koha-list --enabled)

Then add the new koha-stop-plack script to the do_stop() function, just after the koha-stop-zebra line.

    koha-stop-plack $(koha-list) || true

That’s it! Stop and start your koha-common service to enjoy your new Plack infrastructure.

Problems? — Check:

  • log directory is writable by your *-koha user
  • tmp directory for compiled templates is writable by your *-koha user
]]> http://www.generalthreat.com/2013/04/serving-koha-common-with-plack/feed/ 1 Plugins now available on GitHub http://www.generalthreat.com/2012/12/plugins-now-available-on-github/ http://www.generalthreat.com/2012/12/plugins-now-available-on-github/#comments Tue, 11 Dec 2012 02:42:41 +0000 http://www.generalthreat.com/?p=97 Most of my WordPress plugins are now mirrored on GitHub!

This includes Networks for WordPress, which I have traditionally not linked back to this site.

]]> http://www.generalthreat.com/2012/12/plugins-now-available-on-github/feed/ 0 Creating a (relatively) secure dynamic PHP test environment with nginx http://www.generalthreat.com/2012/11/creating-a-secure-dynamic-env/ http://www.generalthreat.com/2012/11/creating-a-secure-dynamic-env/#comments Fri, 30 Nov 2012 02:51:54 +0000 http://www.generalthreat.com/?p=95 I’ve been working on a deployment tool for WordPress development environments; one that can quickly provision and maintain the dizzying array of sites needed to test plugins against different versions of WordPress (with and w/o Multisite), BuddyPress, bbPress, etc.

Some cocktail napkin math suggested at least 20 combinations were needed to cover all the currently-supported configurations. Besides the chore of setting up environments for each, the need to add or remove environments as components are updated makes a manual deployment effort seem ridiculous.

While I’m finishing up work on that tool, I thought I’d start by posting the web server and PHP configs I’m using to make this happen.

nginx Configuration

I went with nginx because of its low memory usage and its handy regular-expression hostname matching, which I find more flexible and less kludgey for this application than mod_vhost_alias or mod_rewrite. This nginx config will provide the flexibility of dynamically-creating sites while still providing some isolation between them.

server {
        server_name ~^(.*)\.dev.your.domain$ ;
 
        set $instance $1;
        set $session_root /var/www/dev/$instance/sessions;
 
        root /var/www/dev/$instance/html;
        index index.php;
 
        location ~ \.php$ {
 
                try_files $uri =404;
                fastcgi_split_path_info ^(.+\.php)(/.+)$;
 
                fastcgi_pass unix:/var/run/fpm-devsites.sock;
#               fastcgi_pass 127.0.0.1:9000
                fastcgi_param PATH_INFO $fastcgi_path_info;
                fastcgi_param SCRIPT_FILENAME  $document_root$fastcgi_script_name;
                fastcgi_param PHP_ADMIN_VALUE  "open_basedir=$document_root\nsession.save_path=$session_root";
                include /etc/nginx/fastcgi_params;
 
        }
 
        location / {
                try_files $uri $uri/ /index.php;
        }
}

Thanks to mike at http://michaelshadle.com/2011/02/11/setting-php-ini-parameters-from-nginx for the great guide to the PHP_ADMIN_VALUE param.

PHP-FPM Configuration

Ideally each site would have its own FPM pool, but that would mean root privileges were needed to provision new sites. So a single but separate pool for the dev environments was a necessary compromise. The goal of dynamically creating sites through an unprivileged web interface also meant that the devsites pool needed to run as the web user.

; Start a new pool named 'www'.
; the variable $pool can we used in any directive and will be replaced by the
; pool name ('www' here)
[devsites]
 
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = www-data
group = www-data
 
; The address on which to accept FastCGI requests.
; Valid syntaxes are:
;   'ip.add.re.ss:port'    - to listen on a TCP socket to a specific address on
;                            a specific port;
;   'port'                 - to listen on a TCP socket to all addresses on a
;                            specific port;
;   '/path/to/unix/socket' - to listen on a unix socket.
; Note: This value is mandatory.
listen = /var/run/fpm-$pool.sock
 
; Set permissions for unix socket, if one is used. In Linux, read/write
; permissions must be set in order to allow connections from a web server. Many
; BSD-derived systems allow connections regardless of permissions.
; Default Values: user and group are set as the running user
;                 mode is set to 0666
listen.owner = www-data
listen.group = www-data
listen.mode = 0666

If you’ve found this helpful (or troublesome), feel free to drop me a line in the comments below!

]]> http://www.generalthreat.com/2012/11/creating-a-secure-dynamic-env/feed/ 0 Serving the koha-common OPAC with Plack http://www.generalthreat.com/2012/09/serving-the-koha-common-opac-with-plack/ http://www.generalthreat.com/2012/09/serving-the-koha-common-opac-with-plack/#comments Tue, 25 Sep 2012 18:58:06 +0000 http://www.generalthreat.com/?p=93 If you’ve set up a Koha instance and been less than impressed with the responsiveness of the OPAC, this post is for you.

Thanks to the hard work of the Koha Debian package team, it’s easier than ever to get a functional Koha install up and running. But once you’ve set up your new instance, you may find the catalog a little sluggish. If you’ve followed the steps on the Koha Plack wiki page but found they don’t work for the koha-common package, here are a few changes that will set things right.

Before we begin, make sure you are running at least Koha 3.8. Earlier versions are not compatible with Plack, so results may be unpredictable.
Also make sure you have installed all Plack dependencies as listed in the Koha wiki.
Finally, it helps to have already created your Koha instance (with koha-create). Whew!

Except where noted, I put these files in a new /usr/share/koha/misc/plack folder. This guide and these code samples assume you will too.

1. Creating the Koha PSGI wrapper

Create koha.psgi

This file is adapted from the example found on the Koha Plack wiki page. The lib and $root variables have been fixed for koha-common, and a lot of debugging hooks have been removed. The static file paths are correct, but those files should really be served by something leaner like nginx.

Update (1/7/2013): I’ve tweaked this file to allow it to be used for serving the Koha staff site as well, since that is supported with Plack as of 3.10. A more complete guide for that is coming soon, so stay tuned!

#!/usr/bin/perl
use Plack::Builder;
use Plack::App::CGIBin;
use Plack::App::Directory;
 
use lib("/usr/share/koha/lib");
use C4::Context;
use C4::Languages;
use C4::Members;
use C4::Dates;
use C4::Boolean;
use C4::Letters;
use C4::Koha;
use C4::XSLT;
use C4::Branch;
use C4::Category;
 
my $root = ( $ENV{INTRANETDIR} ) ?
                $ENV{INTRANETDIR} . '/cgi-bin' :
                $ENV{OPACDIR} . '/cgi-bin/opac' ;
 
my $app=Plack::App::CGIBin->new(root => $root);
 
builder {
 
        mount "/opac-tmpl"     => Plack::App::File->new(root => "/usr/share/koha/opac/htdocs/opac-tmpl");
        mount "/intranet-tmpl" => Plack::App::File->new(root => "/usr/share/koha/intranet/htdocs/intranet-tmpl");
        mount "/cgi-bin/koha" => $app;
 
};

As the docs say, at this point you can test the OPAC with plackup. Just replace [YOUR INSTANCE NAME] with your instance name in the following and give it a shot.

echo "OPACDIR=/usr/share/koha/opac/ \
	KOHA_CONF=/etc/koha/sites/SITE/koha-conf.xml \
	sudo -u SITE-koha -E plackup --reload /usr/share/koha/misc/plack/koha.psgi" | \
	sed s/SITE/[YOUR INSTANCE NAME]/g | sh

Open your web browser of choice and visit http://[YOUR SERVER IP]:5000/cgi-bin/koha/opac-main.pl.

Congratulations! You have a working OPAC running over twice as fast as it was just moments ago.

For production use, you’ll want to set up a more stable application server. The rest of this article will guide you through making your new OPAC a permanent part of your Koha install by setting up a Starman server and running it through koha-common’s control systems.

To continue, press Ctrl + C to break out of plackup.

2. Serving the OPAC with Starman

Create opac-plack.sh

This was adapted from the opac-plack.sh example posted on the patches mailing list. Create it in your /usr/share/koha/misc/plack directory.

#!/bin/sh -xe
 
test ! -z "$1" && site=$1 && shift
dir=`dirname $0`
 
export KOHA_CONF=/etc/koha/sites/$site/koha-conf.xml
export OPACDIR="$( xmlstarlet sel -t -v 'yazgfs/config/opacdir' $KOHA_CONF | sed 's,/cgi-bin/opac,,' )"
export LOGDIR="$( xmlstarlet sel -t -v 'yazgfs/config/logdir' $KOHA_CONF )"
 
export MEMCACHED_SERVERS=localhost:11211
export MEMCACHED_NAMESPACE=$site
 
PIDFILE=/var/run/koha/$site/plack.pid
 
# Use one of these lines to choose between TCP port and UNIX socket listeners
#SOCKET=/var/run/koha/$site/plack.sock
PORT=5000
 
opt="$opt --access-log $LOGDIR/opac-access.log --error-log $LOGDIR/opac-error.log"
opt="$opt -M FindBin --max-requests 50 --workers 2 -E deployment"
if [ $SOCKET ]; then
    opt="$opt --listen $SOCKET -D --pid $PIDFILE"
elif [ $PORT ]; then
    opt="$opt --port $PORT -D --pid $PIDFILE"
fi
/usr/local/bin/starman $opt $dir/koha.psgi

Make the script executable with: chmod +x opac-plack.sh

Also be sure to make note of the port (or socket file path) in this file, since that’s how you’ll access the OPAC.

You may have noticed that the opac-plack.sh file takes an argument not present in the original. That’s because we’re going to control it with koha-common’s startup infrastructure.

3. Controlling the OPAC server

First we need to create startup and shutdown scripts for Plack.

Create /usr/sbin/koha-start-plack

#!/bin/sh
#
# koha-start-plack -- Start Plack processes for named Koha instances
#
 
set -e
 
for name in "$@"
do
    echo "Starting Plack server for $name"
    exec start-stop-daemon \
        --start \
        --chuid $name-koha \
        --exec /usr/share/koha/misc/plack/opac-plack.sh -- $name
done

Create /usr/sbin/koha-stop-plack

#!/bin/sh
#
# koha-stop-plack -- Stop Plack processes for named Koha instances
#
 
set -e
 
for name in "$@"
do
    echo "Stopping Plack server for $name"
    exec start-stop-daemon \
        --stop \
        --pidfile /var/run/koha/$name/plack.pid
done
echo "Servers stopped"

Be sure to make these scripts executable when you’re finished!

4. Preparing for lanch

Now we update the koha-common init script to start and stop the Plack servers along with the rest of our Koha infrastructure.

Edit /etc/init.d/koha-common

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

do_start()
{
    # We insure all required directories exist, including disabled ones.
    koha-create-dirs $(koha-list)
    koha-start-zebra $(koha-list --enabled)
+    koha-start-plack $(koha-list --enabled)
}
 
#
# Function that stops the daemon/service
#
do_stop()
{
    # We stop everything, including disabled ones.
    koha-stop-zebra $(koha-list) || true
+    koha-stop-plack $(koha-list) || true
}

Restart koha-common

Now you are ready to put your OPAC into service. Restart your koha-common services with:

service koha-common stop
service koha-common start

That’s it! Your Plack OPAC will now start with your server each time it is restarted, or each time you start and stop the koha-common services. You can also use the koha-[start|stop]-plack scripts to control your OPAC manually, if needed.

Drop me a line in the comments if you have questions or suggestions, or if this article has helped you get the most from your Koha install!

]]> http://www.generalthreat.com/2012/09/serving-the-koha-common-opac-with-plack/feed/ 0 Extending BuddyPress Group Hierarchy – Adding Breadcrumbs to Your Theme http://www.generalthreat.com/2012/04/extending-buddypress-group-hierarchy-adding-breadcrumbs-to-your-theme/ http://www.generalthreat.com/2012/04/extending-buddypress-group-hierarchy-adding-breadcrumbs-to-your-theme/#comments Wed, 04 Apr 2012 17:49:34 +0000 http://www.generalthreat.com/?p=87 Once you’ve created a hierarchy of BuddyPress groups, you can help your users navigate and give your site the professional touch by including group breadcrumbs where appropriate. Here’s how!

Step One: Change the link at the top of every group page to a trail of links to parent groups

This is the easy part! BuddyPress Group Hierarchy includes a function, bp_group_hierarchy_breadcrumbs(), that will generate a string of links to a group and all its parents. Use it in the Groups loop, and no parameter is required.

Note: If you need to pass in a different group for some reason, you’ll need to use bp_group_hierarchy_get_breadcrumbs( $separator = '|', $group = false ) function and echo the result yourself. This tutorial won’t address using that more advanced function.

Just locate your theme’s groups/single/group-header.php file, and find the current group header which will look something like this:

<h2><a href="<?php bp_group_permalink(); ?>" title="<?php bp_group_name(); ?>"><?php bp_group_name(); ?></a></h2>

Replace it with this simple line:

<h2><?php bp_group_hierarchy_breadcrumbs() ?></h2>

Step Two: Change the page title on group pages to reflect your group structure

Changing the page title is more complicated. BuddyPress builds its page titles with a function hooked to the wp_title filter. This function in turn presents its own filter, and that’s the one we have to hook to put breadcrumbs in the title of our Group page. This makes sure our filtering function runs only when BuddyPress is enabled and on as few pages as necessary.

If you zoned out during that bit, don’t worry! Just place the code below into your theme’s functions.php file.

add_filter( 'bp_modify_page_title', 'my_func_group_breadcrumbs', 10, 4 );
 
function my_func_group_breadcrumbs( $processed_title, $title, $sep, $seplocation  ) {
 
	global $bp;
 
 	if( bp_is_active( 'groups' ) && ! empty( $bp->groups->current_group ) ) {
		$processed_title = substr( $processed_title, strpos( $processed_title, $sep ) );
		$processed_title = bp_group_hierarchy_get_full_name( '|', $bp->groups->current_group ) . ' ' . $processed_title;
 	}
 
	return $processed_title;
}

This function strips the group name from the page title, but re-adds the names of the group and all its ancestors. The bp_group_hierarchy_get_full_name function works like the bp_group_hierarchy_get_breadcrumbs function I mentioned earlier, but it builds a plain text list instead of a list of links.

That’s it! Check back soon for a reference child theme, implementing this technique. As always, if you have any questions or problems adding this to your site, or if you have a novel implementation you’d like to share, please post in the comments below!

Update: As promised, here is the sample child theme! BuddyPress Group Hierarchy Breadcrumbs - Sample Theme

]]> http://www.generalthreat.com/2012/04/extending-buddypress-group-hierarchy-adding-breadcrumbs-to-your-theme/feed/ 2 Adding Externally-Authenticated Users to BuddyPress http://www.generalthreat.com/2012/02/adding-externally-authenticated-users-to-buddypress/ http://www.generalthreat.com/2012/02/adding-externally-authenticated-users-to-buddypress/#comments Wed, 29 Feb 2012 01:49:26 +0000 http://www.generalthreat.com/?p=85 BuddyPress does a great job integrating new users who register through your WordPress site into the community — optionally synchronizing profile information between BP and WP, and creating an activity feed item for new user signups.

But what about users who login against an external authentication provider, and whose accounts are created and managed by such a system? Today we’re going to look at how to bring those users into the community in the same way as those who registered locally. Be warned — this is a fairly dense piece, especially if you haven’t worked with an authenticate filter before.

A crash course on authenticate

If you are using (or writing) an external authentication plugin, you’ll need a function hooked to the authenticate filter. This function is where your plugin gets a chance to authenticate users against your outside system. It is also where your users will have subordinate WordPress accounts made and managed by the external system.

A very quick example:

function my_func_to_authenticate( $user, $username, $password ) {
 // if $user is a valid WP_User, authenticated by an upstream filter
 // pass these params to the external auth source for verification
 // proceed if user is logged in, otherwise return a WP_Error
}
add_filter( 'authenticate', 'my_func_to_authenticate', 10, 3 );

The first login

The first time your users log in to your WordPress install using their external credentials, you’ll probably want to create a WP account for them. You may skip this if you’re just trying to restrict read access, but this is about BuddyPress, so I’m assuming you want them to post and contribute to the site. :)

Here’s a rundown of the process:

  1. Suppress the BuddyPress activation email
  2. Create WP user account
  3. Update user meta and, optionally, xprofile data
  4. Activate user and set proper display_name
  5. Publish activity stream message about new user, with properly-formatted display name

Suppress the BuddyPress activation email

These users are already verified by virtue of being in our external auth system, so an activation email would just be confusing.

/** Suppress activation key email for users logging in with external auth */
add_filter( 'bp_core_signup_send_activation_key', create_function('','return false;') );

Create WordPress user account

Normally, you’d use wp_create_user (or wp_insert_user if you want access to the full set of user properties).
But BuddyPress comes with a wrapper function that can be used to do a lot of the heavy lifting for us.

$new_user = bp_core_signup_user(
	$user_login,
	$user_password,
	$user_email,
	array()
);
 
if( is_wp_error( $new_user ) ) {
	return $new_user;
}

Update user meta and, optionally, xprofile data

There are actually a few ways to handle this, ranging from bull-in-a-china-shop overwriting to graceful but more complicated filtering. Which one you choose may depend on your comfort with WP or PHP, which BuddyPress features you have enabled, or the structure of your authentication script.

Easiest

Easiest
$display_name = $first_name . ' ' . $last_name;
 
update_user_meta( $new_user, 'nickname',   $display_name  );
update_user_meta( $new_user, 'first_name', $first_name );
update_user_meta( $new_user, 'last_name',  $last_name  );
 
if( bp_is_active( 'xprofile' ) )
	xprofile_set_field_data( bp_xprofile_fullname_field_name(), $new_user, $display_name );
 
// Even though setting the xprofile value, above, should take care of this, 
// testing revealed that we needed to prime the cache with the right value
wp_cache_set( 'bp_user_fullname_' . $new_user, $display_name, 'bp' );

PROS:

  • Very straightforward and procedural — no objects or data sharing needed
  • Complete control over format of display_name and BP fullname field
  • Control over any other BP xprofile values you want to set
  • Does not require xprofile or WP-BP profile sync in order to operate

CONS:

  • Will ultimately drift out of sync with BP development
  • Still need to set the display_name property below
  • Might as well use wp_insert_user, since we’re manually adding so much

Shortest

Shortest

Replace the bp_core_signup_user call above with this:

$new_user = bp_core_signup_user(
	$login_name,
	$password,
	$email,
	array(
		'profile_field_ids' => bp_xprofile_fullname_field_name(),
		"field_{bp_xprofile_fullname_field_name()}" => $display_name
	)
);

PROS:

  • Uses BP to eliminate the need for additional filters or processing
  • Least code redundancy of all
  • Can supply additional xprofile fields to be added to the new user
  • Most natural method in terms of program flow

CONS:

  • Complex meta parameter structure can be difficult to read
  • Parameter or data structure may change in future BP releases
  • Requires xprofile and WP-BP profile sync to update WP display_name and usermeta

Fanciest

Fanciest
function my_display_name_filter( $user_id, $user_login, $user_password, $user_email, $usermeta ) {
	// must get $display_name from another part of the authentication process
	if ( bp_is_active( 'xprofile' ) ) {
		xprofile_set_field_data( bp_xprofile_fullname_field_name(), $new_user, $display_name );
	}
}

Change your authenticate function to look like this:

function my_func_to_authenticate( $user, $username, $password ) {
 
	// ... authenticate user
	add_action( 'bp_core_signup_user', 'my_display_name_filter', 9, 5 );
	$new_user = bp_core_signup_user(
		$login_name,
		$password,
		$email,
		array()
	);
}

PROS:

  • Uses BP filters for forward compatibility
  • Reduces the amount of repeated code

CONS:

  • Requires an object or data-sharing infrastructure to get user details to the filter
  • Requires xprofile and WP-BP profile sync to update WP display_name and usermeta

Now that the xprofile and usermeta data are set up, it’s time to activate the user! This is done by simply setting the user_status column to 0.

Activate user (and set proper display_name, if needed)

Update 08-06-2012: I used to recommend wp_update_user for this, but that has proven unreliable on a recent project. So to be safe, just use a direct query.

// activate user and set display name appropriately
$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->users SET display_name=%s, user_status=0 WHERE ID=%d", $display_name, $new_user ) );

And if you set $display_name above, use the shortened version:

// activate user
$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->users SET user_status=0 WHERE ID=%d", $new_user ) );

Publish an activity stream message about the new user and notify the site admin

Since the display_name property and associated xprofile field are finally set the way we want them, it’s time to trigger the activity stream message and administrator notification.

bp_core_new_user_activity( $new_user );
wp_new_user_notification( $new_user );

And you’re done!

Return a WP_User object to let other authentication filters know you’ve handled this user.

return new WP_User( $new_user );

A complete example

function my_func_to_authenticate( $user, $username, $password ) {
	// if $user is a valid WP_User, authenticated by an upstream filter
	if( is_a( $user, 'WP_User' ) ) return $user;
 
	// pass these params to the external auth source for verification
	// proceed if user is logged in, otherwise return a WP_Error
	if( $user_details = my_external_auth( $username, $password ) ) {
 
		// for simplicity's sake, I'm assuming that $user_details is an array with all the right keys
		// in practice, more checks would be required
		extract( $user_details );
 
		// this function returns the new user account ID if successful
		$new_user = bp_core_signup_user(
			$username,
			$password,
			$user_email,
			array()
		);
 
		// If signup returned an error, skip the rest
		if( is_wp_error( $new_user ) ) {
			return $new_user;
		}
 
		$display_name = $first_name . ' ' . $last_name;
 
		update_user_meta( $new_user, 'nickname',   $display_name  );
		update_user_meta( $new_user, 'first_name', $first_name );
		update_user_meta( $new_user, 'last_name',  $last_name  );
 
		if( bp_is_active( 'xprofile' ) )
			xprofile_set_field_data( bp_xprofile_fullname_field_name(), $new_user, $display_name );
 
		// Even though setting the xprofile value, above, should take care of this, 
		// testing revealed that we needed to prime the cache with the right value
		wp_cache_set( 'bp_user_fullname_' . $new_user, $display_name, 'bp' );
 
		// activate user and set display name appropriately
		$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->users SET display_name=%s, user_status=0 WHERE ID=%d", $display_name, $new_user ) );
 
		bp_core_new_user_activity( $new_user );
		wp_new_user_notification( $new_user );
 
		return new WP_User( $new_user );
	}
	// you can return FALSE, or a WP_Error if you have something specific to say
	return new WP_Error( 'login_failed', __( 'Could not authenticate user' ) );
}
add_filter( 'authenticate', 'my_func_to_authenticate', 10, 3 );

If you have questions, or if you put this to use in your next project, feel free to drop me a line in the comments!

]]> http://www.generalthreat.com/2012/02/adding-externally-authenticated-users-to-buddypress/feed/ 2 Extending BuddyPress Group Hierarchy – Creating a Member Groups list http://www.generalthreat.com/2012/01/extending-buddypress-group-hierarchy-list-member-groups/ http://www.generalthreat.com/2012/01/extending-buddypress-group-hierarchy-list-member-groups/#comments Sun, 29 Jan 2012 19:44:39 +0000 http://www.generalthreat.com/?p=82 In this post, I’m going to show you how to create a Member Groups page/list/widget, with a little background on how Group Hierarchy extends the BuddyPress Groups loop.

BuddyPress Groups loop overview

If you aren’t familiar with bp_has_groups() from looking at the BuddyPress theme files, you should take a look at this overview from the BP Codex before continuing.

In a nutshell, bp_has_groups() accepts a series of parameters which it uses to populate the global $groups_template variable with a set of groups. This, in turn, allows all the cool template functions to work without parameters cluttering up your theme file.

How Group Hierarchy changes the Loop

BuddyPress Group Hierarchy changes this in two important ways:

  1. bp_has_groups() creates a set of BP_Groups_Hierarchy objects instead of BP_Groups_Group objects
  2. bp_has_groups_hierarchy() extends the loop with a parent_id parameter for getting only child groups of the passed group ID

There are more changes made just for the Group Tree, but that’s enough to get us started. Onward!

Creating a Member Groups list

Before we build our Member Groups page / widget / list, there’s something you should know about working “in the loop,” i.e. in the context of the current group. The only thing telling BuddyPress what group we’re looking at is the $groups_template variable introduced above. Our member group list is going to change that variable, so we need to save its current state and restore it when we’re done.

// If you're in a function, bring $groups_template into scope
global $groups_template;
 
// Save the current group context for later
$current_group_template = $groups_template;

Using the Codex article I posted at the top as a reference, you’ll see how easy it is to create a Member Groups page / widget / whatever.

Just replace:

<?php if ( bp_has_groups() ) : ?>

with:

<?php if ( bp_has_groups_hierarchy( array( 
	'type'      => 'alphabetical',
	'parent_id' => bp_get_current_group_id() 
) ) ) : ?>

…and the rest works as is! Since 1.3.0, pagination is handled automatically.

Don’t forget to restore the original context!

$groups_template = $current_group_template;

A complete example

Here’s a quick example that adds a list of Member Groups on the Members page, above the list of users. Drop this in your functions.php file, or in a custom plugin, but note that it will only display if the parent group has at least one member!

<?php
add_action( 'bp_before_group_members_content', 'my_func_list_member_groups' );
 
function my_func_list_member_groups() {
	// If you're in a function, bring $groups_template into scope
	global $groups_template;
 
	// Save the current group context for later
	$current_group_template = $groups_template;
 
	if ( bp_has_groups_hierarchy( array( 
		'type'      => 'alphabetical',
		'parent_id' => bp_get_current_group_id(),
	) ) ) : ?>
 
	<h3><?php _e( 'Member Groups' ); ?><br />&nbsp;</h3>
 
	<div class="pagination">
 
		<div class="pag-count" id="group-dir-count">
			<?php bp_groups_pagination_count() ?>
		</div>
 
		<div class="pagination-links" id="group-dir-pag">
			<?php bp_groups_pagination_links() ?>
		</div>
 
	</div>
 
	<ul id="groups-list" class="item-list">
	<?php while ( bp_groups() ) : bp_the_group(); ?>
 
		<li>
			<div class="item-avatar">
				<a href="<?php bp_group_permalink() ?>"><?php bp_group_avatar( 'type=thumb&width=50&height=50' ) ?></a>
			</div>
 
			<div class="item">
				<div class="item-title"><a href="<?php bp_group_permalink() ?>"><?php bp_group_name() ?></a></div>
				<div class="item-meta"><span class="activity"><?php printf( __( 'active %s ago', 'buddypress' ), bp_get_group_last_active() ) ?></span></div>
 
				<div class="item-desc"><?php bp_group_description_excerpt() ?></div>
 
				<?php do_action( 'bp_directory_groups_item' ) ?>
				</div>
 
			<div class="action">
				<?php bp_group_join_button() ?>
 
				<div class="meta">
					<?php bp_group_type() ?> / <?php bp_group_member_count() ?>
				</div>
 
				<?php do_action( 'bp_directory_groups_actions' ) ?>
			</div>
 
			<div class="clear"></div>
		</li>
 
	<?php endwhile; ?>
	</ul>
 
		<?php do_action( 'bp_after_member_groups_loop' ) ?>
 
	<?php else: ?>
 
		<div id="message" class="info">
		<p><?php _e( 'There were no member groups found.' ) ?></p>
		</div>
 
	<?php endif;
 
	// restore original group context!
	$groups_template = $current_group_template;
}

That’s it! Drop me a line in the comments if you find a novel use for this technique.

]]> http://www.generalthreat.com/2012/01/extending-buddypress-group-hierarchy-list-member-groups/feed/ 8 Highlighting Features with WordPress Admin Pointers – A Quick Guide for Plugin Authors http://www.generalthreat.com/2012/01/highlighting-features-with-wordpress-admin-pointers/ http://www.generalthreat.com/2012/01/highlighting-features-with-wordpress-admin-pointers/#comments Mon, 02 Jan 2012 05:24:12 +0000 http://www.generalthreat.com/?p=80 Here’s a quick intro to admin pointers for plugins to WordPress 3.3+, based on some work I recently put into making the help system in Networks more intuitive:

Step One — Add the admin pointer style and script to your page

This is a fairly standard chain of admin_menu action functions, which should look familiar if you’re using a class for your plugin. If they don’t, some light background reading may be in order.

You’ll need to create a script file for your admin page to follow this guide, although you could also dump the required JavaScript into the admin page itself.

 
function admin_menu()
{
	$this->admin_page = add_menu_page( __('My Page'), __('My Page'), 'manage_options', 'my-page', FUNCTION );
 
	wp_register_script( 'my_admin_js', plugins_url(SCRIPT FILE, __FILE__), array('jquery') );
 
	add_action( 'admin_print_scripts-' . $this->admin_page, array( &$this, 'add_admin_scripts' ) );
	add_action( 'admin_print_styles-' . $this->admin_page, array( &$this, 'add_admin_styles' ) );
}
 
function add_admin_styles() {
	wp_enqueue_style( 'wp-pointer' );
}
 
function add_admin_scripts() {
	wp_enqueue_script( 'wp-pointer', false, array('jquery') );
	wp_enqueue_script( 'my_admin_js', false, array('jquery') );
	wp_localize_script( 'my_admin_js', 'strings', $this->localize_admin_js() );
}

In addition to enqueueing the admin pointer CSS and script files, we’ve set up a localization function. Beside being good coding practice, generating the strings for the admin pointer here, instead of in the script file, is going to allow us to use a nice shortcut.

Step Two — Build the pointer text and check for dismissal

function localize_admin_js() {
 
	$pointer_text = '<h3>' . esc_js( __( 'My Pointer Header') ) . '</h3>';
	$pointer_text .= '<p>' . esc_js( __( 'This is the text of my pointer.' ) ). '</p>';
 
	// Get the list of dismissed pointers for the user
	$dismissed = explode( ',', (string) get_user_meta( get_current_user_id(), 'dismissed_wp_pointers', true ) );
 
	// Check whether our pointer has been dismissed
	if ( in_array( POINTER HANDLE, $dismissed ) ) {
		$pointer_text = '';
	}
 
	return array(
		'pointerText' => $pointer_text
	);
}

In testing, setting the pointer text to '' was sufficient to hide the pointer from the screen. However, we can add another layer of protection in the script, which you’ll see below.

Step Three – Script the pointer object gracefully

If you don’t already have an admin script file, you’ll need to create one for this step.

jQuery(document).ready( function() {
 
	/** Check that pointer support exists AND that text is not empty */
	if(typeof(jQuery().pointer) != 'undefined' && strings.pointerText != '') {
		jQuery('#OBJECT_YOU_WANT_TO_POINT_AT').pointer({
			content    : strings.pointerText,
			close  : function() {
				jQuery.post( ajaxurl, {
					pointer: POINTER HANDLE,
					action: 'dismiss-wp-pointer'
				});
			}
		}).pointer('open');
	}
});

Note the close property of the pointer object: calling this action hooks us right into WordPress’s pointer management, so that when the user clicks the Dismiss button, our pointer is added to his list of dismissed pointers. The wp-pointer stylesheet takes care of making the pointer look right so long as there’s an <h3> and one or more paragraphs, and the close button is added and wired up automatically.

Hope this helps anyone wishing to use this neat, new feature!

]]> http://www.generalthreat.com/2012/01/highlighting-features-with-wordpress-admin-pointers/feed/ 2