modules/og_collections/og_collections.module

<?php
// $Id: og_collections.module,v 1.1 2008/03/13 20:12:56 sdboyer Exp $

/**
 * @file
 * The og_collections.module file, which manages the creation and deployment of
 * 'Collections' of 'Pre-Configured Panels' in conjunction with Organic Groups.
 * 
 * Collections are sets of panels (as in the Panels and OG Panels modules) that
 * can be paired with group types. Once a collection of panels has been paired 
 * with a group type, every new group of that type will automatically be granted
 * their own duplicate set of the panels in the collection.
 * 
 */

/**
 * Implementation of hook_help()
 */
function og_collections_help($section) {
  switch ($section) {
    case 'admin/help#og_collections': // TODO write up quite a 
  }
}

/**
 * Implementation of hook_menu()
 */
function og_collections_menu($may_cache) {
  if ($group_types = og_collections_group_types()) { 
    $multgrps = count($group_types) > 1 ? TRUE : FALSE;
  }
  $collectionsetting = variable_get('og_collections_settings', FALSE);
  if ($may_cache) {
    $items[] = array(
      'path' => 'admin/og/og_collections',
      'title' => t('OG Collections'),
      'description' => t('Set up OG Panels to automatically generate associated sets of panels when new groups are created.'),
      'callback' => 'drupal_get_form',
      'callback arguments' => array('og_collections_admin'),
      'access' => user_access('administer organic groups'),
      'weight' => 0,
    );
    $items[] = array(
      'path' => 'admin/og/og_collections/settings',
      'title' => t('Collections Settings'),
      'type' => MENU_DEFAULT_LOCAL_TASK,
      'weight' => -10,
    );
    if ($group_types && $collectionsetting) { // at least one group type must have already been set, and collections must be enabled
      if ($collectionsetting == 1) {
        $pcpanels = FALSE;
      }
      else if ($collectionsetting == 2) {
        $pcpanels = TRUE;
      }
      // sets up the pre-configured panel types selection tab
      $items[] = array(
        'path' => 'admin/og/og_collections/collectioncfg',
        'title' => t('Collections'),
        'description' => $pcpanels ? t('Select which pre-configured panels are to be used for each of your group type bundles.') : t('Select which pre-configured panels are to be used in your group bundle.'), 
        'callback' => 'og_collections_admin_collectioncfg',
        'callback arguments' => array('default'),
        'type' => MENU_LOCAL_TASK,
        'access' => user_access('administer organic groups'),
        'weight' => -4,
      );
      if ($collectionsetting == 2) {
        $items[] = array(
          'path' => 'admin/og/og_collections/collectioncfg/default',
          'title' => t('Default'),
          'type' => MENU_DEFAULT_LOCAL_TASK,
          'access' => user_access('administer organic groups'),
        );
        $i = 1;
        foreach ($group_types as $type => $name) {
          $items[] = array(
            'path' => 'admin/og/og_collections/collectioncfg/'. $type,
            'title' => t($name),
            'callback' => 'og_collections_admin_collectioncfg',
            'callback arguments' => array($type), // for some reason, this argument isn't being passed. currently sporking it using arg() in the callback
            'type' => MENU_LOCAL_TASK,
            'access' => user_access('administer organic groups'),
            'weight' => $i,
          );
        $i++;
        }
      }
      // sets up the pre-configured panels configuration tab
      $items[] = array(
        'path' => 'admin/og/og_collections/pcpanelsetup',
        'title' => t('Pre-Configured Panels'),
        'description' => t('Configure the panels that make up your collection.'),
        'callback' => 'og_collections_admin_pcpanelsetup',
        'callback arguments' => array('default'),
        'type' => MENU_LOCAL_TASK,
        'access' => user_access('administer organic groups'),
        'weight' => -2,
      );
      if ($collectionsetting == 2) {
        $items[] = array(
          'path' => 'admin/og/og_collections/pcpanelsetup/default',
          'title' => t('Default'),
          'description' => t('Configure the panels that make up your collection.'),
          'type' => MENU_DEFAULT_LOCAL_TASK,
          'access' => user_access('administer organic groups'),
        );
        $i = 1;
        foreach ($group_types as $type => $name) {
          $items[] = array(
            'path' => 'admin/og/og_collections/pcpanelsetup/'. $type,
            'title' => t($name),
            'callback' => 'og_collections_admin_pcpanelsetup',
            'callback arguments' => array($type),
            'type' => MENU_LOCAL_TASK,
            'access' => user_access('administer organic groups'),
            'weight' => $i,
          );
        $i++;
        }
      }
      $items[] = array(
        'path' => 'admin/og/og_collections/pcpanel',
        'callback' => 'og_collections_pcpanel_manage',
        'type' => MENU_CALLBACK,
        'access' => user_access('admnister organic groups'),
      );
    }    
  }
  return $items;
}

/**
 * Return the list of node types that have been classified by og as groups.
 * 
 * Because of the omnipresent 'Default' collection, it's sometimes helpful to add a 'Default' 
 * value to the beginning of this array. That's what the first parameter is for.
 *
 * @param boolean $default, default FALSE
 *  indicates whether a 'Default' type should be added at the beginning of the array.
 * @return array $group_types
 *  An associative array of the form [systemtypename] => [publicfacingntypeame] for all group types.
 *  Also can return FALSE if no groups have been defined.
 */
function og_collections_group_types($default = FALSE) {
  if ($group_types = variable_get('og_node_types', FALSE)) {
    asort($group_types);
    foreach ($group_types as $type) {
      $group_types[$type] = node_get_types('name', $type);
    }
    if ($default) { // defaults to not, but if the caller requests it, the 'default' group is inserted at the beginning of the array
      $group_types = array_merge(array('default' => 'Default'), $group_types);
    }
  }
  return $group_types;
}

/**
 * Renders the form for group collections settings
 */
