vBulletin Manual - XML-based Bitfield Definitions

Prior to vBulletin 3.5, the bitfields used for systems such as usergroup forum permissions (database: usergroup.forumpermissions) and user options (database: user.options) were defined in includes/init.php. This meant that in order to define additional bitfields, a core file in vBulletin needed to be modified. Needless to say, this was not an ideal system, as the modifications would need to be re-applied after every vBulletin upgrade.

With 3.5, this problem has been resolved using XML files tied into the product system.

Every product can add a file called bitfield_[product].xml to the includes/xml directory. When bitfields are rebuilt, these files will be read by the system and will appear in the bitfield datastore cache.

An example bitfield XML file might look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<bitfields product="myproduct">
    <bitfielddefs>
        <group name="ugp">
            <group name="myproductpermissions">
                <bitfield name="canfoo" group="myproduct_permissions" phrase="can_foo">1</bitfield>
                <bitfield name="canbar" group="myproduct_permissions" phrase="can_bar">2</bitfield>
            </group>
        </group>
    </bitfielddefs>
</bitfields>

In this example XML file, we define two bits for a new usergroup.myproductpermissions bitfield. After completing the following steps, vBulletin will be able to reference these two permission bitfields using $vbulletin->bf_ugp_myproductpermissions['canfoo'] and $vbulletin->bf_ugp_myproductpermissions['canbar'].

Within the <group name="ugp"> (usergroup permissions) node are definitions for groups of bitfield permissions. The <group name="myproductpermissions"> node defines a bitfield called myproductpermissions, which corresponds to an integer field in the usergroup table called myproductpermissions.

Inside this node are individual <bitfield> nodes, each of which defines a bit within the myproductpermissions bitfield. Each of these nodes has three important attributes:

name

The name attribute defines the name of the bit for easy reference within vBulletin code.

For example, if your <group> node's name is myproductpermissions, and your bitfield's name is canfoo, you will be able to access the value of this bit using $vbulletin->bf_ugp_myproductpermissions['canfoo'].

group

The group attribute is important only for integration into the usergroup editor. You can either specify the name of an existing group (for reference, see includes/xml/bitfield_vbulletin.xml), in which case the yes/no radio buttons for this bit will appear within that group, or else you can define a new group, in which case the name of the group should correspond to the phrase name for the group you are creating.

In order to be able to use and edit these newly-defined permissions, we must first prepare the system.

1	The first thing to do is to define the product using the product manager, if you have not done so already.
2	We must now alter the usergroup table in the database to include this new field. The query to support this particular field would be as follows: ALTER TABLE usergroup ADD myproductpermissions INT UNSIGNED NOT NULL DEFAULT 0;
3	Now that we have a place in the database to store the permissions it is necessary to add all the phrases referenced by the bitfields XML. In our example, these phrases are called myproduct_permissions, can_foo and can_bar. These phrases need to be added to the Permissions phrase group, and should belong to the myproduct product.
4	With the phrases and the database field in place, we can now perform the final step, which is to rebuild the vBulletin bitfield cache from the XML files. This can only be done in debug mode, and appears as a link in the vBulletin Options navigation group.
5	The newly-defined bitfield permissions will now appear within the usergroup editor and can be edited in the same way as the standard, predefined permissions for each usergroup.