Custom Datamanagers

[Guest190829]

Anyone have experience with creating their own Datamanagers for large-scale projects?

[amykhar]

I wrote one once and decided not to use it. It wasn't difficult.

[tgreer]

What would the pros and cons, advantages and disadvantages be?

[amykhar]

I liked that it gave me the option to let others hook into the mod I was writing and to use external scripts to work with it. It gave it a simple interface for other devs. It also provided good data verification mechanisms to validate incoming info.

But, I didn't like the extra overhead and went with a more simplistic approach for my own use when I decided that I did not want to release such a large modification.

[Alan @ CIT]

Creating custom datamangers is fairly easy once you've done one :D

To start with, create your new PHP file to hold your DM code and save it as
includes/class_dm_example.php

Now, the first thing we need to do is check that the vB_Datamanger class exists - without that, we can't do much of anything.

At the top of your new PHP file, put:

if (!class_exists('vB_DataManager'))
{
exit;
}

This will end the script if the vB_Datamanger class doesn't exist.

Now we need to extend the vB_DataManager class to make our own Datamanager.

On the next line down in your PHP file, put:

class vB_DataManager_Example extends vB_DataManager
{

This tells PHP that we want to create a Class called "vB_DataManager_Example", and that we want to base it on the vB_DataManager class. This means that our new DM class will inherit all of the vB_DataManagers variables and methods (functions) so we don't have to make our own save() method for example :)

Now we need to give our new Datamanager some fields to update. For example, the User DM would have fields such as "userid", "username", "email", etc. These fields will usually be the same as the columns in your database table.

These fields all go in an array called $validfields. The $validfields array is in the following format:


'fieldname' => array(type, required?, verify data?, function name to verify data)

The verificatoin options (the last 2) are optional.

With that in mind, lets start adding to our own $validfields array. Our example datamanager will have 4 fields:

'exampleid' - this is an auto increment field from the database which is incremented automaticly.
'userid' - a vBulletin user id
'username' - a vBulletin username
'exampletext' - some random text

First things first, lets create our $validfields array variable.

var $validfields = array(

Now we can add our first field:

'exampleid' => array(TYPE_UINT, REQ_INCR, VF_METHOD, 'verify_nonzero'),

Lets go through this line bit by bit.

First we have the field name - in this case 'exampleid'.
Next we have the type - in this case we're saying it will be an Unsigned Int (ie, a number). A list of valid types can be found at the bottom of this post.
Next we specify that it is required, and that it is an auto-increment value with REQ_INCR. Valid options for this field can be found at the bottom of this post.
Next we tell it that we want to verify the data, with VF_METHOD
And finally, we give it the name of a function to verifiy the data with. In this case, we are using the verify_nonzero() function which is a standard function in the vB_DataManager class.

Now we can add our other 3 fields to the $validfields array:


'userid' => array(TYPE_UINT, REQ_YES, VF_METHOD, 'verify_nonzero'),
'username' => array(TYPE_STR, REQ_YES, VF_METHOD),
'exampletext' => array(TYPE_STR, REQ_NO)
);

This has added a further 3 fields to the $validfields, and closed the $validfields array :)

Now, the next step is to tell vBulletin what table to save our data in. Your table should match the $validfields array in terms of layout and column names.

In this case, we'll use a table called "example":

var $table = 'example';

Now we have to give vBulletin a temporary array that it uses to store the data we give it when it's saving to out database table that we specified above. It doesn't really matter what this is called, but for convention, try to stick with the name of your DM class :)

var $example = array();

The final step in our very basic Datamanager is to create our Class Initator method. This is a function that is run automaticly when our Example Datamanager is created using datamanager_init().

function vB_DataManager_Example(&$registry, $errtype = ERRTYPE_STANDARD)
{
parent::vB_DataManager($registry, $errtype);
}

The name of this functoin should be exactly the same as your class name. So in this case, we've called it "vB_DataManager_Example".

You don't need to worry about the rest of the code, and if you understand OOP, you'll know what it means :)

Now, all we've got left to do is add our closing bracket for our class, and we're done:

}

You can now create your new Datamanager as you would any standard Datamanager by using the datamanager_init() function :)

That's the gist of it anyway, take a look at some of the existing Datamanagers for more advanced options such as Bitfields, custom verify methods, etc.

Valid field types:

TYPE_NOCLEAN - Any value - it won't be checked/cleaned
TYPE_INT - An signed integer
TYPE_UINT - An un-signed integer
TYPE_NUM - A number
TYPE_UNUM - An un-signed number
TYPE_UNIXTIME - A unix timestamp (time();)
TYPE_STR - A string
TYPE_NOTRIM - A string that won't have trim() run on it
TYPE_NOHTML - A string that will have the HTML made-safe
TYPE_FILE - A file upload (ie, $_FILES)
TYPE_BOOL - A bool (true or false)You can also pass Arrays of these items. For example to pass an array of INT's, use TYPE_ARRAY_INT. To pass an array of Strings, use TYPE_ARRAY_STR

Valid Requirement Options:

(The following is taken directly from vBulletin's DataManager documentation)

REQ_YES - the field is required

REQ_NO - the field is not required

REQ_AUTO - the field can be automatically generated. The does not have any effect on code execution at this time. This is appropriate for things like post times that can be reasonably guessed before inserting the new data. (You will still need to write code to generate the appropriate value!)

REQ_INCR - this field is an AUTO_INCREMENT field in the database, and thus will be automatically generated upon insertion.

Hopefully all that ^^^ makes some sort of sense, and good luck making your new DataManager Danny :)

(class_dm_example.php attached)

Thanks,
Alan.

[-=Sniper=-]

wow, thanks Alan

[tgreer]

Alan, would you be willing to make this an article? I've been exploring DataManagers on my own, so was pleased to see a public discussion on it here, and your excellent post did shed some light. Thanks.

[Alan @ CIT]

I'll try and clean it up a bit and post it as an Article. Not sure when though :)

Thanks,
Alan.

[Guest190829]

This is excellant Alan - Great job! :)

[kjhkjh]

Can this help me?? Or anyone here?

I have added forums to the table 'forum'
I have updated the parent ID's, descriptions etc of each of the forums that I've added.
I believe I now have to updates the datastore which is basically a series of records in an serialized form that has information about the forums and its permissions. (this was the advice vb.com gave but I can find no documentation about how to do this - especially how to do it safely)

They also said it would be in your best interested to look at http://member.vbulletin.com/api. In particular the Datamanager class for Forums. but the link isn't working for me.

Any help here is much appreciated - I'm trying to save myself over 100 hours of adding and updating forums - please help :)

[slak74]

Hi,

We seem to be facing issues with usergroups and permissions as the datamanager in VBulletin does not seem to be supporting the same. We would request you to kindly let us know how we could get around and work with usergroup and permissions without the use of a datamanager.

Regards,
Lakshmi

[Marco van Herwaarden]

I am not sure what your problem is, but i suggest you start a new thread describing your problem.