function og_collections_admin_collectioncfg($type) {
  $group_types = og_collections_group_types(TRUE);
  drupal_set_title("'". $group_types[$type] ."' Collection");
  if (mysql_num_fields(db_query("SELECT * FROM {og_collections} WHERE grouptype = 'default'")) == 1) {
    drupal_set_message("You need to create at least one pre-configured panel for OG Collections to operate properly. Use this form to create your first one.");
    drupal_get_destination();
    drupal_goto('admin/og/og_collections/pcpanel/form');
  }
  $collectionsetting = variable_get('og_collections_settings', FALSE);
  // TODO Need to improve helptext considerably
  if ($collectionsetting == 1) {
    $helptext = '<p>This form allows you to control the overall configuration for your collection. You can also !link to the list below.'; 
  }
  elseif ($collectionsetting == 2) {
   $helptext = "<p>This form allows you to control the overall configuration for each group type's pre-configured panel. You can also !link to the list below.";
  }
  $output = t($helptext, array('!link' => l(t('add a new pre-configured panel'), 'admin/og/og_collections/pcpanel/form', array(), drupal_get_destination()))); 
  $output .= drupal_get_form('og_collections_collectioncfg_table', $type);
  return $output;
}

/**
 * FAPI definition for the configure overall collection settings form.
 *
 * @ingroup forms
 * @param string $type
 *  The group type for which the collection settings are being edited.
 * 
 */
function og_collections_collectioncfg_table($type) {
  $collectioncfg = og_collections_load_collectioncfg($type);
  $form['typevar'] = array('#type' => 'hidden', '#value' => $type);
  // $form['#action'] = arg(3) ? url('admin/og/og_collections/'. $theme_key) : url('admin/build/block');
  $form['#tree'] = TRUE;
  // TODO add a default tab as a means of allowing people to add/remove panel pre-configured panels?
  foreach ($collectioncfg as $pcpid => $pcpanel) {
    $pcpanel = og_collections_load_pcpanel($pcpanel['did'], FALSE, $type);
    $form[$pcpid]['page_title'] = array('#value' => '#'. $pcpid .': '. $pcpanel->page_title);
    $form[$pcpid]['weight'] = array('#type' => 'weight', '#default_value' => $pcpanel->weight ? $pcpanel->weight : 0);
    $form[$pcpid]['edit'] = array('#value' => l(t('Edit'), "admin/og/og_collections/pcpanel/form/$type/$pcpid", array(), drupal_get_destination()));
    if ($type == 'default') {
      $form[$pcpid]['delete'] = array('#value' => l(t('Delete'), "admin/og/og_collections/pcpanel/delete/$pcpid", array(), drupal_get_destination()));
    }
    if ($pcpanel->default_page == 1) {
      $default_page = $pcpid;
    }
    if ($pcpanel->active == 1) {
      $activelist[] = $pcpid;
    }
    if ($pcpanel->published == 1) {
      $publist[] = $pcpid;
    }
    if ($pcpanel->show_blocks == 1) {
      $blklist[] = $pcpid;
    }
    $optionshome[$pcpid] = '';
  }
  
  $options = $optionshome;
  $optionshome[0] = t('<em>(Do not replace the group homepage with a pre-configured panel)</em>');
  // $form[0]; // need to add something here that allows people to DESELECT something as the homepage
  $form['active'] = array(
    '#type' => 'checkboxes',
    '#options' => $options,
    '#default_value' => $activelist ? $activelist : NULL,
  );  
  $form['default_page'] = array(
    '#type' => 'radios', 
    '#options' => $optionshome,
    '#default_value' => $default_page ? $default_page : 0,
  );
  $form['published'] = array(
    '#type' => 'checkboxes',
    '#options' => $options,
    '#default_value' => $publist ? $publist : NULL,
  );
  $form['show_blocks'] = array(
    '#type' => 'checkboxes',
    '#options' => $options,
    '#default_value' => $blklist ? $blklist : NULL,
  );
  $form['submit'] = array(
    '#type' => 'submit', 
    '#value' => t('Save Collection'),
  );
  return $form;
}

/**
 * Theme the collection settings form into a table.
 *
 * @ingroup themeable
 */
function theme_og_collections_collectioncfg_table($form) {
  $isdefault = $form['typevar']['#value'] == 'default' ? TRUE : FALSE;
  foreach (element_children($form) as $pcpid) {
    if (is_numeric($pcpid)) {
      $rows[] = array(
        drupal_render($form[$pcpid]['page_title']),
        drupal_render($form['default_page'][$pcpid]),
        drupal_render($form['active'][$pcpid]),
        drupal_render($form['published'][$pcpid]),
        drupal_render($form['show_blocks'][$pcpid]),                
        drupal_render($form[$pcpid]['weight']),
        drupal_render($form[$pcpid]['edit']),
        drupal_render($form[$pcpid]['delete']), // TODO figure out a way to get rid of this if !$isdefault
      );
    }
  }
  
  $output = drupal_render($form);
  $oper = $isdefault ? array('data' => t('Operations'), 'align' => 'center', 'colspan' => 2) : array('data' => t('Operations'), 'align' => 'center', 'colspan' => 1);
  $header = array(t('Panel Name'), t('Home Page'), t('Enabled'), t('Published'), t('Show Blocks'), t('Weight'), $oper);
  return theme('table', $header, $rows). $output;
}

function og_collections_collectioncfg_table_validate($form_id, $form_values, $form) {
  // what kind of validation actually needs to be done here? any?
}

function og_collections_collectioncfg_table_submit($form_id, $form_values) {
  $type = $form_values['typevar'];
  $collectioncfg = og_collections_load_collectioncfg($type);
  foreach (array_keys($collectioncfg) as $pcpid) {
    $collectioncfg[$pcpid]['active'] = (int) $form_values['default_page'] == $pcpid ? 1 : $form_values['active'][$pcpid] ? 1 : 0; // ensures that pcpanels set to be home pages are also active
    $collectioncfg[$pcpid]['default_page'] = (int) $form_values['default_page'] == $pcpid ? 1 : 0;
    $collectioncfg[$pcpid]['weight'] = (int) $form_values[$pcpid]['weight'];
    $collectioncfg[$pcpid]['published'] = (int) $form_values['default_page'] == $pcpid ? 1 : ($form_values['published'][$pcpid]) == $pcpid ? 1 : 0; // ensures that pcpanels set to be home pages are also published
    $collectioncfg[$pcpid]['show_blocks'] = (int) ($form_values['show_blocks'][$pcpid]) == $pcpid ? 1 : 0;
  }
  if (og_collections_save_collectioncfg($type, $collectioncfg, array_keys($collectioncfg))) {
    drupal_set_message(t("Updated '$type' Collection."));
  }
}

