===========================================
CUSTOM ADDONS: vbBux / vbPlaza
===========================================

Here you will find a list of available functions for use with vbBux / vbPlaza
to develop your own addons and quirks for the system.


===========================================
HOOKS: Some useful information about hooks!
===========================================

----------------------------
1) vbplaza_manipulate_points
----------------------------
   -- Used to manipulate the points given for all actions.

   ========================
   == Variable Explanation:
   ========================
   $type - This variable is true if points are given, false if taken.
   $points - This is the variable you need to manipulate.
   $hookname - This tells what hook is manipulating the $points.
   $action - This variable is 'default' or an action if a hook
             requires the use of more than 1 point manipulation.

--------------------------------
2) vbplaza_expire_item_not_found
--------------------------------
   -- Used to force expire a non-custom item.

   ========================
   == Variable Explanation:
   ========================
   $handled_expire - This variable is set to either true or false,
                     depending on if you have handled it or not.


=======================================================================================
FUNCTIONS: Here you will find out some useful functions if you need to make any addons.
=======================================================================================

==========================
A) The file functions.php:
==========================

[code]
// include the vbBux / vbPlaza global functions
require_once(DIR . '/vbplaza/includes/functions.php');
[/code]

--------------------------------------------------------------------------------------------------------
1) vbBux_vbPlaza_DataManager_Init($classtype, &$registry, $errtype = ERRTYPE_STANDARD, $forcefile = '');
--------------------------------------------------------------------------------------------------------
   -- This function is used to make use of the Data Manager classes from vbBux / vbPlaza.

   ========================
   == Variable Explanation:
   ========================

   $classtype:  String  - Name of the class to initialize.
   $registry:   Object  - $vbulletin object for the registry.
   $errtype:    Integer - Use this to set how error messages should show.
   $forcefile:  String  - If the class has a non-standard file name, specify it here.

   =================
   == Example Usage:
   =================

   [code]
   // assuming $giftuser is already gotten, set it to hidden
   $giftdata =& vbBux_vbPlaza_DataManager_Init('vbPlaza_Gift_User', $vbulletin, ERRTYPE_STANDARD);
   $giftdata->set_existing($giftuser);
   $giftdata->set('visible', 0);
   $giftdata->save();
   [/code]

---------------------------------------------------------------------------
2) vbplaza_calculate_post_points($type, $post, $forumid, $usergroupid = 0);
---------------------------------------------------------------------------
   -- This function is sed to calculate how many points a post is worth based on it's
      message size, forum posted in, etc...

   ========================
   == Variable Explanation:
   ========================
   $type:         String  - This variable is either 'thread' or 'post'.
   $post:         Array   - This should be an array with the post data, i.e. message.
   $forumid:      Integer - This is obviously the forum id where the post is being posted.
   $usergroupid:  Integer - Use this if you want to calculate points based off a different usergroup.

   =================
   == Example Usage:
   =================

   [code]
   // calculate the points for a new thread in forum 1
   $newpoints = vbplaza_calculate_post_points('thread', $postinfo, 1);
   [/code]

-------------------------------------------------
3) $outputdata = vbplaza_unserialize($inputdata);
-------------------------------------------------
   -- This function will check if a string is serialized before it calls the unserialize function.

   ========================
   == Variable Explanation:
   ========================
   $inputdata:  String - This is the data that may or may not be unserialized.

   ================
   == Return Value:
   ================
   $outputdata:  String - This will return the proper array of the data unserialized.

   =================
   == Example Usage:
   =================

   [code]
   // unserialize the currently logged in user's history
   $user_history = vbplaza_unserialize($vbulletin->userinfo['vbplaza_history']);
   [/code]

------------------------------------------------------------------------------------------------------------------
4) vbplaza_build_datastore($tablename, $primarykey, $cachename, $orderby = 'displayorder', $exclusions = array());
------------------------------------------------------------------------------------------------------------------
   -- This function is used to build the datastore information used by vbBux / vbPlaza.
      There is also a special version to build the vbplaza_item cache, vbplaza_build_item_datastore();

   ========================
   == Variable Explanation:
   ========================
   $tablename:   String - This is the name of the database table.
   $primarykey:  String - This is the name of the primary key of the table.
   $cachename:   String - This is the name of the datastore cache.
   $orderby:     String - Use this to order the cache by a field other than the cache name.
   $exclusions:  String - Fill this array with fields that you do not want to be cached.

   =================
   == Example Usage:
   =================

   [code]
   // build the datastore for the vbplaza_category table
   vbplaza_build_datastore('vbplaza_category', 'categoryid', 'vbpcatcache');
   [/code]

