vBulletin LTS

Custom Usergroup/Forum Permissions
Mod Version: 1.00, by joefitz

Description:

This product is a framework which simplifies the creation and management of custom usergroup permissions and their associated custom forum permissions. There are tutorials on how to perform these types of modifications to the vBulletin system; however, this is a common part of many vBulletin add-on products and I didn't want to have to write separate code to do this same thing for all of my forthcoming vBulletin products. Since this product allows the arbitrary addition of custom usergroup permissions, I thought it may have value to others as well.

Of significant note, this product does not use any of the vBulletin standard fields, specifically the forumpermissions field of the forumpermission table. Many of the tutorials I've seen online either only discuss adding usergroup permissions (and do not delve into how to extend usergroup permissions to forum usergroup permissions) or they suggest using the forumpermissions field of the forumpermission table (unused bits...). The former situation simply lacks the depth that many of us need; that is, we want full 'forum usergroup' permissions, not simply 'usergroup' permissions. The latter issue is simply a very poor design choice: who knows when the vBulletin system will begin using the as yet unused bitfields in the forumpermission.forumpermissions field or when two add-on products try to contend for the same bits in that field?

A better solution is to standardize a process whereby each of your products adds a new field to the forumpermission table which will store your product-specific custom usergroup data. This ensures your product won't run into problems if the user upgrades vB or installs other add-on products.

CustomUGP addresses these issues. It eliminates most of the real downside with taking this approach, namely that you would have to implement code to handle the custom forum permissions. The disadvantage with the solution as it currently stands is that you have to modify one of the existing vbulletin product files, specifically ./includes/adminfunctions.php. The edits are very minor; simply adding two new hooks (both of which have been requested to be added to a future release of vBulletin).

Phew. I guess that about covers it.

Requirements For installation:

* Admin access to vBulletin 3.5.3 (untested on any other version)
* FTP access to add new files to the vBulletin directory structure

Requirements For Usage:

* Basic familiarity with adding fields to your vB database (specifically, you will need to add a field to the forumpermission table to store your custom bitfields)
* Basic understanding of how to create a product and the associated xml files, namely: yourproduct.xml and bitfields_yourproduct.xml
* Admin access to vBulletin 3.5.x

Installation:

1. Download the distribution file and unzip it to a temp directory.
2. Copy the adminfunctions_customugp.php file to your ./includes directory
3. Edit your ./includes/adminfunctions.php file as follows:

   1. Find the following section of code in the build_forum_permissions function (should start around line 2798):
      
      Code:

      // query forum permissions
      $fperms = $vbulletin->db->query_read("SELECT * FROM " . TABLE_PREFIX . "forumpermission");
      while ($fperm = $vbulletin->db->fetch_array($fperms))
      {
      	$fpermcache["$fperm[forumid]"]["$fperm[usergroupid]"] = $fperm['forumpermissions'];
      }
      unset($fperm);
      $vbulletin->db->free_result($fperms);
      DEVDEBUG('updateForumCache( ) - Queried Forum Pemissions');

      You need to add one line after the while loop:
      
      Code:

      ($hook = vBulletinHook::fetch_hook('customugp_build_forum_custompermissions')) ? eval($hook) : false;

      The new section of code should look like:
      
      Code:

      // query forum permissions
      $fperms = $vbulletin->db->query_read("SELECT * FROM " . TABLE_PREFIX . "forumpermission");
      while ($fperm = $vbulletin->db->fetch_array($fperms))
      {
      	$fpermcache["$fperm[forumid]"]["$fperm[usergroupid]"] = $fperm['forumpermissions'];
      }
      ($hook = vBulletinHook::fetch_hook('customugp_build_forum_custompermissions')) ? eval($hook) : false;
      unset($fperm);
      $vbulletin->db->free_result($fperms);
      DEVDEBUG('updateForumCache( ) - Queried Forum Pemissions');

   2. Find the following section of code in the cache_forum_permissions function (should start around line 2973):
      
      Code:

      // run through each usergroup
      foreach(array_keys($vbulletin->usergroupcache) AS $usergroupid)
      {
      	// if there is a custom permission for the current usergroup, use it
      	if (isset($fpermcache["$forumid"]["$usergroupid"]))
      	{
      		$perms["$usergroupid"] = $fpermcache["$forumid"]["$usergroupid"];
      	}
      	// populate the current row of the forumcache permissions
      	$forum['permissions']["$usergroupid"] = $perms["$usergroupid"];
      }

      You need to add one line after the while loop:
      
      Code:

      ($hook = vBulletinHook::fetch_hook('customugp_cache_forum_custompermissions')) ? eval($hook) : false;

      The new section of code should look like:
      
      Code:

      // run through each usergroup
      foreach(array_keys($vbulletin->usergroupcache) AS $usergroupid)
      {
      	// if there is a custom permission for the current usergroup, use it
      	if (isset($fpermcache["$forumid"]["$usergroupid"]))
      	{
      		$perms["$usergroupid"] = $fpermcache["$forumid"]["$usergroupid"];
      	}
      	// populate the current row of the forumcache permissions
      	$forum['permissions']["$usergroupid"] = $perms["$usergroupid"];
      	($hook = vBulletinHook::fetch_hook('customugp_cache_forum_custompermissions')) ? eval($hook) : false;
      }