/**
 * Render the page containing pcpanel-specific configuration links.
 *
 * @ingroup themeable
 * @param string $type
 *  The group type for which the collection settings are being edited.
 * @return string $output
 *  String of HTML that has (already) been rendered by the theme('page') function... TODO split this into a separate function so it can be themed 
 */
function og_collections_admin_pcpanelsetup($type) {
  $group_types = og_collections_group_types(TRUE);
  drupal_set_title("'". $group_types[$type] ."' Panels Collection");
  if (count(db_fetch_array(db_query("SELECT * FROM {og_collections} WHERE grouptype = 'default'"))) == 1) {
    drupal_set_message("You need to create at least one group panel pre-configured panel before you can start configuring them! Use this form to create one.");
    drupal_get_destination();
    drupal_goto('admin/og/og_collections/pcpanel/form');
  }
  $collectionsetting = variable_get('og_collections_settings', FALSE);
  if ($collectionsetting == 1) {
    $helptext = '<p>This form allows you to control the panel content and setup for each pre-configured panel. You can !link here, if desired.</p>';
    $linktext = 'add a new pre-configured panel'; 
  }
  elseif ($collectionsetting == 2) {
   $helptext = "<p>Because you have selected to allow every group type to maintain its own independent collection, this page will allow you to configure content and layout settings for pre-configured panels that are specific to each collection. However, !link will not immediately result in pre-configured panels that are specific to each collection.</p>
                <p>Instead, OG Collections creates only one version for each pre-configured panel initially - the 'Default' version. Creating a collection-specific version for one of these panels is easy: simply select the group type from the secondary tabs list and click on any of the modification links that correspond to the pre-configured panel in the table below. The group type-specific pre-configured panel will be created automatically if you save your changes on that form.</p>
                <p>However, it is strongly recommended that you set up your panel pre-configured panels in the Default type first. Until a version of a pre-configured panel is created for a given group type, that group type will utilize the default pre-configured panel loadout, but when you create the type-specific version, it will be an exact copy of all the settings pre-configured panel's Default settings. Consequently, it is to your advantage to load your Default pre-configured panel configurations out with as much common content as possible, THEN begin working on the type-specific pre-configured panels.</p>
                <p>These are just guidelines. At any time, you can remove a type-specific pre-configured panel and cause the group type to begin using Default again instead. You can also copy panel pre-configured panel settings from one group type to another, if you want. But, NOTE that <strong>both of these options are completely irreversible</strong> short of restoring your database from a <a href=\"http://drupal.org/project/backup_migrate\">backup</a>.</p>";     
   $linktext = 'adding a new pre-configured panel';
  }
  $output = t($helptext, array('!link' => l(t($linktext), 'admin/og/og_collections/pcpanel/form', array(), drupal_get_destination()))); 
  
  // looks like we may not need a form, as no data gets submitted or changed directly on this page...begin form substitution!
  $collectioncfg = og_collections_load_collectioncfg($type);
  $multi = $collectionsetting == 2 ? TRUE : FALSE;
  $isdefault = strtolower($type) == 'default' ? TRUE : FALSE;
  
  if (!$isdefault) {
    foreach ($collectioncfg as $pcpid => $pcpanel) {
      $pcpanel = og_collections_load_pcpanel($pcpanel['did'], FALSE, $type);
      if ($pcpanel->active) {
        $row = array();
        $row['page_title'] = $pcpanel->page_title;
        $row['usedef'] = $pcpanel->usedef ? 'Yes' : 'No';
        $row['default_page'] = $pcpanel->default_page ? 'Yes' : 'No';
        $row['content'] = l(t('Content'), "admin/og/og_collections/pcpanel/content/$type/$pcpid", array(), drupal_get_destination());
        $row['layout'] = l(t('Layout'), "admin/og/og_collections/pcpanel/layout/$type/$pcpid", array(), drupal_get_destination());
        $row['layset'] = l(t('Layout Settings'), "admin/og/og_collections/pcpanel/layset/$type/$pcpid", array(), drupal_get_destination());
        $row['revert'] = $pcpanel->usedef ? 'Already Tied' : l(t('Revert'), "admin/og/og_collections/pcpanel/revert/$type/$pcpid", array(), drupal_get_destination());
        $row['mirror'] = 'Coming Soon';
        
        $rows[] = $row;
      }
    }    
  }
  else {
    foreach ($collectioncfg as $pcpid => $pcpanel) {
      $pcpanel = og_collections_load_pcpanel($pcpanel['did'], FALSE);
      if ($pcpanel->active) {
        $row = array();
        $row['page_title'] = $pcpanel->page_title;
        $row['default_page'] = $pcpanel->default_page ? 'Yes' : 'No';
        $row['content'] = l(t('Content'), "admin/og/og_collections/pcpanel/content/$pcpid", array(), drupal_get_destination());
        $row['layout'] = l(t('Layout'), "admin/og/og_collections/pcpanel/layout/$pcpid", array(), drupal_get_destination());
        $row['layset'] = l(t('Layout Settings'), "admin/og/og_collections/pcpanel/layset/$pcpid", array(), drupal_get_destination());
        $row['mirror'] = 'Coming Soon';
        
        $rows[] = $row; // any utility in making the rows array associative?
      }
    }
  }
  
  if ($isdefault) {
    $header = array(t('Panel Name'), t('Home Page?'), t('Edit Content'), t('Edit Layout'), t('Edit Layout Settings'), t('Import Template'));
  }
  else {
    $header = array(t('Panel Name'), t('Tied to Default'), t('Home Page?'), t('Edit Content'), t('Edit Layout'), t('Edit Layout Settings'), t('Revert to Default'), t('Import Template'));
  }
  $linktext = "admin/og/og_collections/collectioncfg";
  $linktext .= $isdefault ? "" : "/$type";
  $output .= theme('table', $header, $rows);
  $output .= t('<p>Pre-configured panels that have been disabled in !panpcpanel will not appear in the above list. You must enable them before you can edit them here.</p>', array('!panpcpanel' => l(t('Panel Templates'), $linktext)));
  return $output;
}