-----------------------------------------------------------------------------------------
5) vbplaza_rebuild_gift_postbit($userid, $updatehistory = false, $itemhistory = array());
-----------------------------------------------------------------------------------------
   -- Use this to rebuild the gifts the user has displayed in their postbit.

   ========================
   == Variable Explanation:
   ========================
   $userid:         Integer - The User ID that you want to rebuild the gift postbits for.
   $updatehistory:  Bool    - True or False, should it update the user's history.
   $itemhistory:    Array   - Fill this array with the fields to update the user's history.

   =================
   == Example Usage:
   =================

   [code]
   // rebuild the gift postbit info for userid 1
   vbplaza_rebuild_gift_postbit(1);
   [/code]

-------------------------------------------------------------------------------------------
6) vbplaza_rebuild_ribbon_postbit($userid, $updatehistory = false, $itemhistory = array());
-------------------------------------------------------------------------------------------
   -- Use this to rebuild the ribbons the user has displayed in their postbit.

   ========================
   == Variable Explanation:
   ========================
   $userid:         Integer - The User ID that you want to rebuild the ribbon postbits for.
   $updatehistory:  Bool    - True or False, should it update the user's history.
   $itemhistory:    Array   - Fill this array with the fields to update the user's history.

   =================
   == Example Usage:
   =================

   [code]
   // rebuild the ribbon postbit info for userid 1
   vbplaza_rebuild_ribbon_postbit(1);
   [/code]

--------------------------------------------------------
7) $userhistory = vbplaza_add_history($userinfo, $item);
--------------------------------------------------------
   -- Call this function to add an item to a user's history.

   ========================
   == Variable Explanation:
   ========================
   $userinfo:  Array - This is the array of the User you want to update.
   $item:      Array - This is the array of the purchase you want to update.

   ================
   == Return Value:
   ================
   $userhistory - Serialized version of the user's new history.

   =================
   == Example Usage:
   =================
   [code]
   // add an item to the logged in user's history
   $userhistory = vbplaza_add_history($vbulletin->userinfo, $item);
   [/code]

-----------------------------------------------------------
8) $userhistory = vbplaza_remove_history($userinfo, $item);
-----------------------------------------------------------
   -- Call this function to remove an item from a user's history.
   -- NOTE: It remove's $item['itemid'] from the user's history.

   ========================
   == Variable Explanation:
   ========================
   $userinfo:  Array - This is the array of the User you want to update.
   $item:      Array - This is the array of the purchase you want to update.

   ================
   == Return Value:
   ================
   $userhistory - Serialized version of the user's new history.

   =================
   == Example Usage:
   =================
   [code]
   // remove an item to the logged in user's history
   $userhistory = vbplaza_remove_history($vbulletin->userinfo, $item);
   [/code]

-----------------------------------------------------------------
9) vbplaza_user_purchase_update(&$userinfo, $item, $extrafields);
-----------------------------------------------------------------
   -- Use this to send off the query to update the user's points/history.

   ========================
   == Variable Explanation:
   ========================
   $userinfo:     Array - This is the array of the User you want to update.
   $item:         Array - This is the array of the purchase you want to update.
   $extrafields:  Array - Fill this array with any additional fields you want to update.

   ========================
   == Variable Explanation:
   ========================
   $extrafields - String value for queries to add values to update in the
                  user table. (i.e. set it to "vbplaza_variable = '0'")

   =================
   == Example Usage:
   =================

   [code]
   // update the logged in user's history (set reputation to 1 via $extrafields)
   vbplaza_user_purchase_update($vbulletin->userinfo, $item, array('reputation' => 1));
   [/code]

--------------------------------------------------------------------------------------------------
10) vbplaza_quick_add_points($userinfo, $givepoints, $can_receive = true, $extrafields = array());
--------------------------------------------------------------------------------------------------
    -- Used to add points to a user quickly.

    ========================
    == Variable Explanation:
    ========================
    $userinfo:     Array   - This is the array of the User you want to update.
    $givepoints:   Integer - This is the amount of points you want to give.
    $can_receive:  Bool    - True or False, check if user is able to receive points first.
    $extrafields:  Array   - Fill this array with any additional fields you want to update.

    =================
    == Example Usage:
    =================

    [code]
    // add 1000 points to the logged in user
    vbplaza_quick_add_points($vbulletin->userinfo, 1000);
    [/code]

-------------------------------------------------------------------------------------------------------
11) vbplaza_quick_subtract_points($userinfo, $takepoints, $can_receive = true, $extrafields = array());
-------------------------------------------------------------------------------------------------------
    -- Used to subtract points from a user quickly.

    ========================
    == Variable Explanation:
    ========================
    $userinfo:     Array   - This is the array of the User you want to update.
    $takepoints:   Integer - This is the amount of points you want to take.
    $can_receive:  Bool    - True or False, check if user is able to receive points first.
    $extrafields:  Array   - Fill this array with any additional fields you want to update.

    =================
    == Example Usage:
    =================

    [code]
    // subtract 1000 points to the logged in user
    vbplaza_quick_subtract_points($vbulletin->userinfo, 1000);
    [/code]

