If you are needing to provide a way for your donors to search all of your projects and then donate through a specific page, we have a simple script you can use. All you need is to use the following javascript, there are no other needed dependencies. Simply copy and paste any one of the example templates in this article into your website and the script will create the search box seen below and needed API calls to query RaiseDonors projects and campaigns.
Pro Tip: Any project having a meta key of "public-api.isprivate" and value equal to "true" will not be included in any responses from the RaiseDonors API.
Default Example
The following script is intended to query projects and use the default settings.
<!-- Required script reference -->
<script src="https://api.raisedonors.com/js/fundsearch.js" id='rd-fund-js'></script>
<script>
fundSearchJS.init(
01234, //orgId
'https://raisedonors.com/', //org base URL. If you have a white label domain, use that. Example: 'https://sub.organization.org'
'rd-fund-js', //dom element id
null, //custom filter provider
false, //debug info?
'test-page', //campaign/page url
);
</script>
How to configure
The main object in this script is "campaignSearchJS", which is defined through our javascript file, "https://api.raisedonors.com/js/campaignsearch.js".
You need to call the initializer method "init" and provide the following arguments.
- Organization ID
This can be located in the top right of the admin area when you are logged into RaiseDonors, it will be inside the square brackets [ ]. - Organization Base Url
This is the root link to your organization in RaiseDonors. For most customers, this will look something similar to https://raisedonors.com/ and for white label customers, this will be the full white label URL, similar to https://sub.organization.org/. - Dom ID
The identifier of the dom element to dynamically create the search box. - Filter Provider
The custom filter provider allows you to specify a custom function to filter the results being returned from RaiseDonors. You can use any of the built-in filter parameters or you may use a custom filter provider.
- If you pass "null", no filter provider will be used.
- Starts With :: use the string "Awesomplete.FILTER_STARTSWITH".
- Contains :: use the string "Awesomplete.FILTER_CONTAINS".
- Custom filter provider allows you to create customized business rules for your filter needs. If the function evaluates to "false", the specific item will be excluded from the search results and will not be available. Two parameters are required for this function.
- text : The data being returned from RaiseDonors, to be displayed and searched through.
- input : The user provided input.
- Campaign Url
Every page in RaiseDonors has a customizable url. The standardized url structure is similar to,
{baseUrl} / {org-url} / {page-url}. You'll want to pass the {page-url} component, such as "page-url-here". For example: https://raisedonors.com/your-org-url-here/page-url-here.- Pro-tip: If you want to add url parameters to configure the landing page, you can pass them in with the campaign url. For example, if you desire to include first and last name, you could pass this full string in as the campaign url, page-url-here?fname=joe&lname=McTester
- Debug
Debugging information? Helpful to diagnose issues.
Customize Filter: Starts With
The following script is intended to query campaigns and filter results using the "starts with" logic. A donor who types "miss", will return results starting with "miss", such as missionary. This filter is not case sensitive.
<!-- Required script reference -->
<script src="https://api.raisedonors.com/js/fundsearch.js" id='rd-fund-js'></script>
<script>
fundSearchJS.init(
01234, //orgId
'https://raisedonors.com/', //org base URL
'rd-fund-js', //dom element id
Awesomplete.FILTER_STARTSWITH, //custom filter provider
false, //debug info?
'test-page', //campaign/page url
);
</script>
Customize Filter: Contains
The following script is intended to query campaigns and filter results using the "contains" logic. A donor who types "ary", will return results containing with "ary", such as missionary. This filter is not case sensitive.
<!-- Required script reference -->
<script src="https://api.raisedonors.com/js/fundsearch.js" id='rd-fund-js'></script>
<script>
fundSearchJS.init(
01234, //orgId
'https://raisedonors.com/', //org base Url
'rd-fund-js', //dom element id
Awesomplete.FILTER_CONTAINS, //custom filter provider
false, //debug info?
'test-page', //campaign/page url
);
</script>
Customize Filter: Custom Filter
The following script is intended to query campaigns and filter results using custom logic for filtering. In this specific case, this will only match strings that start with the user’s input and this is case sensitive. Meaning "miss" will not match "Missionary".
<!-- Required script reference -->
<script src="https://api.raisedonors.com/js/fundsearch.js" id='rd-fund-js'></script>
<script>
//Returns true if the match is successful and false if it is not.
//Parameter 1: the current suggestion text that’s being tested
//Parameter 2: string with the user’s input its matched against.
//For example, to only match strings that start with the user’s input, case sensitive, we can do this:
function customFilter(text, input) {
return text.indexOf(input) === 0;
}
fundSearchJS.init(
01234, //orgId
'https://raisedonors.com/', //org base Url
'rd-fund-js', //dom element id
customFilter, //custom filter provider
false, //debug info?
'test-page', //campaign/page url
);
</script>
Pro tip example: Customize landing page
The following script is intended to demonstrate how you can customize the donation page using url parameters.
<!-- Required script reference -->
<script src="https://api.raisedonors.com/js/fundsearch.js" id='rd-fund-js'></script>
<script>
fundSearchJS.init(
01234, //orgId
'https://raisedonors.com/', //org base Url
'rd-fund-js', //dom element id
Awesomplete.FILTER_CONTAINS, //custom filter provider
false, //debug info?
'test-page?amt=50&fname=joe', //campaign/page url with amount and first name
);
</script>
Customize Filter: Additional Examples
<script>
function customFilter(text, input) {
try {
//clean the input provided by the user in the search box
var cleanedInput = input.toLowerCase().trim();
//clean the input provided by the API results
var cleanedText = text.toLowerCase().trim();
//Exclude any input from user starting with Z100
if (cleanedInput.startsWith('z1') ||
cleanedInput.startsWith('z10') ||
cleanedInput.startsWith('z100')) {
return false;
}
//Exclude any input from user containing SALES
else if (cleanedInput.includes('sales')) {
return false;
}
//Exclude any results from API containing 'abc'
else if ( cleanedText === 'abc') {
return false;
}
//evaluate any results from API containing '123' - to see if user typed 'abc'
else if (cleanedText.includes('123')) {
return cleanedInput.includes('abc');
}
//return api results that contain what the user typed
else {
return text.toLowerCase().trim().includes(cleanedInput);
}
}
catch(ex) {
console.log(ex);
}
}