/*
 * Form to add/edit a pre-configured panel. if a $did is passed in, it edits that pcpanel. if there's no $did, it creates a new pcpanel.
 */
function og_collections_pcpanel_form($did = NULL) {
  if ($did) {
    $pcpanel = og_collections_load_pcpanel($did, FALSE);
  }
  drupal_set_title($did ? "Configure $pcpanel->page_title Template" : "Add New Pre-Configured Panel");
  
  $form['page_title'] = array(
    '#title' => t('Panel Name Title'),
    '#type' => 'textfield',
    '#required' => TRUE,
    '#default_value' => $did ? $pcpanel->page_title : NULL,
    '#disabled' => $pcpanel->default_page ? TRUE : FALSE,
    '#description' => t('The title for the page and of the tab that will be used by default when this pre-configured panel is instantiated.'),
    '#size' => 32,
  );
  $form['path'] = array(
    '#title' => t('Default Path'),
    '#type' => 'textfield',
    '#default_value' => $pcpanel->default_page ? '' : $pcpanel->path,
    '#required' => $pcpanel->default_page ? FALSE : TRUE,
    '#description' => $pcpanel->default_page ? t('This pre-configured panel is currently set to act as the group home page and therefore cannot be assigned a default path.') : t('The sub-path (appearing after the root group path) this pre-configured panel will appear at upon instantiation.'),
    '#disabled' => $pcpanel->default_page ? TRUE : FALSE,
    '#size' => 32,
  );
  $form['show_blocks'] = array(
    '#title' => t('Show blocks'),
    '#type' => 'checkbox',
    '#default_value' => $did ? $pcpanel->show_blocks : TRUE,
    '#description' => t('If unchecked, unmodified instantiations of this pre-configured panel will NOT show the standard group blocks.'),
  );
  $form['published'] = array(
    '#type' => 'checkbox',
    '#title' => t('Published'),
    '#default_value' => $did ? $pcpanel->published : FALSE,
    '#description' => t('If unchecked, instantiations of this pre-configured panel will initially be unpublished and viewable only by site or group administrators. Keeping this unchecked is wise if the page contains information that is not automatically present on group creation, and having this page accessible but empty would reflect poorly on the group.'),
  );
  
  $form['submit'] = array(
    '#type' => 'submit', 
    '#value' => $did ? t('Update Pre-configured Panel') : t('Create Pre-configured Panel'),
  );
  $form['did'] = array('#type' => 'value', '#value' => $did);
  return $form;
}

// FIXME NEED a validation function to ensure that paths entered are valid.
function og_collections_pcpanel_form_validate($form_id, $form_values, $form) {
  
}

/**
 * Creates a new panel pre-configured panel, or modifies an existing one. Also ensures that all relevant
 * collectioncfgs are updated with the new panel information.
 **/
function og_collections_pcpanel_form_submit($form_id, $form_values) {
  if ($form_values['did']) {
    $pcpanel = og_collections_load_pcpanel($form_values['did'], FALSE);
    $pcpanel->page_title = $form_values['page_title'];
    $pcpanel->path = $form_values['path'];
    $pcpanel->show_blocks = $form_values['show_blocks'];
    $pcpanel->published = $form_values['published'];
    og_collections_save_pcpanel($pcpanel);
    drupal_set_message(t('Pre-configured panel "'. $pcpanel->panel_title .'" has successfully been updated.'));
    return 'admin/og/og_collections/collectioncfg'; // TODO return to the page that the edit was called from?
  }
  else {
    // Create a new display in the default grouptype
    $display = panels_new_display();
    panels_save_display($display);
    // grouptype doesn't need to be included; column defaults to 'default', and new panel pcpanels are always in the default grouptype
    $pcpid = db_next_id("{og_collections_pcpanel}_pcpid");
    og_collections_manage_db('pcpid_'. $pcpid, 'add');
    db_query("INSERT INTO {og_collections_pcpanel} (did, pcpid) VALUES (%d, %d)", $display->did, $pcpid);
    drupal_set_message(t("The pre-configured panel '%title' created, and has been added to the Default collection. You must now select a default layout.", array('%title' => $form_values['page_title'])));
    // Update all collectioncfgs to reflect new pre-configured panel. might be worth turning this into a hook at some point, at least in the generalized module.
    // if this mass-update method is useful somewhere else, split it out into some separate function
    $conf = array(
      'active' => 0,
      'default_page' => 0,
      'weight' => 0, 
      'did' => $display->did,
      'usedef' => 1,
      'page_title' => $form_values['page_title'],
      'path' => $form_values['path'],
      'published' => $form_values['published'],
      'show_blocks' =>  $form_values['show_blocks'],
      'grouptype' => 'default',
    );
    $group_types = og_collections_group_types(TRUE);
    foreach (array_keys($group_types) as $type) {
      $collectioncfg = og_collections_load_collectioncfg($type);
      $collectioncfg[$pcpid] = $conf;
      og_collections_save_collectioncfg($type, $collectioncfg, array($pcpid));
    }
    drupal_get_destination();
    return 'admin/og/og_collections/pcpanel/layout/'. $pcpid; // redirect to layout selection
  }
}

/**
 * Central pre-configured panel management function, redirects requests based on supplemental args; takes any number of args that can be passed to the 
 * 'admin/og/og_collections/pcpanel' URL and dispatches them appropriately
 */
