Ticket #4805: test-wplists.php

<?php
/*
Plugin Name: Test wp-lists.js
Plugin URI: http://wordpress.org/#
Description: Try out the wp-lists javascript
Author: Michael Adams
Version: 0.1
*/ 

function test_wp_list_admin_menu() {
    $hook = add_menu_page( 'WPLists Tests', 'WPLists', 0, __FILE__, 'test_wp_list_instructions' );
    add_submenu_page( __FILE__, 'WPLists Tests', 'Instructions', 0, __FILE__ );
    add_action( "admin_print_scripts-$hook", 'test_wp_list_admin_page_js' );
    add_action( "admin_head-$hook", 'test_wp_list_admin_page_head' );
    $hook = add_submenu_page( __FILE__, 'WPLists Tests', 'Add Test 1', 0, 'test_wp_lists_1', create_function('', 'test_wp_list_admin_page(1);') );
    add_action( "admin_print_scripts-$hook", 'test_wp_list_admin_page_js' );
    add_action( "admin_head-$hook", 'test_wp_list_admin_page_head' );
    $hook = add_submenu_page( __FILE__, 'WPLists Tests', 'Add Test 2', 0, 'test_wp_lists_2', create_function('', 'test_wp_list_admin_page(2);') );
    add_action( "admin_print_scripts-$hook", 'test_wp_list_admin_page_js' );
    add_action( "admin_head-$hook", 'test_wp_list_admin_page_head' );
    $hook = add_submenu_page( __FILE__, 'WPLists Tests', 'Delete Test', 0, 'test_wp_lists_3', create_function('', 'test_wp_list_admin_page(3);') );
    add_action( "admin_print_scripts-$hook", 'test_wp_list_admin_page_js' );
    add_action( "admin_head-$hook", 'test_wp_list_admin_page_head' );
    $hook = add_submenu_page( __FILE__, 'WPLists Tests', 'Dim Test', 0, 'test_wp_lists_4', create_function('', 'test_wp_list_admin_page(4);') );
    add_action( "admin_print_scripts-$hook", 'test_wp_list_admin_page_js' );
    add_action( "admin_head-$hook", 'test_wp_list_admin_page_head' );
    $hook = add_submenu_page( __FILE__, 'WPLists Tests', 'Full Test', 0, 'test_wp_lists_5', create_function('', 'test_wp_list_admin_page(5);') );
    add_action( "admin_print_scripts-$hook", 'test_wp_list_admin_page_js' );
    add_action( "admin_head-$hook", 'test_wp_list_admin_page_head' );
}
add_action( 'admin_menu', 'test_wp_list_admin_menu' );

function test_wp_list_admin_page_js() {
    wp_enqueue_script( 'wp-lists' );
    wp_enqueue_script( 'jquery-form' );
}