4. Copy the product-customUGP.xml and hooks_customugp.xml files into your ./includes/xml directory.
5. Import the product (product-customUGP.xml) via the vBulletin Product Management tool in the Admin

Usage:

[ADVANCED]

1. Create an appropriate bitfield file to add the options you want to the usergroup (see example in the beginners section below if necessary)
2. Add the database field to both the usergroup and forumpermission table (the field must match the inner "group" tag's name attribute in the bitfield xml file
3. Create the appropriate phrases
4. Rebuild the bitfields via the ACP
5. Go to the Custom UGP Settings option in the vBulletin Options manager; add the field name you just added to the db into the input box
6. You can now reference your custom forum usergroup permissions in php code as follows:
   
   Code:

   $can['private'] = ($vbulletin->forumcache["$forumid"]['cpermissions']["$usergroupid"]['threadprivacy_options'] & $vbulletin->bf_ugp_threadprivacy_options['canprivate']);

Obviously you could do something similar in a template, although I believe the recommended process would be to set these flags in a hook/php code mod and then refer to the variable in a template using a conditional as so:

Note: the above lines of code is taken from the example I used below in the beginners section. Your code should look similar but reference the individual bitfields you specified in your bitfield file (instead of canprivate) as well as the name of the custom forum permission you are checking (threadprivacy_options in this case).

[BEGINNERS]

There are several different ways to create new Usergroup Permissions using this product. The best way is to create a product. If you haven't done so before, read one of the tutorials and download a few products to use as guides. It is EXTREMELY SIMPLE to create a product. If you don't believe me, look at the product-customUGP.xml file. It is TRIVIAL. You can do it. One particular issue to note re: creating a product is that you can manually create a product using the standard vBulletin Admin Control Panel Product Manager and then define the various plug-ins, templates, admin help files, admin settings, phrases... that you need. Once you are satisfied, simply go back to the Product Manager and click export and the system will automatically export your product.xml file for you completely built!

Ok, I've convinced you to create a product for the feature you are implementing...now what? I'd recommend reading the rest of this once before doing anything if you are new to this.

The first step is to decide what Usergroup Permissions you need to create. These should be yes/no options (if they aren't, don't try to use this product). Once you've made that decision, you can get to the real work as follows:

1. Create a bitfield file named bitfield_YOURPRODUCT.xml (all lowercase) and put it in the ./includes/xml directory. A tutorial is available at: http://www.vbulletin.org/forum/showt...4&page=1&pp=15
   
   An example from one of my forthcoming products:
   
   
   Code:

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <bitfields product="threadprivacy">
   	<bitfielddefs>
   		<group name="ugp">
   			<group name="threadprivacy_options">
   				<bitfield name="canreadonly" group="thread_privacy_options"  phrase="threadprivacy_can_read_only" install="">1</bitfield>
   				<bitfield name="canmemod" group="thread_privacy_options"  phrase="threadprivacy_can_me_mod" install="">2</bitfield>
   				<bitfield name="canwemod" group="thread_privacy_options"  phrase="threadprivacy_can_we_mod" install="">4</bitfield>
   				<bitfield name="canprivate" group="thread_privacy_options"  phrase="threadprivacy_can_private" install="">8</bitfield>
   			</group>
   		</group>
   	</bitfielddefs>
   </bitfields>

   Of particular note:
   1. You should use your own product name as the product identifier in the bitfields tag.
      
   2. The outer group tag's "name" attribute should be ugp (usergroup permission); this is a vBulletin value
      
   3. The inner group tag's "name" attribute should be the database field you want to store the data in; you will need to add this field to the usergroup and forumpermission tables.
      
   4. The database field you add should be an unsigned int field with a length at least as large as the number of bitfields you require (at least 4 in the above example)
      
   5. The "group" attribute of the bitfield tag is the phrase name displayed as the title for these options (in other words, you'll need to add a corresponding phrase using the Phrase Manager)
      
   6. Each bitfield:

      
      i) should have a short name, preferably of the form candosomething: you access these values in your code in several ways including by these names -- make them descriptive but short
      ii) should have a phrase as specified in the phrase portion of the bitfield definition
      iii) the value between the open/close bitfield tag is the value of the position of the bitfield in the unsigned int field:
      1) these must be a power of 2 (1,2,4,8,16,32,64,128,256,512,1024,2048...)
      2) the values can appear in any order but must not have conflicts/duplicates
      

   
   