function og_collections_pcpanel_manage() {
  $args = func_get_args();
  $op = array_shift($args);
  $dest = drupal_get_destination();
  $error = $success = '';
  $collectionsetting = variable_get('og_collections_settings', FALSE);
  $multi = $collectionsetting == 1 ? FALSE : TRUE;
  
  switch ($op) {
    case 'form':
      if (!empty($args[0]) && !empty($args[1])) {
        if (is_string($args[0]) && is_numeric($args[1])) {
          if ($pcpanel = og_collections_load_pcpanel(array($args[0], $args[1]))) {
            $output = drupal_get_form('og_collections_pcpanel_form', $pcpanel->did);
          }
          else {
            $error = 'No pre-configured panel was loaded with the arguments provided.';
            break;
          } 
        }
        else {
          $error = 'The arguments provided were in an invalid format.';
          break;
        }
      }
      else {
        $output = drupal_get_form('og_collections_pcpanel_form');
      }
      return $output;

    case 'layout':
    case 'content': // FIXME display_edit.inc in Panels needs to be updated with a different return value if the form is cancelled. Or something.
    case 'layset':
      if (is_numeric($args[0])) { // editing the default version of a pre-configured panel 
        list($pcpid) = $args;
        $result = og_collections_pcpanel_edit($op, $pcpid, $error, $success);
      }
      elseif (is_string($args[0])) { // editing a group type specific version of a pre-configured panel
        list($type, $pcpid) = $args;
        $result = og_collections_pcpanel_edit($op, $pcpid, $error, $success, $type);
      }
      if ($result) {
        return $result; // only anything is returned into result is when the form strings need to be returned for processing
      }
      // all other situations (errors, success, whatever), result in a break
    break;
          
    case 'revert': // reverting a given page pcpanel to default and re-linking it
      if (!$multi) {
        $error = 'Reversion is pointless if you are using only one collection for all your group types. How did you even GET here!?!'; // =)
        break;
      }
      if (isset($args[0], $args[1])) {
        if (is_string($args[0]) && is_numeric($args[1])) {
          $pcpanel = og_collections_load_pcpanel(array($args[0], $args[1]), FALSE);
          return drupal_get_form('og_collections_pcpanel_revert_confirm', $pcpanel);
        }
      }
    break;
    
    case 'delete': // delete a given pcpanel
      if (!isset($args[0]) || !is_numeric($args[0])) {
        $error = 'A valid pcpid must be supplied if you want to delete a pre-configured panel.';
        break;
      }
      if ($multi) {
        $dids = db_num_rows(db_query("SELECT * FROM {og_collections_pcpanel} WHERE pcpid = %d", $args[0]));
        drupal_set_message(t('WARNING: Deleting this pre-configured panel will remove it for ALL group types. This will result in the automatic, irreversible deletion of the <strong>%dids</strong> uniquely configured display(s) that correspond to this pre-configured panel. If you just want the pre-configured panel to not be instantiated for a particular group type, simply disable it on the !link', array('%dids' => $dids, '!link' => l(t('Panel Templates'), 'admin/og/og_collections/collectioncfg'))));
      }
    return drupal_get_form('og_collections_pcpanel_delete_confirm', $args[0], $multi);  
    break;
    
  }
  if (!empty($error)) {
    drupal_set_message($error, 'error');
    drupal_goto();
  }
  elseif (!empty($success)) {
    drupal_set_message($success);
    drupal_goto();
  }
}

function og_collections_pcpanel_revert_confirm($pcpanel) {
  $form['pcpid'] = array('#type' => 'value', '#value' => $pcpanel->pcpid);
  $form['type'] = array('#type' => 'value', '#value' => $pcpanel->grouptype);
  $form['page_title'] = array('#type' => 'value', '#value' => $pcpanel->page_title);
  
  return confirm_form($form,
    t('Are you sure you want to revert the type-specific pre-configured panel %title back to the Default type?', array('%title' => $pcpanel->page_title)),
    "admin/og/og_collections/pcpanelsetup/$pcpanel->grouptype",
    t('This action CANNOT be undone; any custom type-specific changes you have made to this pre-configured panel will be PERMANENTLY lost.'),
    t('Revert'), t('Cancel')
  );
}

function og_collections_pcpanel_revert_confirm_submit($form_id, $form_values) {
  $pcpanel = og_collections_load_pcpanel(array($form_values['type'], $form_values['pcpid']), FALSE);
  $defcollectioncfg = og_collections_load_collectioncfg();
  $collectioncfg = og_collections_load_collectioncfg($pcpanel->grouptype);
  $collectioncfg[$pcpanel->pcpid]['usedef'] = 1;
  $collectioncfg[$pcpanel->pcpid]['did'] = $defcollectioncfg[$pcpanel->pcpid]['did'];
  panels_delete_display($pcpanel->did);
  db_query("DELETE FROM {og_collections_pcpanel} WHERE pcpid = %d AND grouptype = '%s'", $pcpanel->pcpid, $pcpanel->grouptype);
  og_collections_save_collectioncfg($pcpanel->grouptype, $collectioncfg, array($pcpanel->pcpid)); 
}


function og_collections_pcpanel_delete_confirm($pcpid) {
  $collectioncfg = og_collections_load_collectioncfg();
  $form['pcpid'] = array('#type' => 'value', '#value' => $pcpid);
  $form['page_title'] = array('#type' => 'value', '#value' => $collectioncfg[$pcpid]['page_title'] ? $collectioncfg[$pcpid]['page_title'] : '');
  
  return confirm_form($form,
    t('Are you sure you want to delete the %title pre-configured panel?', array('%title' => $collectioncfg[$pcpid]['page_title'] ? $collectioncfg[$pcpid]['page_title'] : '')),
    isset($_GET['destination']) ? $_GET['destination'] : 'admin/og/og_collections/collectioncfg',
    t('This action CANNOT be undone.'),
    t('Delete'), t('Cancel')
  );
}

function og_collections_pcpanel_delete_confirm_submit($form_id, $form_values) {
  og_collections_pcpanel_delete($form_values['pcpid']);
  drupal_set_message(t('%title has been deleted.', array('%title' => $form_values['page_title'])));
}