function test_wp_list_admin_page_head() {
?>

<script type="text/javascript">
/* <![CDATA[ */
jQuery(function($) {
$('#the-list').wpList( { response: 'bob' } );
} );
/* ]]> */
</script>

<style type="text/css">
.dim-class { background-color: #99F; color: #33F; font-style: italic; }
pre { background-color: #FFD; padding: 1em; }
.green { background-color: #0F6; }
#the-list { border: 1px solid #ccc; padding: 1em 2em; }
form { border: 1px solid #ccc; padding: 0; }
form div { float: left; margin: 0 2ex 1em; }
</style>

<?php
}


function test_wp_list_instructions() {
?>

<div class="wrap">
<h2>WP jQuery Lists</h2>
<p>Information about <a href="#markup">Markup</a>, <a href="#javascript">JavaScript</a>, and <a href="#server">Server Responses</a>.</p>
<p>You'll find some tests/examples in the other tabs.</p>
</div>

<div id="markup" class="wrap">
<h2>The HTML Markup</h2>

<pre><code>
&lt;ul id="the-list" class="list:item"&gt;
    &lt;li id="item-1"&gt;The first item&lt;/li&gt;
    ...
&lt;/ul&gt;
</code></pre>

<p>All of the classes mentioned below <strong>must</strong> be the first class for that element.</p>
<p>Upper case "class parameters" are required.  Lower case parameters are optional.

<h3>Setting up the list</h3>
<p>CLASS: <code>list:TTTT</code></p>
<dl>
    <dt><code>TTTT</code></dt>
    <dd>The "type" of the item the list contains</dd>
</dl>
<h4>Notes</h4>
<ul>
    <li>The list element must have an HTML id attribute.</li>
    <li>The list can be any block level element: <code>UL</code>, <code>OL</code>, <code>DIV</code>....</li>
    <li>If you want to use a table, you must make the list container a <code>TBODY</code> within that table.</li>
    <li>
        The items in the list much each have an id formatted like: <code>id="TTTT-ID"</code> where <code>TYPE</code>
        is the "type" of item the list contains and <code>ID</code> is some unqique identifer (not necessarily a number).
    </li>
    
</ul>

<h3>Adding items to the list</h3>
<p>CLASS: <code>add:LLLL:FFFF:aaaa:qqqq</code></p>
<dl>
    <dt><code>LLLL</code></dt>
    <dd>The HTML id of the list to which you want to add the item.</dd>

    <dt><code>FFFF</code></dt>
    <dd>
        The HTML id of the element containing the form elements you want to send in the AJAX call.
        May be blang if the <code>add:</code> class is given to a <code>FORM</code> element, but
        the colon after <code>LLLL</code> is <em>always required</em>: <code>&lt;form class="add:the-list:"&gt;</code>.
    <dd>

    <dt><code>aaaa</code></dt>
    <dd>A six digit hex color that specifies the fade color of the item when it is added.  It can also be set to "<code>none</code>".</dd>

    <dt><code>qqqq</code></dt>
    <dd>A query string formatted string of extra data to send in the AJAX call: <code>add:the-list:::foo=bar&yo=mama<code>.</dd>
</dl>
<h4>Notes</h4>
<ul>
    <li>The AJAX call is constructed from <code>FORM</code> elements.</li>
    <li>
        You can send all of the form to the server by giving the form the <code>add:LLLL:</code> class. The final colon is very important!
        The AJAX call will be made whenever the form is submitted (type enter, click submit...).
    </li>
    <li>
        You can send just a piece of the form by giving some element a <code>add:LLLL:FFFF</code> class.
        The AJAX call will be made whenever that element is clicked or whenever a submit event comes from that piece of the form.
    </li>
    <li>Whatever you send, it must include a <code>_ajax_nonce</code> or <code>_wpnonce</code> element.</li>
</ul>

<h3>Removing items from the list</h3>
<p>CLASS: <code>delete:LLLL:IIII:dddd:qqqq</code></p>
<dl>
    <dt><code>LLLL</code></dt>
    <dd>The HTML id of the list from which you want to delete the item.</dd>

    <dt><code>IIII</code></dt>
    <dd>The HTML id of the item you want to delete.</dd>

    <dt><code>dddd</code></dt>
    <dd>A six digit hex color that specifies the fade color of the item when it is deleted.  It can also be set to "<code>none</code>".</dd>

    <dt><code>qqqq</code></dt>
    <dd>A query string formatted string of extra data to send in the AJAX call: <code>delete:the-list:item-1::foo=bar&yo=mama<code>.</dd>
</dl>
<h4>Note</h4>
<p>The nonce is drawn from the url of the link's href.  Use either a <code>_ajax_nonce</code> or <code>_wpnonce</code> parameter.</p>

<h3>Dimming items in the list (toggling a class)</h3>
<p>CLASS: <code>dim:LLLL:IIII:CCCC:aaaa:dddd:qqqq</code></p>
<dl>
    <dt><code>LLLL</code></dt>
    <dd>The HTML id of the list containing the item you want to dim</dd>

    <dt><code>IIII</code></dt>
    <dd>The HTML id of the item you want to dim</dd>

    <dt><code>CCCC</code></dt>
    <dd>The name of the class</dd>

    <dt><code>aaaa</code></dt>
    <dd>A six digit hex color that specifies the fade color of the item when the class is added.  It can also be set to "<code>none</code>".</dd>

    <dt><code>dddd</code></dt>
    <dd>A six digit hex color that specifies the fade color of the item when the class is deleted.  It can also be set to "<code>none</code>".</dd>

    <dt><code>qqqq</code></dt>
    <dd>A query string formatted string of extra data to send in the AJAX call: <code>dim:the-list:item-1:classname:::foo=bar&yo=mama<code>.</dd>
</dl>
<h4>Note</h4>
<p>The nonce is drawn from the url of the link's href.  Use either a <code>_ajax_nonce</code> or <code>_wpnonce</code> parameter.</p>

</div>

<div id="javascript" class="wrap">

<h2>The Javascript</h2>

<p>If your form has radio buttons or other complicated form elements, you should include the jQuery-Forms JS file so that the data is sent to the server in the correct format.</p>

<pre><code>
// Set up the list
$('#the-list').wpList(); // Basic Usage.
// or
$('#the-list').wpList( options ); // Advanced Usage.

options = {
    url: '/admin-ajax.php',
        // Where to submit the AJAX request,
    response: 'ajax-response',
        // the HTML id of an element whose innerHTML
        // will be filled with error messages if needed

    what: '',
    alt: 'alternate',
        // the class that will be added to alternate list items.
        // Can be set to blank.
    altOffset: 0, // 0 or 1
        // 0 => odd items will be given alt class
        // 1 => even items
    addColor: null, delColor: null, dimAddColor: null, dimDelColor: null,
        // Fade colors for various actions.
        // Overridden by class parameters in <a href="#markup">Markup</a>

    confirm: null,
        // Callback function usefupl for Are You Sure?s
        // Called from scope of list element
        // 1st arg: element to delete or dim, or form to add from
        // 2nd: options object
        // 3rd: 'add', 'delete', 'dim' (what we're doing)
        // 4th: original pre-highlight background color of element
        //
        // Return true => "I want to da that", false => "I didn't mean it. Stop."

    addBefore: null, // options.data is a query string
    delBefore: null, // options.data is a JS object
    dimBefore: null, // options.data is a JS object
        // Callback functions executed before AJAX call
        // Accepts options object as first and only parameter
        // options.data is the data that will be sent via AJAX
        //
        // Must return options object (like WP filters must)
        // Can instead return false => AJAX will be aborted,
        //   and "traditional" action will proceed (form submit,
        //   link click...)

    addAfter: null,
    delAfter: null,
    dimAfter: null,
        // Callback function executed after AJAX call succeeds
        // Accepts response(XML|Text) as 1st argument, options object as 2nd
        

};

// Add alt class to appropriate elements
$("#the-list').wpList.recolor();

// Add HTML or element to list manually.  No AJAX involved.  The .get(0) is really important
$("#the-list').get(0).wpList.add( HTML or element );
</code></pre>

</div>

<div id="server" class="wrap">
<h2>Server Side</h2>

<p>The server should exit with one of the following.</p>

<dl>
    <dt><code>(string) -1</code></dt>
    <dd>
        This response indicates that the user does not have permission to perform the requested action.
        This could be because of the user lacks a capability you're checking for or because the nonce check failed.
    </dd>

    <dt><code>(string) 0</code></dt>
    <dd>Indicates that something reall strange happened.  You should only return this when you have no idea what the error really is.</dd>

    <dt><code>(string) 1</code></dt>
    <dd>"All is well.  The requested action was performed with no problem."</dd>

    <dt><code>(string)</code> Raw Text or HTML</dt>
    <dd>"Something bad happened; the requested action did not complete.  Here is an error message."</dd>

    <dt>XML generated by <code>(object) new WP_Ajax_Response</code></dt>
    <dd>
        The client side JS expects the XML to be formatted in a particular way.
        The <code>WP_Ajax_Response</code> class should be used to generate that XML.
        You will need to use this method when AJAX adding to a list.
    </dd>
</dl>

<h3>The <code>WP_Ajax_Response</code> Class</h3>

<pre><code>
// Respond with single item
$x = new WP_Ajax_Response( array(
    'what'  => 'object', // the item "type" of your list
    'action' => false, // (optional) formatted like a nonce action
    'id' => 0, // The unique identifier of the item (not the HTML id)
    'oldId' => 0, // (optional) If you were updating an item, did it formerly have a different id?
    'position' => 1,
        // -1 => insert at beginning of list
        // 0  => if oldId, insert where oldId item was
        // 1  => insert at end of list
        // HTML_ID  => insert after the item with that HTML id
        // -HTML_ID => insert before the item with that HTML id
    'data' => '', // The HTML of the item to be inserted into the list.
    'supplemental' => array()
        // an associative array af extra data to be passed with the XML response:
        // 'supplemental' => array( 'foo' => 'bar' )
        // yields
        // &lt;foo&gt;&lt;![CDATA[bar]]&gt;&lt;/foo&gt;
);
$x->send();

// Respond with several items
$x = new WP_Ajax_Response;
$x->add( ... );
$x->add( ... );
$x->send();
</pre></code>

</div>
<?php
}



function test_wp_list_admin_page( $test ) {
    $list_items = array( 1,2,3,4,5,6,7,8); //,9,10,11,12,13,14,15,16,17,18,19,20 );
?>
<div class="wrap">

<div id="bob"></div>

<?php
$code = '';
switch ( $test ) :
case 1 :
echo "<h2>Send the whole form</h2>\n";
echo "<p>The add: class is given to the whole form.</p>\n\n";
$code = <<<CODE1
<form action='' method='post' id='ajax-add' class='%s'>
    ...
    <?php wp_nonce_field( 'add-item', '_ajax_nonce', false ); ?>
</form>
<ul id="the-list" class="list:item">
    ...
</ul>
CODE1;
$code = sprintf( wp_specialchars( $code ), "<span class='green'>add:the-list:</span>" );
break;


case 2 :
echo "<h2>Send a piece of the form</h2>\n";
echo "<p>The add: class is given to a button (so the position radios shouldn't work in this test; it will always appear at the end of the list).</p>\n\n";
$code = <<<CODE2
<form action='' method='post' id='ajax-add'>
    <div id="%s">
        <input type='text' id='adder' name='adder' />
        <?php wp_nonce_field( 'add-item', '_ajax_nonce', false ); ?>
    </div>
    ...
    <input type="button" value="Add" id='add-button' class='%s'>
</form>
<ul id="the-list" class="list:item">
    ...
</ul>
CODE2;
$code = sprintf( wp_specialchars( $code ), "<span class='green'>ajax-add-name</span>", "<span class='green'>add:the-list:ajax-add-name</span>" );
break;



case 3 :
echo "<h2>Delete an item from the list</h2>\n";
echo "<ul>\n";
echo "\t<li>The list must specify what kind of items it holds with the list: class.</li>\n";
echo "\t<li>The delete link should have the nonce in it.</li>\n";
echo "\t<li>The delete link must specify what item to delete and from what list to delete it with the delete: class.</li>\n";
echo "</ul>\n\n";
$code = <<<CODE3
<ul id="the-list" class="%s">
    <li id="item-1">
        Item 1
        <a href="?_wpnonce=123456789a" class="%s">Delete</a>
    </li>
    ...
</ul>
CODE3;
$code = sprintf( wp_specialchars( $code ), "<span class='green'>list:item</span>", "<span class='green'>delete:the-list:item-1</span>" );
break;



case 4 :
echo "<h2>'Dim' an item: toggle it's class</h2>\n";
echo "<ul>\n";
echo "\t<li>The list must specify what kind of items it holds with the list: class.</li>\n";
echo "\t<li>The dim link should have the nonce in it.</li>\n";
echo "\t<li>The dim link must specify what item to dim, from what list to dim it, and what class to toggle  with the dim: class.</li>\n";
echo "</ul>\n\n";
$code = <<<CODE3
<ul id="the-list" class="%s">
    <li id="item-1">
        Item 1
        <a href="?_wpnonce=123456789a" class="%s">Dim</a>
    </li>
    ...
</ul>
CODE3;
$code = sprintf( wp_specialchars( $code ), "<span class='green'>list:item</span>", "<span class='green'>dim:the-list:item-1:dim-class</span>" );
break;
endswitch;

if ( $code ) {
    echo "\n<h3>Example:</h3>\n\n";
    echo "\n\n<pre><code>$code</code></pre>\n\n";

    echo "\n<h3>Test:</h3>\n\n";
}

if ( $test < 3 || 5 == $test ) : ?>

<form action='' method='post' id='ajax-add'<?php if ( 1 == $test || 5 == $test ) echo " class='add:the-list:'"; ?>>
<div id="ajax-add-name">
    <h4>Name of item to add:</h4>
    <input type='text' id='adder' name='adder' />
    <?php wp_nonce_field( 'add-item', '_ajax_nonce', false ); ?>
</div>
<div>
    <h4>Position:</h4>
    <label for="pos--1"><input type='radio' name='pos' value='-1' checked='checked' id='pos--1' /> Beginning: -1</label><br />
    <label for="pos--3"><input type='radio' name='pos' value='-3' id='pos--3' /> Before Item 3</label><br />
    <label for="pos-3"><input type='radio' name='pos' value='3' id='pos-3' /> After Item 3</label><br />
    <label for="pos-1"><input type='radio' name='pos' value='1' id='pos-1' /> End: 1</label><br />
</div>
<?php if ( 2 == $test ) : ?>
<div>
    <h4>The "submit" button</h4>
    <input type="button" value="Add" id='add-button' class='add:the-list:ajax-add-name button' />
</div>
<?php endif; ?>
<?php if ( 5 == $test ) : ?>
<input type="hidden" value="5" name="test" />
<?php endif; ?>
<br style="clear: both"/>
</form>

<?php endif; ?>

<ul id="the-list" class="list:item">
<?php foreach ( $list_items as $list_item ) : ?>

    <li id="item-<?php echo $list_item; ?>">
        Item <?php echo $list_item; ?>
<?php if ( 3 == $test || 5 == $test ) : ?>
        <a href="<?php echo wp_nonce_url( '?', "delete-item_$list_item"); ?>" class="delete:the-list:item-<?php echo $list_item; ?>">Delete</a>
<?php endif; if ( 4 == $test || 5 == $test ) : ?>
        <a href="<?php echo wp_nonce_url( '?', "dim-item_$list_item"); ?>" class="dim:the-list:item-<?php echo $list_item; ?>:dim-class">Dim</a>
<?php endif; ?>
    </li>

<?php endforeach; ?>

</ul>

</div>

<?php
}

function test_wp_list_admin_ajax() {
    $id = (int) $_POST['id'];
    switch ( $_POST['action'] ) :
    case 'add-item' :
        check_ajax_referer( 'add-item' );
        $text = $_POST['adder'];
        $id = mt_rand();
        $data  = "<li id='item-$id'>\n";
        $data .= "\t$text\n";
        if ( isset($_POST['test']) && 5 == $_POST['test'] ) {
            $data .= "\t<a href='" . wp_nonce_url( add_query_arg( array( 'action' => 'delete', 'id' => $id ), '?' ), "delete-item_$id") . "' class='delete:the-list:item-$id'>Delete</a>\n";
            $data .= "\t<a href='" . wp_nonce_url( add_query_arg( array( 'action' => 'dim', 'id' => $id ), '?' ), "dim-item_$id") . "' class='dim:the-list:item-$id:dim-class'>Dim</a>\n";
        }
        $data .= "</li>";
        $pos = (int) $_POST['pos'];
        if ( 3 == $pos )
            $pos = 'item-3';
        elseif ( -3 == $pos )
            $pos = '-item-3';

        $x = new WP_Ajax_Response( array( 'what' => 'item', 'id' => $id, 'data' => $data, 'position' => $pos ) );
        $x->send();
        break;
    case 'delete-item' :
    case 'dim-item' :
        check_ajax_referer( "{$_POST['action']}_$id" );
        die('1');
        break;
    endswitch;
}
add_action( 'wp_ajax_add-item', 'test_wp_list_admin_ajax' );
add_action( 'wp_ajax_delete-item', 'test_wp_list_admin_ajax' );
add_action( 'wp_ajax_dim-item', 'test_wp_list_admin_ajax' );

?>