2. Create the database field specified in the bitfield file; remember to create it in both the usergroup and forumpermission tables (make sure these changes end up in your product.xml file)
   
3. Create the phrases associated with the bitfield file you defined; make sure the phrases end up in your product.xml file (see that tutorial if you need more guidance)
   
4. Rebuild the bitfields (done via the admin or preferably as part of your product installation code if you are distributing a product); your custom permissions won't appear until the bitfields are generated!
   
5. Add the name of the db field you added into the list in Custom Usergroup Permision Settings section of the vBulletin Options in the AdminCP (ideally, add this process to your product install code)
   
6. Access these permissions in php files (or hooks) via:
   
   
   Code:

   $can['private'] = ($vbulletin->forumcache["$forumid"]['cpermissions']["$usergroupid"]['threadprivacy_options'] & $vbulletin->bf_ugp_threadprivacy_options['canprivate']);

   Once the variables 'can' variables are set, you refer to them in templates as you would normally. See the example at the end of the 'advanced' section for more details of a real-world example.

Note: the above line of code is specific to the example bitfield I used above. Your code should look similar but reference the individual bitfields you specified in your bitfield file (instead of canprivate) as well as the name of the custom forum permission you are checking (threadprivacy_options in this case).

System Changes:

This product uses five hooks. Two are newly created hooks that have to be manually inserted into the adminfunctions.php file. This was necessary in order to cache the custom forum permissions after they are changed in the admin. Unfortunately I couldn't find a way around a manual file change; however, I have requested that these hooks be added into a future release of vBulletin and I'm hopeful that at some point it will be done (hopefully they'll just modify vBulletin to support this feature and remove the need for this customization entirely). The other three are hooks already in vBulletin and are used to automate the handling of the custom permissions you need (that is, to display and save the information).

There are no database changes required to install this product; however, using the product requires you to alter the database as mentioned above. There product includes one new php file and 1 xml file.

Limitations:

This code was developed to work only with bitfield-type permissions, that is Yes/No situations.

Problems:

• DOES NOT WORK with the Permission Duplication Tools available from the Forum Permissions area of the ACP. There are no hooks or other mechanisms by which I could incorporate these features. Worse, the feature uses a "REPLACE INTO" feature basically means the custom usergroup permissions you've defined will be zeroed out in whatever records you are copying into. Do not use these two duplication features if you want to be safe. If you do use them, make sure you go into the newly copied permissions and update the settings for all the custom usergroup permissions you have defined.

NOTE: The Permissions Quick Editor and the Quick Forum Permission Setup functions still work properly.

Potential Issues/Cautions:

• Please see the Problems section. Short answer: DO NOT USE PERMISSION DUPLICATION TOOLS (first link at the top of the Forum Permissions AdminCP page).
• Requires changing the vBulletin adminfunctions.php file distributed with vBulletin; this means this product is not likely to be safe with upgrades to vBulletin

Future Plans:

1. Enhance the error checking; currently it doesn't do ANY error checking, which is quite bad. For instance, the product should be validating that the CustomUGP Field List you enter in the settings area actually have the correct fields in the appropriate database tables. There are many other checks that should be put in place as well.
2. Add admin help button support
3. Optionally add forum option for each permission (this will optionally allow you to put a hard limit on the capabilities of a specific forum regardless of user permissions defined within that forum)
4. Address the duplication feature problem: this involves a manual code fix unless they update the product in such a way as to provide a hook or two.