// very dangerous function. validate thoroughly before calling.
function og_collections_pcpanel_delete($pcpid) {
  $result = db_query("SELECT did FROM {og_collections_pcpanel} WHERE pcpid = %d", $pcpid);
  while ($row = db_fetch_array($result)) {
    panels_delete_display($row['did']);
  }
  db_query("DELETE FROM {og_collections_pcpanel} WHERE pcpid = %d", $pcpid);
  og_collections_manage_db('pcpid_'. $pcpid, 'drop');
}

/*
 * Function that handles the panels API editing for all three panels
 * editing types - display editing (i.e., content), layout, and layout settings. 
 */
function og_collections_pcpanel_edit($op, $pcpid, &$error, &$success, $type = 'default') {
  if (!$pcpanel = og_collections_load_pcpanel(array($type, $pcpid), TRUE)) { 
    if (!$pcpanel = og_collections_load_pcpanel(array('default', $pcpid), TRUE, $type)) { // only way this happens is with a bad pcpid. error out.
      $error .= 'ERROR: Bad pcpid provided. The pre-configured panel you are attempting to edit does not exist.';
      return FALSE;
    }
    $isnew = TRUE;
    if (isset($_POST['op'])) {
      if ($_POST['op'] == 'Save') { // this is the second passthrough, and the user has chosen to save the panel; we slip the exported panel w/the 'new' $did so the submit function operates on that one instead
        og_collections_export_display($pcpanel->display);
      }
      elseif ($_POST['op'] == 'Cancel') {
        $success = t('Operation cancelled. A collection-specific panel has NOT been created; your pre-configured panel is still tied to the Default.');
        return $success;
      }
    }
    else {
      $group_types = og_collections_group_types();
      $newdisplay = 'NOTE: The !grouptype collection is currently tied to the Default type for this panel. If you save changes on this page, a version of this pre-configured panel specific to the !grouptype collection will be generated, and this panel\'s link to the Default pre-configured panel will be broken.';
      drupal_set_message(t($newdisplay, array('!grouptype' => $group_types[$type])));
    }
  }
  switch ($op) {
    case 'content':
      $saved = panels_edit($pcpanel->display, NULL, $pcpanel->display->content_types);
      break;
    case 'layout':
      $saved = panels_edit_layout($pcpanel->display, t('Save'), NULL);
      break;
    case 'layset':
      $saved = panels_edit_layout_settings($pcpanel->display, t('Save'), NULL);
      break;
  }
  
  if (!isset($_POST['op'])) {
    $error = FALSE;
    if ($op == 'content') {
      print theme('page', $saved, FALSE);
      return FALSE;
    }
    return $saved;
  }  
  elseif ($_POST['op'] == 'Save' && is_object($saved)) { // if it's not an object at this stage, something's wrong. error out
    if ($isnew) {
      $pcpanel->display = $saved;
      $pcpanel->did = $pcpanel->display->did;
      $pcpanel->usedef = 0;
      $pcpanel->grouptype = $type;
      og_collections_save_pcpanel($pcpanel, TRUE);
    }
    $success = 'The settings for this pre-configured panel have been successfully updated.';
  }
  else {
        $error .= 'An unknown error occurred, causing the panels edit function to return an unidentified string. No changes have been saved to the pre-configured panel, but changes MAY have been saved to the panels display.'; // returns string on errors
  }
}

function og_collections_admin() {
  $ops = variable_get('og_collections_settings', 0);
  $helptext = t("<p>Group 'pre-configured panels' are saved collections of panels and settings that encompass all the options you are able to manually set for an individual group using OG Panels. By defining collections, you can automatically apply these collections to new groups as they are created.</p>");
  switch ($ops) {
    case 0:
       $helptext .= t("
                <p>Once activated, OG Collections allows varying levels of granularity in configuring these pre-configured panels. However, collections are currently disabled. Select one of the 'Enabled' settings below to begin collections.</p>
                <ul><li>Selecting 'Enabled - One Overall Template' will cause ALL of your group types to use the same pre-configured panel.</li>
                <li>Selecting 'Enabled - Templates Per Type' will allow you to define pre-configured panels for each group type you have defined in !ogadmin.</li></ul>", array('!ogadmin' => l(t('Organic Groups Configuration'), 'admin/og/og')));
    break;
    case 1:
      // TODO need to write up additional helptext for circumstances where the user may be switching from one collections configuration to another, once the backend has been written

    break;
    case 2:
      // TODO ditto above
    break;
  }
  
  $options = array('Disabled', 'Enabled - One Overall Template', 'Enabled - Templates Per Type');
  $form['og_collections']['helptext'] = array('#value' => $helptext);
  $form['og_collections']['collectionsetting'] = array (
    '#type' => 'radios',
    '#title' => t('Group Collections Settings'),
    '#options' => $options, 
    '#default_value' => $ops,
    '#required' => TRUE,
  );
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save Configuration'),
    '#id' => 'panels-dnd-save',
  );
  return $form;
}

function og_collections_admin_submit($form, $form_values) {
  variable_set('og_collections_settings', $form_values['collectionsetting']);
  if ($form_values['collectionsetting'] == 0) {
    $msg = t('Group Collections have been disabled. Any pre-configured panel configuration you have done will be accessible if you reactive Group Collections.');
  }
  else if ($form_values['collectionsetting'] == 1) {
    $msg = t('Group Collections have been enabled, using one collection for all group types. You can configure your collection in !ogpanel.', array('!ogpanel' => l(t('Panel Templates'), 'admin/og/og_collections/collectioncfg')));
  }
  else if ($form_values['collectionsetting'] == 2) {
    $msg = t("Group Collections have been enabled, with one pre-configured panel allowed per group type. You can configure all of your collections in !ogpanel. Make sure to set up pre-configured panels for all desired group types now, as there is currently no way to retrofit existing groups with pre-configured panels you update later.", array('!ogpanel' => l(t('OG Collections Configuration'), 'admin/og/og_collections/collectioncfg')));
  }
  drupal_set_message($msg);
  cache_clear_all('*', 'cache_menu', TRUE);
  return NULL;
}

