Helpers
As well as being built using CodeIgnitor allowing you to use any of the standard CodeIgnitor features, Funraisin also has a lot of built in helpers to help make things easier to do.
Database Helpers
Below are a list of built in PHP functions (helpers) that allow you to interact with a Funraisin database.
MySQLResult($Query,$ResultColumn,$ReadOnly=false);
e.g. MySQLResult("SELECT count(*) as cnt from donations","cnt");
Performs a database call to the main database and pulls out a single column of data $ResultColumn. If $ReadOnly is set to true then it uses the ReadOnly database (if applicable)
MySQLArray($Query,$ReadOnly=false);
e.g. MySQLArray("SELECT * from donations WHERE donation_id=123");
Performs a database call on the main database and pulls out an entire row as an Array. Returns Array. If $ReadOnly is set to true then it uses the ReadOnly database (if applicable)
MySQLRows($Query,$limit=100,$offset=0,$ReadOnly=false);
e.g. MySQLRows("SELECT * from donations",100,0);
Performs a database call on the main database and pulls out multiple rows as an Array. Returns Array. If $ReadOnly is set to true then it uses the ReadOnly database (if applicable). $limit cannot be increased to greater than 100 records
MySQLInsert($Data,$Table);
e.g. MySQLInsert(array("member_id"=>1,"step"=>"shared-page","date_created"=>date("Y-m-d H:i:s")),"members_steps");
Generates an INSERT query SQL, to be used in conjunction with $this->db->query(MySQLInsert($Data,$Table)); Returns a SQL statement.
MySQLUpdate($Data,$Table,$Field,$ID);
e.g. MySQLUpdate(array("d_status"=>"paid"),"donations","donation_id",1);
Generates an UPDATE query SQL, to be used in conjunction with $this->db->query(); Returns a SQL statement complete with WHERE clause.
Cached DB Helpers
When you are needing to cache the DB output you can use the below helpers
MySQLResultCache($Query,$ResultColumn,$data=array(),$CacheName,$Expiry=300);
e.g. MySQLResultCache("SELECT count(*) as cnt from donations","cnt",$data,"MyCache",300);
Performs a database call to the main database and pulls out a single column of data $ResultColumn and then caches the output for the specified time in seconds.
MySQLArrayCache($Query,$data=array(),$CacheName,$Expiry=300);
e.g. MySQLArrayCache("SELECT * from donations WHERE donation_id=123",$data,"MyCache",300);
Performs a database call on the main database and pulls out an entire row as an Array. Returns Array and caches the output for the specified time in seconds.
MySQLRowsCache($Query,$limit=100,$offset=0,$data=array(),$CacheName,$Expiry=300);
e.g. MySQLRowsCache("SELECT * from donations WHERE history_id=123",100,0,$data,"MyCache",300);
Performs a database call on the main database and pulls out multiple rows as an Array. Returns Array and caches the output for the specified time in seconds.
Output Data Helpers
The following is a list of PHP helpers that can assist with data handling Output (displaying on a page or pre-populating a webform).
ShowDataText($FieldName,$Array);
Used when wanting to display captured form data back in the form field itself, it sanitizes any data and safely displays the value in the form field. $FieldName being the name of the field you are retrieving and $Array being the data array you are retrieving it from.
e.g. < input type="text" name="m_fname" id="m_fname" value="< ?= ShowDataText("m_fname",$MemberDetails); ? >" / >
This will display the variable "m_fname" looking first from $_GET and then $_POST and then the array provided, in this case $MemberDetails
You should never use just $_POST["field_name"] or $_GET["field_name"] or $ChosenArray["field_name"] etc when displaying user generated content in a webform field as it exposes you to XSS.
ShowDataTextNoXss($FieldName,$Array);
Used when we don't want to have the content stripped out for nasties, used only when we know it's safe to allow things like Javascript which is usually only in a protected area such as an Admin.
ShowDataTextHTML($FieldName,$Array);
Similar to the first helper but this will not return escaped data so this can be used when you wish to allow HTML content
Input Data Helpers
The following is a list of PHP helpers that can assist with data handling Input.
PrepareData($Value,$NotEqualTo opt,$DefaultValue opt);
This helper is used when handling DB inserts or updates and is used in conjunction with a DB insert or update query below.
e.g. $DataToInsert=array( "m_fname"=>PrepareData("m_fname"), "m_lname"=>PrepareData("m_lname"), "m_email"=>PrepareData("m_email"));
echo MySQLInsert($DataToInsert,"members");
Will produce: INSERT INTO members (`m_fname`,`m_lname`,`m_email`) VALUES ('Jon','Doe','jon@gmail.com')
Commonly used with a DB Insert command such as: $this->db->query(MySQLInsert($DataToInsert,"members"));
Any nasties in the submitted data will be escaped and dealt with by the XSS filter so much better than just using "m_fname"=>$_POST["m_fname"]
PrepareDataNoXss($Value)
Similar to above but data won't be checked for nasties and XSS etc so it will accept whatever is inputted. Can only be used in a safe environment where you know the user e.g. Admin
PrepareDataEnum($Value,$DefaultValue opt)
Used for accepting input data from things like checkboxes where it needs to either return a Y or N value. If no value is received it will return "N"
e.g. $DataToInsert=array( "m_fname"=>PrepareData("m_fname"), "m_lname"=>PrepareData("m_lname"), "m_email"=>PrepareData("m_email"), "m_optin"=>PrepareDataEnum("m_optin"));
echo MySQLInsert($DataToInsert,"members");
Will produce: INSERT INTO members (`m_fname`,`m_lname`,`m_email`,`m_optin`) VALUES ('Jon','Doe','jon@gmail.com','N')
Select Helpers
There are also some built in helpers that allow you to interact with Selects, Checkboxes and Radio buttons more easily in terms of accessing selected data from the database.
PopulateSelect($Table,$ID,$FieldName,$SelectedData,$Where);
< select name="teams">
< option value="">- Choose a Team -
< ?=PopulateSelect("teams","team_id","t_name",ShowDataText("team_id"),"1 ORDER BY t_name ASC");? >
Personalisation
Often when we add in custom code such as sending an email, we will want to allow the content to be personalised from data stored in the database, the most common scenario is pulling out a fundraiser's details to have displayed in an email or on a page.
To achieve this we have a helper called EvaluateContent();
Fundraising Helpers
The following is a list of PHP helpers that can assist with common tasks relating to Fundraising.
GetDonations($history_id=0,$team_id=0,$member_id=0,$event_id=0,$cache='Y',$org_id=0);
e.g. $mydonations = GetDonations(123,0);
Performs a database query to calculate the current amount raised for the fundraiser / team / org. All queries will be cached for a period of 10 mins. Output will be un-formatted.
GetDIYDonations($category_id=0,$cache='Y');
e.g. $themedonations = GetDIYDonations(1);
Performs a database query to calculate the current amount raised for the entire DIY theme. All queries will be cached for a period of 10 mins. Output will be un-formatted.
GetLocalDonations($history_id=0,$team_id=0,$member_id=0,$event_id=0,$cache='Y',$org_id=0);
e.g. $mydonations = GetLocalDonations(123,0);
Performs a database query to calculate the current amount raised for the fundraiser / team / org in their native currency. Used for multi-currency sites only. All queries will be cached for a period of 10 mins. Output will be un-formatted.
GetGiftAid($history_id=0,$team_id=0,$member_id=0,$event_id=0,$cache='Y',$org_id=0);
e.g. $mygiftaid = GetGiftAid(123,0);
Performs a database query to calculate the current gift aid from amounst raised for the fundraiser / team / org. All queries will be cached for a period of 10 mins. Output will be un-formatted.
CalculateRank($member_id=0,$team_id=0,$history_id=0,$NoOrdinize=N,$Readonly=false);
Performs a database query to try and work out the current ranking of a person or team based on their amount raised. All queries are cached for 30 mins
Fitness Helpers
The following is a list of PHP helpers that can assist with common tasks relating to Fitness Data.
getFitnessData($history_id=0,$team_id=0,$org_id=0,$event_id=0);
e.g. $Fitness = GetFitnessData(123,0);
Performs a database query to calculate varous fitness data for the fundraiser / team / org. All queries will be cached for a period of 15 mins. Output will be un-formatted.
Returns
array("steps"=>1000,
"hours"=>10000,
"distance"=>800 // in metres
"cnt"=>10 // number of activities
)
Rank Helpers
The following is a list of PHP helpers that can assist with common tasks relating to Ranking.
CalculateFundraisingRank($options=array());
Options: team_id,member_id,history_id,org_id,ReadOnly (true/false),Ordinize (true/false)
e.g. $Rank = CalculateFundraisingRank(["member_id"=>123,history_id=>123]);
Performs a database query to calculate the current fundraising rank of the fundraiser, team or organisation.
CalculateDistanceRank($options=array());
Options: team_id,member_id,history_id,org_id,ReadOnly (true/false),Ordinize (true/false)
e.g. $Rank = CalculateDistanceRank(["member_id"=>123,history_id=>123]);
Performs a database query to calculate the current distance rank of the fundraiser, team or organisation.
CalculateDurationRank($options=array());
Options: team_id,member_id,history_id,org_id,ReadOnly (true/false),Ordinize (true/false)
e.g. $Rank = CalculateDurationRank(["member_id"=>123,history_id=>123]);
Performs a database query to calculate the current rank of the ffundraiser, team or organisation based on duration achieved
CalculateStepsRank($options=array());
Options: team_id,member_id,history_id,org_id,ReadOnly (true/false),Ordinize (true/false)
e.g. $Rank = CalculateStepsRank(["member_id"=>123,history_id=>123]);
Performs a database query to calculate the current rank of the fundraiser, team or organisation based on steps achieved
Leaderboard Helpers
The following is a list of PHP helpers that can assist generating common leaderboard queries. These will return an array of data allowing you to then render a leaderboard, you can also optionally specify an output format of JSON.
GenerateMemberLeaderboardQuery($leaderboardType,$options=array());
Options: team_id,event_id,org_id,charity_id,customfield,limit,expiry (in seconds), output (json or array)
LeaderboardType Options: fundraising,steps,duration,distance
Returns Array: leaderboard=[
"member_id"=>Id of the fundraiser,
"name" => Name of the Fundraiser,
"company" => Organisation,
"url" => Url to fundraising page,
"distance" => total distance,
"steps" => total steps,
"duration" => total duration in hours,
"raised" => Total raised,
"target" = Fundraising or Fitness target,
"photo" => Profile Pic,
"event_name" => Name of Event
];
e.g. $LeaderboardQuery = GenerateMemberLeaderboardQuery("fundraising",["event_id"=>1,"expiry"=>3600,"limit"=>5]);
This will perform the database query, cache the query for however long is defined in "expiry" and then return a PHP Array of data that you can then access via
foreach($LeaderboardQuery["leaderboard"] as $leaderboard) {
}
GenerateTeamLeaderboardQuery($leaderboardType,$options=array());
Options: event_id,org_id,charity_id,customfield,limit,expiry (in seconds), output (json or array)
LeaderboardType Options: fundraising,steps,duration,distance
Returns Array: leaderboard=[
"team_id"=>Id of the team,
"name" => Name of the team,
"url" => Url to fundraising page,
"distance" => total distance,
"steps" => total steps,
"duration" => total duration in hours,
"raised" => Total raised,
"target" = Fundraising or Fitness target,
"photo" => Profile Pic,
"event_name" => Name of Event
];
e.g. $LeaderboardQuery = GenerateTeamLeaderboardQuery("fundraising",["event_id"=>1,"expiry"=>3600,"limit"=>5]);
This will perform the database query, cache the query for however long is defined in "expiry" and then return a PHP Array of data that you can then access via
foreach($LeaderboardQuery["leaderboard"] as $leaderboard) {
}
GenerateOrgLeaderboardQuery($leaderboardType,$options=array());
Options: event_id,charity_id,customfield,limit,expiry (in seconds), output (json or array)
LeaderboardType Options: fundraising,steps,duration,distance
Returns Array: leaderboard=[
"org_id"=>Id of the org,
"name" => Name of the org,
"url" => Url to fundraising page,
"distance" => total distance,
"steps" => total steps,
"duration" => total duration in hours,
"raised" => Total raised,
"target" = Fundraising or Fitness target,
"photo" => Profile Pic,
"event_name" => Name of Event
];
e.g. $LeaderboardQuery = GenerateOrgLeaderboardQuery("fundraising",["event_id"=>1,"expiry"=>3600,"limit"=>5]);
This will perform the database query, cache the query for however long is defined in "expiry" and then return a PHP Array of data that you can then access via
foreach($LeaderboardQuery["leaderboard"] as $leaderboard) {
}
Constants
The following constants exist on each Funraisn site.
Platform Related
SITEURL
Returns the full url to the site e.g. https://support.funraisin.co/
SECUREURL
Same as above
ISMOBILE
Returns TRUE if the site visitor is on a mobile device
TEMP_UPLOADS
Path to the tmp directory where we store file uploads
USER_UPLOADS_NICE
Full url to the CDN where file uploads are stored
Site Visitor Related
UserCountryCode
Phone country code e.g. 61 for Australia
UserCountry
Country where the visitor is located as determined by their IP e.g. Australia
UserCountryPrefix
2 digit country code of above e.g. AU
UserCurrency
The currency of the user as detemined by their country code e.g. AUD
Language
The language of the user as detemined by their country e.g. EN
ActiveLanguage
Current active language. For multi-lingual sites a visitor can switch languages
Fundraiser Related
LoggedIn
Returns TRUE if the fundraiser is currenly logged in otherwise FALSE
IsFundraising
Returns TRUE if the loggedin fundraiser has an active fundraising event
NumEvents
The number of events that a logged in fundraiser has
LoggedInMemberID
Returns the logged in fundraiser's ID
LoggedInHistoryID
Returns the logged in fundraiser's active History ID
FirstName
First name of the fundraiser
UserName
The fundraiser's profile name / username
InTeam
Returns TRUE if the logged in fundraiser is part of a team for their current active event
IsCaptain
Returns TRUE if the logged in fundraiser is also a team captain for their current active event
TeamAccess
Returns TRUE if the logged in fundraiser has been given team captain like access, for their current active event
TeamUrl
The full url to the team fundraising page for any logged in team member
TeamName
The team name if the logged in fundraiser is part of a team for their current active event
TeamNoun
The noun used for teams e.g. team (sometimes we change it to things like school)
InOrg
Returns TRUE if the logged in fundraiser is part of an organisation for their current active event
IsOrgCaptain
Returns TRUE if the logged in fundraiser is the creator of the organisation
OrgAccess
Returns TRUE if the logged in fundraiser has been given Organisation captain like access
OrgUrl
The full url to the logged in fundraiser's organsation page
OrgName
The name of the logged in fundraiser's organisation page
OrgNoun
The noun used for organisation pages for the fundraisers active event e.g. organisation
Donor Related
DonorName
LoggedInDonor
Admin Related
IsAdmin
AdminID
AdminName
IsReadOnly
IsPublish
CharityID
