</> Developers Guide to Funraisin

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)

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.

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,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,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,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