/**
 * Implementation of hook_nodeapi()
 * 
 * og_collections uses nodeapi to trigger the automated duplication of
 * pcpanel collections into actual og panels whenever a group of the
 * appropriate type is created.
 * 
 * // TODO consider switching to workflow_ng for this
 *
 */
function og_collections_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {
  switch ($op) {
    case 'insert':
      if ($collectionsetting = variable_get('og_collections_settings', FALSE)) {
        $group_types = og_collections_group_types();
        if (in_array($node->type, array_keys($group_types))) {
          $multi = $collectionsetting == 1 ? FALSE : TRUE;
          $defaultcfg = og_collections_load_collectioncfg(); // we'll need the default regardless of $multi
          if ($multi) {
            $collectioncfg = og_collections_load_collectioncfg($node->type);
            foreach ($collectioncfg as $pcpid => $conf) {
              if (!empty($conf['active'])) {
                $toinsert[$pcpid] = !empty($conf['usedef']) ? $defaultcfg[$pcpid]['did'] : $conf['did']; // $conf will theoretically have the right $did either way, but this is the surefire way
              }
            }
          }
          else {
            $type = 'default';
            $collectioncfg = $defaultcfg;
            foreach ($collectioncfg as $pcpid => $conf) {
              if (!empty($conf['active'])) {
                $toinsert[$pcpid] = $conf['did'];
              }
            }
          }
        }
        
        if (!is_null($toinsert)) {
          // now, attach the pcpanels to the nid via og_panels!
          foreach ($toinsert as $pcpid => $did) {
            $status = _og_collections_panelize_group($did, $node->nid, $collectioncfg[$pcpid], $pcpid);
            if ($status == 'error') {
              $message = t("Error occurred while adding the '!page_title'' pre-configured panel to the new '!groupname' group.", array('!page_title' => $collectioncfg[$pcpid]['page_title'], '!groupname' => $node->title));
            }
            elseif ($status == 'status') {
              $message = t("The '!page_title'' pre-configured panel was successfully added to the new '!groupname' group.", array('!page_title' => $collectioncfg[$pcpid]['page_title'], '!groupname' => $node->title));
            }
            drupal_set_message($message, $status);
          }
        }
      }
      break;
  }
}

/**
 * Add a pcpanel to a newly-created group, per the parameters passed in.
 *
 * @param int $did
 *  the did of the display being exported
 * @param int $nid
 *  the nid of the newly-added group node
 * @param array $conf
 *  a configuration array specific to the pcpanel being added in this iteration (@see og_collections_nodeapi())
 * @param int $pcpid
 *  the pcpid from which the panel is being instantiated
 * @return string $status
 *  the type of message to report back on adding the pcpanel with - status or error
 */
function _og_collections_panelize_group($did, $nid, $conf, $pcpid) {
  $display = panels_load_display($did);
  og_collections_export_display($display, $nid);
  panels_save_display($display);
  $fields = og_collections_panel_fields();
  $conf['nid'] = $nid;
  $conf['did'] = $display->did;
  $conf['frompcpanel'] = $pcpid; // FIXME there needs to be a better, more comprehensive method of tracking this relationship. dids can go away, all too easily
  if (!empty($conf['default_page'])) { // by default, og_panels removes any paths that were assigned to homepages. if this is gonna be a homepage, don't put in a path
    $conf['path'] = '';
  }
  foreach ($fields as $field => $value) {
    $f[] = $field;
    $q[] = $value;
    $v[] = $conf[$field];
  }
  
  db_query("INSERT INTO {og_panels} (". implode(', ', $f) .") VALUES (". implode(', ', $q) .")", $v);
  $status = db_error();
  return $status ? 'error' : 'status'; // returns string to set $status in drupal_set_message
}

// -------------------------------------------------------------------------
// Collections Helper functions, esp. save/load

/**
 * Adds/removes fields from the collectioncfg table as needed.
 * 
 * Plays nice with both mysql and pgsql. The ONLY time this function gets called is when a pcpanel is deleted, or a new one is created. 
 *
 * @param string $fieldname
 * @param string $op
 *  must be either 'add' or 'drop'
 * @return mixed
 *  ONLY returns FALSE if a bad $op value has been passed. Otherwise, void
 */
function og_collections_manage_db($fieldname, $op) {
  if (strtolower($op) != ('add' || 'drop')) {
    // bad $op
    return FALSE;
  }
  switch ($GLOBALS['db_type']) {
    case 'mysql':
    case 'mysqli':
      if ($op == 'add') {
        db_query("ALTER TABLE {og_collections} ADD COLUMN $fieldname LONGTEXT NOT NULL");
      }
      elseif ($op == 'drop') {
        db_query("ALTER TABLE {og_collections} DROP COLUMN $fieldname");
      }
    break;
    
    case 'pgsql':
      if ($op == 'add') {
        db_add_column($ret, 'og_collections', $fieldname, 'TEXT'); 
      }
      elseif ($op == 'drop') {
        db_query("ALTER TABLE {og_collections} DROP $fieldname");
      }
    break;
  }
}


/**
 * Update the database with the new id values for the exported pcpanel.
 *
 * @param obj $pcpanel
 *  A pcpanel object. Only needs $collectioncfg values to perform this operation; $display is unnecessary 
 */
function og_collections_pcpanel_handle_export($pcpanel) {
  db_query("DELETE FROM {og_collections_pcpanel} WHERE pcpid = %d AND grouptype = '%s'", $pcpanel->pcpid, $pcpanel->grouptype); // in case of a residual display that avoided deletion
  db_query("INSERT INTO {og_collections_pcpanel} (did, pcpid, grouptype) VALUES (%d, %d, '%s')", $pcpanel->did, $pcpanel->pcpid, $pcpanel->grouptype);
}

function og_collections_export_display(&$display, $nid = NULL) {
  eval(panels_export_display($display));
  panels_load_include('plugins');
  panels_load_include('common');
  $display->context = !is_null($nid) ? array('og_panels' => panels_context_create('group', $nid)) : array('og_panels' => panels_context_create_empty('group'));
  $display->content_types = panels_common_get_allowed_types('og_panels', $display->context);
  return $display; // just to be nice, return as well as by reference
}