--------------------------------------------------------------------------------------------------------
12) vbplaza_quick_add_bank_points(&$userinfo, $givepoints, $can_receive = true, $extrafields = array());
--------------------------------------------------------------------------------------------------------
    -- Used to add points to a user's bank quickly.

    ========================
    == Variable Explanation:
    ========================
    $userinfo:     Array   - This is the array of the User you want to update.
    $takepoints:   Integer - This is the amount of points you want to take.
    $can_receive:  Bool    - True or False, check if user is able to receive points first.
    $extrafields:  Array   - Fill this array with any additional fields you want to update.

    =================
    == Example Usage:
    =================

    [code]
    // add 1000 points to the logged in user's bank
    vbplaza_quick_add_bank_points($vbulletin->userinfo, 1000);
    [/code]

----------------------------------------------------------
13) vbplaza_send_pm($fromuser, $touser, $title, $message);
----------------------------------------------------------
    -- Used to send a PM to a user.

    ========================
    == Variable Explanation:
    ========================
    $fromuser: - Array or Integer - User ID or $userinfo array of the from user.
    $touser:   - Array or Integer - User ID or $userinfo array of the to user.

    =================
    == Example Usage:
    =================

    [code]
    // send a hello PM
    vbplaza_send_pm($vbulletin->userinfo, $touser, "Hello", "Hey, just saying whats up!");
    [/code]

================================
B) The file functions_items.php:
================================

[code]
// include the vbBux / vbPlaza items functions
require_once(DIR . '/vbplaza/includes/functions_items.php');
[/code]

----------------------------------------------
1) vbplaza_verify_all_fields(&$item, $verify);
----------------------------------------------
   -- Used to verify that the item mysql fields are valid.

   ========================
   == Variable Explanation:
   ========================
   $item:  - Array - Array of the item that is being verified.
   $verify - Bit flags used to determine which parts to verify.
             a) -1 is used for ALL fields
             b) 1 is used for 'tablename'
             c) 2 is used for 'wherename'
             d) 4 is used for 'wherevalue'
             e) 8 is used for 'setname'
             f) 16 is used for 'setvalue'

   =================
   == Example Usage:
   =================
   [code]
   // verify all fields for an item
   vbplaza_verify_all_fields($item, -1);
   [/code]

--------------------------------
2) vbplaza_validate_cost($item);
--------------------------------
   -- Use this function to validate the user has enough points to buy your item.

   ========================
   == Variable Explanation:
   ========================
   $item:  - Array - Array of the item that is being verified.

   =================
   == Example Usage:
   =================
   [code]
   // validate the cost for an item
   vbplaza_validate_cost($item);
   [/code]

----------------------------------------------------------------
3) vbplaza_calculate_total_cost($item, $userdiscount, $taxable);
----------------------------------------------------------------
   -- Use this to calculate and verify the $item['cost'], $item['totalcost']
      and $item['tax']. It also takes into account any user dicounts and
      if you want the item to be taxable or not.

   ========================
   == Variable Explanation:
   ========================
   $item:          - Array - Array of the item that is being verified.
   $userdiscount:  - Bool  - True or False to use user discounts.
   $taxable:       - Bool  - True or False to use tax rates.

   =================
   == Example Usage:
   =================
   [code]
   // calculate the total cost of an item
   vbplaza_calculate_total_cost($item, true, true);
   [/code]

------------------------------------
4) vbplaza_build_inputfields($item);
------------------------------------
   -- If your item has any extra input fields set in the Admin CP, then
      you will need to call this function to display your input fields.

   ========================
   == Variable Explanation:
   ========================
   $item:  - Array - Array of the item that is being verified.

   =================
   == Example Usage:
   =================
   [code]
   // build any input fields needed for the item purchase
   vbplaza_build_inputfields($item);
   [/code]

---------------------------------------
5) vbplaza_item_check_for_flood($item);
---------------------------------------
   -- Pretty obvious, this function just verifies the flood check time
      in between purchasing the same option over and over.

   ========================
   == Variable Explanation:
   ========================
   $item:  - Array - Array of the item that is being verified.

   =================
   == Variables Set:
   =================
   $item['flooding'] - BOOL item, either true or false
   -- IF $item['flooding'] is set to true:
      $item['lastusage'], $item['timenow'], $item['nextusage'] are dates.

   =================
   == Example Usage:
   =================
   [code]
   // check to see if the item is being flooded
   vbplaza_item_check_for_flood($item);
   [/code]

---------------------------------------
6) vbplaza_update_quantity_sold($item);
---------------------------------------
   -- Call this after updating the user's purchase above to update the
      item's quantity and sold values.

   ========================
   == Variable Explanation:
   ========================
   $item:  - Array - Array of the item that is being verified.

   =================
   == Example Usage:
   =================
   [code]
   // update the quantity sold
   vbplaza_update_quantity_sold($item);
   [/code]
