Overview

ccMixter is a site focused on audio but the 'playlist' feature is just a matter of wording. For an image site the same feature would be called 'gallery' or in a video site it would be called 'channel.'

This tutorial walks through the implementation of an admin feature in ccMixter that with one click will add a playlist to the Featured Playlists page. It covers event handling, URL mapping, customizing command menus, database insert and browser redirect.

Feature Spec

The 'Featured Playlist' page in ccMixter is page created by using the Content Manager with a topic type of 'feat_playlist'. Once a week the admins on the site would create a new topic, copy from the previous week's featured playlist, change a number in a query and post the new topic. The exact same operation (approximately 20 clicks, a copy/paste and submit) every week.

The idea behind this feature is to put a menu on a playlist (example playlist) that with a single click, automate the entire process.

The Code

Adding the Command to the Playlist Menu

In order to add a menu item to the playlist menu we first have to create a dataview filter event handler. (Find out how that was determined.)

Here is the code that handles the event and populate the menu.

 CCEvents::AddHandler(CC_EVENT_FILTER_CART_MENU,   
                    'playlist_feature_OnFilterCartMenu');
 
 CCEvents::AddHandler(CC_EVENT_MAP_URLS,           
                    'playlist_feature_OnMapUrls');

 function playlist_feature_OnFilterCartMenu(&$records)
 {
   // make sure we have a playlist and only show this 
   // command to admins...

   if( empty($records[0]['cart_id']) || !CCUser::IsAdmin() )
       return;
 
   // some helper declarations...

   $row =& $records[0];
   $playlist_id = $row['cart_id'];

   // This is was copy/pasted from the system version, 
   // tweaked for our needs

   $row['menu'][] = array( 'url'   => ccl( 'playlist', 'feature', $playlist_id ),
                            'class' => 'cc_playlist_playlink',
                            'id'    => '_feat_' . $playlist_id,
                            'text'  => '*Feature' );
 }

Map an URL to Our Function

The menu item above made up a new URL playlist/feature/{playlist_id} that we now have to map to function.

Here's the code that does that:

 CCEvents::AddHandler(CC_EVENT_MAP_URLS,           
                        'playlist_feature_OnMapUrls');

 // This function will be called when the system 
 // needs to build the URL map

 function playlist_feature_OnMapUrls()
 {
    // Put our mapping into the system:

    CCEvents::MapUrl(  // here's our URL, the 'playlist_id'
                       // that's appended to this URL will
                       // passed to our function as a param
                       ccp('playlist', 'feature'),   

                       // the function to map to:
                      'playlist_feature_playlist', 

                       // the access level (admin only)
                       CC_ADMIN_ONLY, 

                       // where the function lives (this module)
                       ccs(__FILE__) );
 }

This mapping will only take hold after you do a <your_install_root>?update=1.

Creating the Featured Playlist Topic

In the URL mapping we made up a function that we now implement:

  // the parameter is what was appended to the URL

  function playlist_feature_playlist($playlist_id)
  {
     // needed so we can declare the CCTopics table

     require_once('cchost_lib/ccextras/cc-topics.inc');

     // This is the string (with placeholders) that will 
     // be our topic text...

     $text =<<<EOF
              [left][query=t=avatar&u=mcjackinthebox][/query][/left]
              [query=t=playlist_2_info&ids=%id%][/query]
              [query=t=yahoo_black&playlist=%id%][/query]
  EOF;

     // Create an instance of the topics database 
     // to make the 'INSERT' easier.
     $topics = new CCTopics();

     // Fill out the fields...
     $values['topic_id'] = $topics->NextID();
     $values['topic_upload'] = 0;
     $values['topic_thread'] = 0;
     $values['topic_date'] = date('Y-m-d H:i:s',time());
     $values['topic_user'] = CCUser::CurrentUser();
     $values['topic_type'] = 'feat_playlist';

     // This is where we replace the placeholder with
     // the actual playlist id

     $values['topic_text'] = str_replace('%id%', $playlist_id, $text );


     // Here we use the cart (aka playlist) name for the
     // topic name

     $values['topic_name']  = addslashes(CCDatabase::QueryItem(
                             'SELECT cart_name FROM cc_tbl_cart WHERE 
                             'cart_id='.$playlist_id));

     // insert the values into the database

     $topics->Insert($values,0);

     // Redirect the browser to the 'Featured Playlists' page

     CCUtil::SendBrowserTo( ccl('view','media','playlists') );
  }