/**
 * Loads a pre-configured panel object.
 *
 * @param mixed $op
 *   Either a valid $did, or an array that should be defined as follows:
 *   array($grouptype, $pcpid), corresponding to values in the og_collections_pcpanel table.
 * @param bool $loaddisplay = TRUE
 *   If TRUE, the $pcpanel object will also be loaded with corresponding $display information.
 * @param string $type2 = NULL
 *   Use this parameter if the collectioncfg to be loaded is different from the collectioncfg 
 *   corresopnding to param1. Primarily for exporting/reversion. 
 * @return mixed
 *   Returns an object if all goes well. If type/pcpid provided were no good, FALSE is returned.
 *   If a bad did is provided, returns NULL.
 */
function og_collections_load_pcpanel($op, $loaddisplay = TRUE, $type2 = NULL) {
  if (is_array($op) && (is_string($op[0]) && is_numeric($op[1]))) {
    $result = db_query("SELECT * FROM {og_collections_pcpanel} WHERE grouptype = '%s' AND pcpid = %d", $op[0], $op[1]);
  }
  elseif (is_numeric($op)) {
    $result = db_query("SELECT * FROM {og_collections_pcpanel} WHERE did = %d", $op);
  }
  
  if ($pcpanel = db_fetch_object($result)) {
    if ($loaddisplay) {
      $pcpanel->display = panels_load_display($pcpanel->did);
      panels_load_include('plugins');
      $pcpanel->display->context = array('og_panels' => panels_context_create_empty('group'));
      panels_load_include('common');
      $pcpanel->display->content_types = panels_common_get_allowed_types('og_panels', $pcpanel->display->context); // TODO this is a taxing operation - cache it in some way if possible. store content_types in collectioncfg?
    }
    $collectioncfg = og_collections_load_collectioncfg($type2 ? $type2 : $pcpanel->grouptype);
    if (isset($collectioncfg[$pcpanel->pcpid])) { 
      foreach ($collectioncfg[$pcpanel->pcpid] as $key => $value) {
        if ($key != 'did') {
          $pcpanel->$key = $value;
        }
      }
    }
    return $pcpanel;
  }
  else {
    return is_array($op) ? FALSE : NULL; // returns false if a type/pcpid was provided and got nothing; returns NULL if a did was provided and got nothing 
  }
}

/**
 * Save a pcpanel object to the database.
 * 
 * @param object $pcpanel
 * @param bool $export
 */
function og_collections_save_pcpanel($pcpanel, $export = FALSE) {
  $collectioncfg = og_collections_load_collectioncfg($pcpanel->grouptype);
  foreach ((array)$pcpanel as $key => $value) {
    if (in_array($key, array('pcpid', 'display', 'content_types'))) {
      continue;
    }
    $collectioncfg[$pcpanel->pcpid][$key] = $value;
  }
  if ($export) {
    og_collections_pcpanel_handle_export($pcpanel);
  }
  og_collections_save_collectioncfg($pcpanel->grouptype, $collectioncfg, array($pcpanel->pcpid));
}

/**
 * Load all collection configurations into an associative array, keyed by grouptype.
 * 
 * Rows are, by default, cached into a static variable. Will only requery to pick up a new set of
 * collectioncfgs if $refresh is TRUE
 * 
 * @param bool $refresh
 * @return mixed $rows
 *   returns FALSE if no results are found.
 */
function og_collections_load_collectioncfgs($refresh = FALSE) {
  static $rows;
  if (!$rows || $refresh == TRUE) {
    $result = db_query("SELECT * FROM {og_collections}");
    if (count(db_fetch_array($result)) != 1) { // only occurs if no pre-configured panels have been created yet.
      $result = db_query("SELECT * FROM {og_collections}"); // TODO ugh - have to double-query until D6 solves this problem w/schema
      while ($row = db_fetch_array($result)) {
        $grouptype = array_shift($row); // gets rid of grouptype, which is always first
        foreach ($row as $pcpid => $vals) {
          $arr[(int)substr($pcpid, 6)] = $vals ? unserialize($vals) : array();
        }
        uasort($arr, '_collectioncfg_sort'); // TODO consider trying to move this into the single load function somehow; could improve performance a bit
        $rows[$grouptype] = $arr;
        unset ($arr);
      }
    }
  }
  return $rows ? $rows : FALSE;
}


/**
 * Specialized sort function. Sorts a given collectioncfg $conf array by the following criteria:
 * 1. Default Page status
 * 2. Active status (enabled/disabled in the current pre-configured panel)
 * 3. Weight
 */
function _collectioncfg_sort($a, $b) {
  $default_page = $b['default_page'] - $a['default_page'];
  if ($default_page) {
    return $default_page;
  }
  
  $active = $b['active'] - $a['active'];
  if ($active) {
    return $active;
  }
  
  // if ($a['active']) return ($a['weight'] - $b['weight']);
  return ($a['weight'] - $b['weight']);
}

/**
 * As with og_collections_load_collectioncfgs, uses static var to reduce db queries. only will refresh if explicitly instructed to do so,
 * and does so by passing that parameter on to the other load function
 */
function og_collections_load_collectioncfg($type = 'default', $refresh = FALSE) {
  static $collectioncfgs;
  if (!$collectioncfgs || $refresh == TRUE) {
    $collectioncfgs = og_collections_load_collectioncfgs($refresh);
  }
  if ($collectioncfgs) {
    if (!isset($collectioncfgs[$type])) {
      $collectioncfgs[$type] = og_collections_new_collectioncfg($type, $collectioncfgs['default']);
    }
    return $collectioncfgs[$type];
  }
}

function og_collections_new_collectioncfg($type, $collectioncfg) {
  db_query("INSERT INTO {og_collections} (grouptype) VALUES ('%s')", $type);
  $pcpids = array_keys($collectioncfg);
  return og_collections_save_collectioncfg($type, $collectioncfg, $pcpids);
}