modules/og_forum/README.txt

/**
 * $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)
  UNINSTALL
  THEMING
  CREDITS
  
--REQUIREMENTS--
  This module requires both the OG module and the Forum module from Core to be installed.
  
  For proper function of the module, you will unfortunately have to patch OG. Here's why:
  http://drupal.org/node/177626
  
  Due to the changing nature of OG, I didn't want to provide a patch with this module as it
  will quickly be outdated. Also, the change can be applied to many versions of OG without
  difficulty. The change is small, and is as follows...
  
  Add this code:
  
  if ($required && $form_id == 'forum_node_form' && module_exists('og_forum')) {
    $simple = TRUE;
  }
  
  to the function called "og_form_add_og_audience". I won't repeat the entire function here,
  but the surrounding code as found in the above-mentioned issue is:
  
  // determine value of audience multi-select
  if (count($options) == 1 && $required) {
    $gids = array_keys($options);
    $gid = $gids[0];
    $groups = array($gid);
    // also show read only mode if user has 1 option and we are in required mode
    $simple = TRUE;
  }
  elseif ($gids) {
   // populate field from the querystring if sent
   $groups = $gids;
   if (!user_access('administer nodes')) {
     // filter out any groups where author is not a member. we cannot rely on fapi to do this when in simple mode.
     $groups = array_intersect($gids, array_keys($options));
   }
   /***********OG_FORUM NEEDS THE NEXT IF CLAUSE*********************************/
   if ($required && $form_id == 'forum_node_form' && module_exists('og_forum')) {
     $simple = TRUE;
   }
   /***********END OG_FORUM CHANGES**********************************************/
  }
  elseif ($node->nid || $node->og_groups) {
    $groups = $node->og_groups;
  }
  else {
    $groups = array();
  }

  WHAT THIS DOES:
    This change to OG allows group forum nodes to be properly added to the og_ancestry
    table which ensures that the group context is correct for all forum nodes.
    
--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 priviledges 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, than 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 explaination 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 rest 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 appearant 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.

--UNINSTALL--
  As of version 2.2 (for 5.x), this module has a proper uninstall routine which will remove
  the og_term table from the database and all variables from the variable table. You do this
  through the usual Drupal means.

--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) is the current Maintainer and the fellow who
  got OG forums working with site-wide forums, and made OG forums publicly viewable based
  on Admin and Group Owner settings.
  
  Darren Oh is the previous maintainer and current co-maintainer.
  
  Original author: Károly Négyesi

  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.
