/**
 * $Id$
 * @package OG_Forum
 * @category NeighborForge
 */
This module extends the forum module to allow for Organic Groups to have their own forums.
When viewing groups, only forum discussions for that group are displayed. This module does
not hinder the creation of site-wide forums in any way. You can have both OG forums and
site-wide forums.  There are a multitude of settings for customizing how these forums work.
which are detailed below.

--CONTENTS--
  REQUIREMENTS
  INSTALL
  SETUP
  FEATURES
  USAGE (Example)
  THEMING
  CREDITS
  
--REQUIREMENTS--
  This module requires both the OG module and the Forum module from Core to be installed.
     
--INSTALL--
  Before you post an issue to the queue with installation problems, be sure you did all
  of these things in this order:
  
  FOR A NEW SITE/ONE WITHOUT OG ALREADY INSTALLED
    1) Install the forum module through the regular Drupal means.
    
    2) Trigger the forum vocabulary creation routine by visiting admin/forums - this is
       the part most often overlooked.
       
    3) Install OG through the regular Drupal means.
    
    4) Install this module, again through the regular Drupal means.
  
  FOR A SITE WITH OG ALREADY INSTALLED
    1) Install the forum module through the regular Drupal means.
    
    2) Trigger the forum vocabulary creation routine by visiting admin/forums - this is
       the part most often overlooked.
       
    3) Install this module, again through the regular Drupal means.
    
    4) Go to admin/og/og_forum and click on "Update old groups" to have forum containers
       and default forums created for existing groups. See the FEATURES section for
       options.

--SETUP--
  There are two permissions that you can assign to roles: 'make forums public' and
  'admin own group forums'. The former is to allow non-group-owners the ability to set
  the publicity of forums in groups. Usually, you will want to reserve this for admins.
  
  The latter is to allow group owners all privileges for administering forums of their
  groups.

--FEATURES--
  At admin/og/og_forum there are a bunch of options divided into five groups, three of
  which are fieldsets. The groupings are:
  
  -Retroactively update old groups
  -Default forum name
  -Group forum container
  -Forum publicity administration
  -Limit number of forums per group
  
  RETROACTIVELY UPDATE OLD GROUPS
    This is a single button which adds containers and forums to each existing OG and is
    to be used if you install og_forum into a site where groups already exist. You may
    wish to change some settings below before pushing this button.
    
  DEFAULT FORUM NAME
    When a new group is created, or during the retroactive forum creation function, each
    group is given a forum container with the term name of the group's name as well as one
    default forum. Normally, the default forum is called "General discussion". You may
    change that name here.
    
    CAVEAT - Having the container name the same as the group name makes it easy for people
      to find the group's forum in a site-wide listing of forums like at the 'forum' URL.
      This container's name will change as the group's name is changed.
  
  GROUP FORUM CONTAINER
    Rather than have all groups' containers and forums show up at the site-wide level, you
    may designate another (pre-existing) container for all group containers to be placed in.
    This alternate container may be any number of levels deep in the forum structure. To
    use this feature, check the box and select the container.
    
  FORUM PUBLICITY ADMINISTRATION
    This section has several controls which work together as follows:
    
   -AUTOMATIC FORUM PUBLICITY
      This turns on/off the automatic publicity of group forums. If a group forum has at
      least one post which is public, then entries will be made in the database to indicate
      that the forum and its container are also publicly browsable. If a group forum does
      not have any public posts, then that forum will not be publicly browsable except as
      noted below in conjunction with other settings.
      
      NOTE: The automatic setting uses two values for storing the forum and containers'
      states - PRIVATE_DEFAULT and PUBLIC_AUTO.
      
   -ALLOW PUBLIC CHOICE
      This allows group owners to decide which of their forums are public or private, but
      can also work with the auto setting above. First an explanation without the auto
      setting:
      
        In each forum, the group owner (or admins) will see a link in the context menu to
        'Administer group forums' which presents a table structure whereby they may edit
        forums' names or delete them, add forums to the container, make them public,
        make them private, or reset them. The publicity settings enter these values into the
        database - PRIVATE_SET_BY_OWNER, PUBLIC_SET_BY_OWNER, and PRIVATE_DEFAULT. The 'set
        by owner' values take precedence over the 'auto' and 'default' values.
        
      With the auto setting:
      
        Forums and containers will appear or not in any browsable listing per the standard
        automatic rules unless overridden by the group owner or an admin. As mentioned above,
        the 'set by owner' values take precedence over the 'auto' and 'default' values when
        determining publicity or browsability.
        
   -MAKE ALL FORUMS PUBLIC
      Checking this does not mean you can't check the options above. However, the effects of
      any settings made under the above settings will not be apparent unless this feature
      is later turned off. This is either an easy way to ensure that all forums are always
      browsable by the public, or may be used to temporarily open the site for something like
      an 'open house'. Turning it off would keep in-tact any settings made before its use.
      
   -MANAGE PUBLICITY OF OLD GROUPS
      Similar to the other retroactive control above, this one manages publicity settings in
      the database for the case where you are upgrading from a version of og_forum without
      these features. As noted on the admin page, it should only be used once.
      
   -SWITCH TO AUTOMATIC PUBLICITY
      Although this may sound like simply turning off the 'Make all forums public' check box
      and ensuring that the 'Automatic forum publicity' checkbox is set, that is NOT what
      this feature does.
      
      Should you use the 'Allow public choice' feature, but later decide that as site admin
      you would like total control of the forums' publicity, you may push this button and
      change all entries in the database to reflect a state as though they had always been
      managed by the 'Automatic forum publicity' feature.
      
      In other words, PUBLIC_SET_BY_OWNER will be changed to PUBLIC_AUTO and PRIVATE_SET_BY_
      OWNER will be changed to PRIVATE_DEFAULT in all database entries. Make sure that you
      uncheck the 'Allow public choice' checkbox, or else group owners will continue to be
      able to make their own settings.
    
  LIMIT NUMBER OF FORUMS PER GROUP
    Here you can set a three digit number (0 - 999) to limit the number of forums that may
    be created by group owners. This limit does not apply to user 1, nor to those with the
    'administer forums' permission.
    
--USAGE--
  I couldn't think of anything not already covered by the FEATURES section. If anyone has a
  special use-case or combo of settings they think need special mention here, let me know.

--THEMING--
  NOTE: This module overrides the theme functions from Drupal core's
    forum module.
    
  There are three theme functions that are overridden. It would be best for you to copy the
  functions from this module to your theme files, rather than use the originals from the
  forum module as starting points.
  
--CREDITS--
  Ryan Constantine (Drupal ID rconstantine) & Paul Booker (Drupal ID paulbooker)  are the current maintainers.
  
  Darren Oh is a previous maintainer.

  Historical thanks to:
  Evan Leeson of Catalyst Creative for sponsorship of 4.7 port and
  improvements.
  Gavin Mogan for http://drupal.org/node/63379 which was a huge help in
  porting the module.