Cash Mod API
Your #1 source (unless someone beats me to it
) for Cash Mod API documentation!
So, Cash Mod has a couple new and big things this time around, mainly, the API, to help other programmers who want to use Cash, to interface with the Cash Mod more easily.
We'll split this up into x sections, where x is an unknown number i have yet to determine.
- IN_CASHMOD
- $cash object
- Bitmasks
- Currency Objects
- cash_user objects (forthcoming)
- CM_EVENT (forthcoming)
- more!
- IN_CASHMOD
so, the first thing that's important, is that at the top of the file where you want to use Cash Mod API, is that you include the entry
right below
in all the user-facing files that you wish to access the API from.
this ensures that functions_cash.php will get loaded when your file includes common.php
Without this, you won't have access to the Cash Mod API
- $cash object
the $cash object is in the global scope, similar to the $db and $template object. Similar to those objects, it can be very powerful. What $cash does is hold the data for all the currencies currently in your database.
There are four main functions that it has that you may find useful.
- currency_exists(...);
- currency(...);
- currency_count(...);
- currency_next(...);
- currency_exists($cash_id)
eg: if ( $cash->currency_exists(1) )
returns true if there is a currency with that key defined, false otherwise
- currency($cash_id)
eg: $c_cur = $cash->currency(1)
returns the currency object for the currency associated with that key
- currency_count($mask = false, $forum_id = false)
eg: $num_currencies = $cash->currency_count(CURRENCY_ENABLED)
returns a count of currencies, depending on the bitmasks used. if no bitmasks are used, a count of all currencies are returned. if $forum_id is set, then only currencies that are enabled in the forum specified are counted.
- currency_next($iterator,$mask = false, $forum_id = false)
eg: while ( $c_cur = &$cash->currency_next($cm_i,CURRENCY_ENABLED) )
retrieves the next currency. $mask and $forum_id are identical in usage as currency_count
- Bitmasks
Cash Mod has several bitmasks defined:
- CURRENCY_ENABLED - currency is enabled
- CURRENCY_IMAGE - currency has an image icon
- CURRENCY_VIEWPROFILE - currency is displayed in the profile
- CURRENCY_VIEWTOPIC - currenct is displayed in the topic
- CURRENCY_VIEWMEMBERLIST - currency is displayed in the memberlist
- CURRENCY_DONATE - currency is donateable
- CURRENCY_MODEDIT - moderators can edit this currency
- CURRENCY_EXCHANGEABLE - currency is exchangeable
So, to get a count of all currencies that are enabled, and exchangeable, useCode: Select all
$cash->currency_count(CURRENCY_ENABLED | CURRENCY_EXCHANGEABLE);
- Currency Objects
you may recall the line
or
Code: Select all
while ( $c_cur = &$cash->currency_next($cm_i,CURRENCY_ENABLED) )
$c_cur is my standard way of referring to the 'current' currency.
it has several useful functions.
- id();
- name(...);
- db();
- display(...);
- mask(...);
- forum_active();
- id()
eg: $cash_id = $c_cur->id();
retreives the currency's id
- name($supress_image = false, $quotes = false)
eg: $display = $c_cur->name();
gives a string output of the currency's symbol. It defaults to the currency's image (with the alt text equal to the currency's name) if it exists, otherwise it displays the currency's name. If the currency does not have an image, then it displays the name regardless.
- db()
eg: $db_field = $c_cur->db();
returns the text value of the database field in the user table that the currency is associated with.
- display($amount,$surpress_image = false, $quotes = false)
eg: $amount = $c_cur->display($userdata['user_points']);
formats a number to be displayed with the currency's symbol (prefix and postfix stuff is handled with this, you don't need to worry about it)
- mask($bitmask = false, $forum_id = false)
(eg: if ( $c_cur->mask(CURRENCY_DONATE) )
returns true if that bit is set for the currency
- forum_active($forum_id)
(eg, $main_forum_on = $c_cur->forum_active(1);
returns true if the currency is not disabled for the forum in question. Note, this can still return true if the currency itself is (as a whole) disabled.