Creating sortable drag & drop admin interfaces is a handy feature that gives the user an intuitive level of control over the appearance of there website. In this tutorial, we will go over how to create a sortable list using jQuery UI, and then save the list order using WordPress’s Settings API. And lastly, how to output the sorted list in your theme template.

Download the source code for this tutorial here.

Step 1: Setting up our scripts

In order to create our sortable options, we will require three scripts: jQuery UI core, jQuery UI sortable, and a custom script file. First create a blank file in your theme’s root directory and name it admin.js. Then, to include the scripts, add the following code to your functions.php file:

function yourtheme_admin_scripts() {
    if (is_admin()) {
	wp_register_script('admin-js', get_template_directory_uri() . '/admin.js', array('jquery'), '', true);
	wp_enqueue_script('admin-js');
	wp_enqueue_script('jquery-ui-core');
	wp_enqueue_script( 'jquery-ui-sortable' );
    }
}
add_action('admin_enqueue_scripts', 'yourtheme_admin_scripts');

Step 2: Implementing the Settings API

Before we can get started creating our sortable list, we’ll want to configure the settings API, giving us an environment where we can save information into the database. If you have already set this up and would like skip over this section, click here.

First, in your themes function.php file, you want to add your options page to the WordPress menu. To do this, add the following function:

add_action('admin_menu', 'yourtheme_theme_options_create_menu');

function yourtheme_theme_options_create_menu() {

	//create new top-level menu
	add_menu_page('Theme Options', 'Theme Options', 'administrator', 'theme_options', 'yourtheme_theme_options_page' , null, 99 );

	//call register settings function
	add_action( 'admin_init', 'register_yourtheme_theme_options' );
}

*Note: remember to replace yourtheme with the actual name of your theme.

Now you should be seeing a menu item in your WordPress admin that links to your theme options page. Currently, this page is blank. Next we will write the function that outputs the form that will contain the sortable list.

Step 3: Creating the Sortable List

Next, we will be adding two additional functions. Copy and paste the following code into your functions.php:

function register_yourtheme_theme_options() {
    register_setting( 'rypecore-settings-group', 'filter_fields_order' );
}

function yourtheme_theme_options_page() {
    ?>

    <div class="wrap">
        <h2>Theme Options</h2>
        <br/>

        <?php settings_errors(); ?>

        <form method="post" action="options.php" id="theme-options-form">
            <?php settings_fields( 'rypecore-settings-group' ); ?>
            <?php do_settings_sections( 'rypecore-settings-group' ); ?>

            <?php
            $fields_order_default = array(
                0 => array(
                    'id' => '0',
                    'name' => 'List Item 1',
                    'slug' => 'list_item_1'
                ),
                1 => array(
                    'id' => '1',
                    'name' => 'List Item 2',
                    'slug' => 'list_item_2'
                ),
                2 => array(
                    'id' => '2',
                    'name' => 'List Item 3',
                    'slug' => 'list_item_3'
                ),
                3 => array(
                    'id' => '3',
                    'name' => 'List Item 4',
                    'slug' => 'list_item_4'
                ),
                4 => array(
                    'id' => '4',
                    'name' => 'List Item 5',
                    'slug' => 'list_item_5'
                ),
            );
            ?>

            <div class="admin-module"> 
                <label><b>Sortable List</b> <em>(Drag & drop to rearrange order)</em></label>

                <ul class="filter-fields-list">
                    <?php 
                        $filter_fields_order = get_option('filter_fields_order', $fields_order_default); 
                        foreach($filter_fields_order as $value) { ?>

                            <?php
                                if(isset($value['id'])) { $id = $value['id']; }
                                if(isset($value['name'])) { $name = $value['name']; }
                                if(isset($value['slug'])) { $slug = $value['slug']; }
                            ?>

                            <li class="sortable-item">
                                <?php echo $name; ?>
                                <input type="hidden" name="filter_fields_order[<?php echo $id; ?>][id]" value="<?php echo $id; ?>" />
                                <input type="hidden" name="filter_fields_order[<?php echo $id; ?>][name]" value="<?php echo $name; ?>" />
                                <input type="hidden" name="filter_fields_order[<?php echo $id; ?>][slug]" value="<?php echo $slug; ?>" />
                            </li>
                    <?php } ?>
                </ul>
            </div>

            <?php submit_button(); ?>
        </form>

    </div>
    <?php
}

The first function just assigns a field to a settings group named “rypecore-settings-group”. This is part of WordPress’s Settings API, you can read more about it here. The second function is responsible for outputting the code that will generate our form in the theme options.

After pasting this code into your functions.php, refresh your theme options page and you should see a list and a Save button. Test out the sortable list by clicking and dragging a list item to a different position and then save the settings to make sure the list order remains.

Step 4: Outputting the List In a Theme Template

Once you have confirmed that you can manipulate your list order and save the theme options, next we will add the code that will output this list in your theme file. Place this code in custom template files, custom widgets, shortcodes, or any wordpress theme file.

<?php
    $fields_order_default = array(
        0 => array(
            'id' => '0',
            'name' => 'List Item 1',
            'slug' => 'list_item_1'
        ),
        1 => array(
            'id' => '1',
            'name' => 'List Item 2',
            'slug' => 'list_item_2'
        ),
        2 => array(
            'id' => '2',
            'name' => 'List Item 3',
            'slug' => 'list_item_3'
        ),
        3 => array(
            'id' => '3',
            'name' => 'List Item 4',
            'slug' => 'list_item_4'
        ),
        4 => array(
            'id' => '4',
            'name' => 'List Item 5',
            'slug' => 'list_item_5'
        ),
    );
?>

<ul>
     <?php 
            $filter_fields_order = get_option('filter_fields_order', $fields_order_default); 
            foreach($filter_fields_order as $value) { ?>

                <?php
                    if(isset($value['id'])) { $id = $value['id']; }
                    if(isset($value['name'])) { $name = $value['name']; }
                    if(isset($value['slug'])) { $slug = $value['slug']; }
                ?>

                <li><?php echo $name; ?></li>

     <?php } ?>
</ul>

That’s it! You have now successfully implemented a sortable list into your theme options. This example is a very basic implementation for the sake of simplicity, but it can be easily extended to accommodate for complex scenarios, such as custom form builders, page layouts, and more. Get creative and have fun with it!