[Bb-trac] Re: [bbPress] #620: Front-end changes to enable forum hierarchy

[bbPress]

#620: Front-end changes to enable forum hierarchy
-------------------------+--------------------------------------------------
 Reporter:  sambauers    |        Owner:  sambauers
     Type:  enhancement  |       Status:  new      
 Priority:  normal       |    Milestone:  1.0      
Component:  Front-end    |      Version:  0.8.1    
 Severity:  normal       |   Resolution:           
 Keywords:  has-patch    |  
-------------------------+--------------------------------------------------
Comment (by mdawaffe):

 WordPress' post loop has been extremely successful, largely because of how
 completely customizable the markup it generates is.  I think we need
 something equally customizable for bbPress forum "loop" (and topics and
 posts too), except that it will have to handle hierarchy too.

 Here's what I came up with.  It's heavily based on sambauers' patch above.
 The template would look like:

 {{{
 <?php if ( bb_forums() ) : ?>

 <h2><?php _e('Forums'); ?></h2>
 <table id="forumlist">

 <tr>
         <th><?php _e('Main Theme'); ?></th>
         <th><?php _e('Topics'); ?></th>
         <th><?php _e('Posts'); ?></th>
 </tr>

 <?php while ( bb_forum() ) : ?>

 <tr<?php bb_forum_class(); ?>>
         <td><?php bb_forum_pad( ' &#8212; ' ); ?><a href="<?php
 forum_link(); ?>"><?php forum_name(); ?></a><small><?php
 forum_description(); ?></small></td>
         <td class="num"><?php forum_topics(); ?></td>
         <td class="num"><?php forum_posts(); ?></td>
 </tr>

 <?php endwhile; ?>

 </table>

 <?php endif; ?>
 }}}

  1. {{{bb_forums()}}} sets up the loop and takes two forms:
   1. {{{bb_forums( $get_forums_formatted_args );}}}
   2. {{{bb_forums( [ one of 'flat', 'ul' ], $get_forums_formatted_args
 );}}}
  All parameters are optional.

  In the second form, you can specify whether the loop should be "flat" (no
 structural hierarchy will appear in the html except what you put in
 manually (see below)) or should be a hierarchical, nested UL.  "flat" is
 good for flat tables and is the default behavior.
  2. {{{bb_forum()}}} advanceds the loop.  Everything inside the
 {{{while}}} block will be printed for each forum.   The function returns
 the hierarchy's current depth, so you can do

 {{{
 while ( $depth = bb_forum() ) :
 }}}

  and do something fancy with that.
  3. {{{bb_forum_pad( $pad )}}} just {{{str_repeat()}}}s {{{$pad}}} a
 number of times equal to the current depth in the hierarchy.  You can use
 it to print out a bunch of EMdashes as in the example above, or something
 fancier like:

 {{{
 bb_forum_pad( '<span class="nest"> ); bb_forum_name(); bb_forum_pad(
 '</span>' );
 }}}
  4. {{{bb_forum_class()}}} outputs a host of hierarchically based classes
 on wihch to wield CSS-fu.

 ----

 The above point 1 isn't super clear.  Let me give two code examples and
 their resulting markup.

 {{{
 <?php if ( bb_forums() ) : // See if there are forums and set up the loop.
 'flat' is the default ?>

 <table>

 <tr>
  <th>Name</th>
 </tr>

 <?php while ( bb_forum() ) : // Advance the loop ?>

 <tr>
  <td><?php bb_forum_pad( ' - ' ); forum_name(); ?>
 </tr>

 <?php endwhile; ?>

 </table>

 <?php endif; ?>
 }}}

 Will produce

 {{{
 <table>

 <tr>
  <th>Name</th>
 </tr>

 <tr>
  <td>Forum 1</td>
 </tr>

 <tr>
  <td> - Forum 1.1</td>
 </tr>

 <tr>
  <td>Forum 2</td>
 </tr>

 </table>
 }}}

 And

 {{{
 <?php if ( bb_forums( 'ul' ) ) : // 'ul' for hierarchical UL ?>

 <ul>

 <?php while ( bb_forum() ) : ?>

 <li><?php forum_name(); ?></li>

 <?php endwhile; ?>

 </ul>

 <?php endif; ?>
 }}}

 Will produce

 {{{
 <ul>

  <li>Forum 1
   <ul>
    <li>Forum 1.1</li>
   </ul>
  </li>

  <li>Forum 2</li>

 </ul>
 }}}

 (Whitespace edited for clarity.)

 ----

 Accomplished by

  1. BB_Walker class.  Walker wasn't quite up to the task, though I think
 BB_Walker is 100% backward compatible, so I'll see if WP will take it over
 after their next release.
  2. BB_Loop class. Sets up, controls, and advances the arrays and pointers
 of a Walker object.  Abstract versions of bb_forums(), bb_forum(),
 bb_forum_pad(), bb_forum_class().  Can be used for other template loops
 like topics, posts, etc.
  3. Corrupting sambauer's patch and using his array skillz and admin code.

 ----

 It isn't *quite* as easy as WordPress' post loop (it is without the
 "hidden" flat/UL feature), but I think it's not too bad.

 Opinions?

-- 
Ticket URL: <http://trac.bbpress.org/ticket/620#comment:9>
bbPress <http://bbpress.org/>
Innovative forum development