1	/**
2	* $Id:$
3	* @package OG_Forum
4	* @category NeighborForge
5	*/
6	This module extends the forum module to allow for Organic Groups to have their own forums.
7	When viewing groups, only forum discussions for that group are displayed. This module does
8	not hinder the creation of site-wide forums in any way. You can have both OG forums and
9	site-wide forums. There are a multitude of settings for customizing how these forums work
10	which are detailed below.
11
12	--CONTENTS--
13	REQUIREMENTS
14	INSTALL
15	SETUP
16	FEATURES
17	USAGE (Example)
18	UNINSTALL
19	THEMING
20	CREDITS
21
22	--REQUIREMENTS--
23	This module requires both the OG module and the Forum module from Core to be installed.
24
25	For proper function of the module, you will unfortunately have to patch OG. Here's why:
26	http://drupal.org/node/177626
27
28	Due to the changing nature of OG, I didn't want to provide a patch with this module as it
29	will quickly be outdated. Also, the change can be applied to many versions of OG without
30	difficulty. The change is small, and is as follows...
31
32	Add this code:
33
34	if ($required && $form_id == 'forum_node_form' && module_exists('og_forum')) {
35	$simple = TRUE;
36	}
37
38	to the function called "og_form_add_og_audience". I won't repeat the entire function here,
39	but the surrounding code as found in the above-mentioned issue is:
40
41	// determine value of audience multi-select
42	if (count($options) == 1 && $required) {
43	$gids = array_keys($options);
44	$gid = $gids[0];
45	$groups = array($gid);
46	// also show read only mode if user has 1 option and we are in required mode
47	$simple = TRUE;
48	}
49	elseif ($gids) {
50	// populate field from the querystring if sent
51	$groups = $gids;
52	if (!user_access('administer nodes')) {
53	// filter out any groups where author is not a member. we cannot rely on fapi to do this when in simple mode.
54	$groups = array_intersect($gids, array_keys($options));
55	}
56	/*********OG_FORUM NEEDS THE NEXT IF CLAUSE*******************************/
57	if ($required && $form_id == 'forum_node_form' && module_exists('og_forum')) {
58	$simple = TRUE;
59	}
60	/*********END OG_FORUM CHANGES********************************************/
61	}
62	elseif ($node->nid \|\| $node->og_groups) {
63	$groups = $node->og_groups;
64	}
65	else {
66	$groups = array();
67	}
68
69	WHAT THIS DOES:
70	This change to OG allows group forum nodes to be properly added to the og_ancestry
71	table which ensures that the group context is correct for all forum nodes.
72
73	--INSTALL--
74	Before you post an issue to the queue with installation problems, be sure you did all
75	of these things in this order:
76
77	FOR A NEW SITE/ONE WITHOUT OG ALREADY INSTALLED
78	1) Install the forum module through the regular Drupal means.
79
80	2) Trigger the forum vocabulary creation routine by visiting admin/forums - this is
81	the part most often overlooked.
82
83	3) Install OG through the regular Drupal means.
84
85	4) Install this module, again through the regular Drupal means.
86
87	FOR A SITE WITH OG ALREADY INSTALLED
88	1) Install the forum module through the regular Drupal means.
89
90	2) Trigger the forum vocabulary creation routine by visiting admin/forums - this is
91	the part most often overlooked.
92
93	3) Install this module, again through the regular Drupal means.
94
95	4) Go to admin/og/og_forum and click on "Update old groups" to have forum containers
96	and default forums created for existing groups. See the FEATURES section for
97	options.
98
99	--SETUP--
100	There are two permissions that you can assign to roles: 'make forums public' and
101	'admin own group forums'. The former is to allow non-group-owners the ability to set
102	the publicity of forums in groups. Usually, you will want to reserve this for admins.
103
104	The latter is to allow group owners all priviledges for administering forums of their
105	groups.
106
107	--FEATURES--
108	At admin/og/og_forum there are a bunch of options divided into five groups, three of
109	which are fieldsets. The groupings are:
110
111	-Retroactively update old groups
112	-Default forum name
113	-Group forum container
114	-Forum publicity administration
115	-Limit number of forums per group
116
117	RETROACTIVELY UPDATE OLD GROUPS
118	This is a single button which adds containers and forums to each existing OG and is
119	to be used if you install og_forum into a site where groups already exist. You may
120	wish to change some settings below before pushing this button.
121
122	DEFAULT FORUM NAME
123	When a new group is created, or during the retroactive forum creation function, each
124	group is given a forum container with the term name of the group's name as well as one
125	default forum. Normally, the default forum is called "General discussion". You may
126	change that name here.
127
128	CAVEAT - Having the container name the same as the group name makes it easy for people
129	to find the group's forum in a site-wide listing of forums like at the 'forum' URL.
130	This container's name will change as the group's name is changed.
131
132	GROUP FORUM CONTAINER
133	Rather than have all groups' containers and forums show up at the site-wide level, you
134	may designate another (pre-existing) container for all group containers to be placed in.
135	This alternate container may be any number of levels deep in the forum structure. To
136	use this feature, check the box and select the container.
137
138	FORUM PUBLICITY ADMINISTRATION
139	This section has several controls which work together as follows:
140
141	-AUTOMATIC FORUM PUBLICITY
142	This turns on/off the automatic publicity of group forums. If a group forum has at
143	least one post which is public, than entries will be made in the database to indicate
144	that the forum and its container are also publicly browsable. If a group forum does
145	not have any public posts, then that forum will not be publicly browsable except as
146	noted below in conjunction with other settings.
147
148	NOTE: The automatic setting uses two values for storing the forum and containers'
149	states - PRIVATE_DEFAULT and PUBLIC_AUTO.
150
151	-ALLOW PUBLIC CHOICE
152	This allows group owners to decide which of their forums are public or private, but
153	can also work with the auto setting above. First an explaination without the auto
154	setting:
155
156	In each forum, the group owner (or admins) will see a link in the context menu to
157	'Administer group forums' which presents a table structure whereby they may edit
158	forums' names or delete them, add forums to the container, make them public,
159	make them private, or rest them. The publicity settings enter these values into the
160	database - PRIVATE_SET_BY_OWNER, PUBLIC_SET_BY_OWNER, and PRIVATE_DEFAULT. The 'set
161	by owner' values take precedence over the 'auto' and 'default' values.
162
163	With the auto setting:
164
165	Forums and containers will appear or not in any browsable listing per the standard
166	automatic rules unless overridden by the group owner or an admin. As mentioned above,
167	the 'set by owner' values take precedence over the 'auto' and 'default' values when
168	determining publicity or browsability.
169
170	-MAKE ALL FORUMS PUBLIC
171	Checking this does not mean you can't check the options above. However, the effects of
172	any settings made under the above settings will not be appearant unless this feature
173	is later turned off. This is either an easy way to ensure that all forums are always
174	browsable by the public, or may be used to temporarily open the site for something like
175	an 'open house'. Turning it off would keep in-tact any settings made before its use.
176
177	-MANAGE PUBLICITY OF OLD GROUPS
178	Similar to the other retroactive control above, this one manages publicity settings in
179	the database for the case where you are upgrading from a version of og_forum without
180	these features. As noted on the admin page, it should only be used once.
181
182	-SWITCH TO AUTOMATIC PUBLICITY
183	Although this may sound like simply turning off the 'Make all forums public' check box
184	and ensuring that the 'Automatic forum publicity' checkbox is set, that is NOT what
185	this feature does.
186
187	Should you use the 'Allow public choice' feature, but later decide that as site admin
188	you would like total control of the forums' publicity, you may push this button and
189	change all entries in the database to reflect a state as though they had always been
190	managed by the 'Automatic forum publicity' feature.
191
192	In other words, PUBLIC_SET_BY_OWNER will be changed to PUBLIC_AUTO and PRIVATE_SET_BY_
193	OWNER will be changed to PRIVATE_DEFAULT in all database entries. Make sure that you
194	uncheck the 'Allow public choice' checkbox, or else group owners will continue to be
195	able to make their own settings.
196
197	LIMIT NUMBER OF FORUMS PER GROUP
198	Here you can set a three digit number (0 - 999) to limit the number of forums that may
199	be created by group owners. This limit does not apply to user 1, nor to those with the
200	'administer forums' permission.
201
202	--USAGE--
203	I couldn't think of anything not already covered by the FEATURES section. If anyone has a
204	special use-case or combo of settings they think need special mention here, let me know.
205
206	--UNINSTALL--
207	As of version 2.2 (for 5.x), this module has a proper uninstall routine which will remove
208	the og_term table from the database and all variables from the variable table. You do this
209	through the usual Drupal means.
210
211	--THEMING--
212	NOTE: This module overrides the theme functions from Drupal core's
213	forum module.
214
215	There are three theme functions that are overridden. It would be best for you to copy the
216	functions from this module to your theme files, rather than use the originals from the
217	forum module as starting points.
218
219	--CREDITS--
220	Ryan Constantine (Drupal ID rconstantine) is the current Maintainer and the fellow who
221	got OG forums working with site-wide forums, and made OG forums publicly viewable based
222	on Admin and Group Owner settings.
223
224	Darren Oh is the previous maintainer and current co-maintainer.
225
226	Original author: Károly Négyesi
227
228	Historical thanks to:
229	Evan Leeson of Catalyst Creative for sponsorship of 4.7 port and
230	improvements.
231	Gavin Mogan for http://drupal.org/node/63379 which was a huge help in
232	porting the module.