one time popup after theme activation

After delving into the codex and hacking around I figured out how to do this.

Short answer – use thickbox (http://codex.wordpress.org/ThickBox).

Longer answer….

Hooking into after_setup_theme isn’t ideal for inserting any content into the admin page, as it runs on each page load when that theme is active.
As suggested by kaiser we can use after_switch_theme instead.

The hook in_admin_header will allow us to drop in some HTML into the body of the admin page, which we can use to populate a modal box and show it using thickbox which comes with wordpress.

A simple example is below, where on the page load after switching to my theme a modal box is presented to the user which can contain a link or regular form which will allow us to perform those setup actions, but only if the user decides to. The real form includes a ‘Dont show this again’ option.

function jp_modal()
{
    //inject a script that opens a thickox which contains the content of #install
    ?>
        <script>
            jQuery(window).load(function($) {
                tb_show("jp theme install","#TB_inline?width=600&height=800&inlineId=install", null);
            });
        </script>
        <div id='install'><div>My Install Options!</div></div>
    <?php
}
function jp_theme_setup()
    {
        //test for the theme being installed before. 
        //This stops us running the code more than once.

        $installed = get_option('jp_installed');
        if (!$installed)
        {
            //mark the theme as installed, and show the modal box
            update_option('jp_installed', true);
            add_action('in_admin_header', 'jp_modal');
        }
    }
    add_action('after_switch_theme', 'jp_theme_setup');

Note that I’ve removed code to only show the relevant parts so it has not been tested in this reduced form.

The option jp_installed combined with only running my install code on after_switch_theme ensures that it will only run once, and the user is given the choice of how to proceed using a modal box – the two requirements fulfilled.