one time popup after theme activation

Question

I've written a custom theme which does some one-time setup chores after activation - things which I need to do every time I use it on a fresh copy of wordpress, like creating a nav menu and configuring discussion settings.

I've automated these things in my theme rather than a plugin because they are directly related to the theme and would have limited use elsewhere.

Anyway, what I'd like to do is after my theme is activated for the first time, show a popup box that will give the user a choice of whether or not to perform these actions. The code to do them is already working and written, but I don't have a mechanism for the user to start them off - my only real option here is to run them automatically by hooking into after_setup_theme.

I've figured out how to tell if it's a first-time activation, using update_option to store a boolean that I then check against - here's what I have:

function jp_theme_setup()
{
    $installed = get_option('jp_installed');
    if (!$installed)
    {
        update_option('jp_installed', true);
        //set up my theme, do stuff involving things

        //how can I ask the user whether or not to do certain actions?
    }
}
add_action('after_setup_theme', 'jp_theme_setup');

How can I use a dialogue box to ask the user whether or not to perform these setup tasks?

Answer 1

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.

Answer 2

I'd suggest that you still use a plugin. It's a one time task and you can deactivate the plugin automatically when the task is performed, not leaving anything behind. You could even activate the plugin if you switch themes and back to yours again.

You might want to take a look at check_theme_switched(). Then there's the option get_option( 'theme_switched' ), which gets checked by before mentioned function. And finally there's an action, which has the stylesheet as argument

add_action( 'after_switch_theme', function( $stylesheet, $old_theme_obj = null )
{
    // here goes the funk
}, 10, 2 );

The second argument is optional and a WP_Theme instance, the same object you would normally retrieve via wp_get_theme(). It is only present if you haven't deleted the old theme.