Pure Charity Plugin Installation Instructions

The Pure Charity Plugin is designed to integrate various Pure Charity products and features into your WordPress site. This document provides instructions on how to install, configure, and use the plugin.

Installation

1. Download the Plugin:
   • Download the plugin files and ensure they are in a compressed .zip format.
2. Upload the Plugin:
   • Log in to your WordPress admin dashboard.
   • Navigate to Plugins > Add New.
   • Click on the Upload Plugin button at the top of the page.
   • Choose the downloaded .zip file and click Install Now.
3. Activate the Plugin:
   • Once the plugin is installed, click on the Activate button to activate the plugin.

Configuration

After activating the plugin, you need to configure it to suit your needs. The plugin provides several modules, each with its own settings.

General Settings

1. Navigate to Settings:
   • Go to Settings > Pure Charity.
2. API Settings:
   • API Mode: Choose between Live or Sandbox mode. Unless you were specifically instructed to use a staging sandbox you will choose Live
   • API Key: Enter your Pure Charity API key.
3. Main Theme Color:
   • Set the main theme color for the plugin and Save.
     
     
     

     PureCharity Plugin – Shortcodes Reference

     Use this guide to embed PureCharity data inside WordPress posts, pages, and reusable blocks. Shortcodes can be added through the block editor "Shortcode" block or the classic editor. For module-level defaults (API credentials, regions, date formats, etc.), navigate to Settings > PureBase in the WordPress admin before using the snippets below.

     Fundraisers

     [fundraisers]

     Purpose : Render a paginated list of fundraisers. It supports inline filtering, optional single-fundraiser expansion, and integrates with query-string parameters so visitors can refine the listing.
     Attributes
     • fundraiser (string, optional): Prefetch a fundraiser slug to open in the modal view when the page loads. Default: false.
     • query (string, optional): Default search phrase used to pre-filter results. Falls back to the query query-string parameter.
     • grid (boolean, optional): Toggle the grid layout (true) instead of the default list presentation. Accepts true or false. Default: value from grid query parameter or blank.
     • title (string, optional): Sort field helper used alongside order. Accepts owner_name to sort by founder name. Default: get_query_var('title').
     • campaign (string, optional): Filter by campaign slug. When omitted the shortcode auto-loads campaigns from the visitor's query string.
     • per_page (integer, optional): Number of fundraisers per page. Default: value from _GET['per_page'] or site default.
     • dir (string, optional): Sort direction (asc or desc). Default: query parameter dir or blank.
     • order (string, optional): API sort field (e.g., created_at, goal). Default: query parameter order or blank.
     • hide_search (boolean, optional): Hide the search form when set to true.
     • layout (integer, optional): Template variant (1–4). Defaults to the visitor query parameter or module default.
     Example

     [fundraisers per_page="12" grid="true" dir="asc" order="created_at"]
     

      

     Customization Tips
     • Combine with [fundraisers_search] to offer keyword search.
     • Append query parameters (e.g., ?campaign=back-to-school) to direct visitors to scoped fundraiser collections.
     • When embedding inside a modal or iframe, set hide_search="true" to remove duplicate search UI.

     [fundraisers_search]

     Purpose : Output a standalone search form that targets a page containing the [fundraisers] shortcode.
     Attributes
     • page_id (integer, required): ID of the page where search results should appear. Defaults to get_query_var('page_id') but the shortcode behaves best when explicitly set.
     Example

     [fundraisers_search page_id="123"]
     

      

     [last_fundraisers]

     Purpose : Highlight the most recently created or updated fundraisers in a compact grid. Supports the same filtering rules as [fundraisers] but limits the dataset to the latest records.
     Attributes
     • fundraiser (string, optional): Preselect a fundraiser slug to display the single view instead of the list.
     • query (string, optional): Seed search term used to narrow the recent fundraisers feed.
     • dir (string, optional): Sort direction (asc or desc). Defaults to the dir query parameter.
     • order (string, optional): Sort field forwarded to the API (for example created_at). Defaults to the order query parameter.
     • title (string, optional): Alternate sort selector. Use owner_name to order results by fundraiser founder.
     • limit (integer, optional): Number of fundraisers to return. Defaults to the limit query parameter.
     • layout (integer, optional): Template variant (1–4) used for the listing layout.
     • campaign (string, optional): Restrict the recent feed to a specific campaign slug when present in shortcode attributes or visitor query parameters.
     Example

     [last_fundraisers limit="3" layout="2" order="created_at" dir="desc"]
     

      

     [fundraiser]

     Purpose : Display the full detail view for a specific fundraiser.
     Attributes
     • slug (string, required): Fundraiser slug or permalink identifier. Defaults to get_query_var('slug') when omitted.
     • title (string, optional): Overrides the displayed heading. Defaults to get_query_var('title').
     • layout (integer, optional): Template variant (1–4) used for the detail view.
     • id (integer, optional): Internal fundraiser ID used when embedding via query string.
     Example

     [fundraiser slug="example-fundraiser-slug" layout="1"]
     

      

     [fundraiser_funding_bar]

     Purpose : Output the fundraising progress bar for a single fundraiser—ideal for sidebars and landing pages.
     Attributes
     • fundraiser (string, required): Fundraiser slug to fetch from the API.
     • standalone_bar (boolean, optional): When true (default), loads only the progress bar. Set to false to embed within an existing fundraiser layout wrapper.
     Example

     [fundraiser_funding_bar fundraiser="example-fundraiser-slug" standalone_bar="true"]
     

      

     [featured_fundraiser]

     Purpose : Showcase one flagship fundraiser with featured styling and optional call-to-action redirect.
     Attributes
     • slug (string, required): Target fundraiser slug.
     • title (string, optional): Override the default heading pulled from the API.
     • redirect (string, optional): Custom URL used when the featured card CTA is clicked.
     Example

     [featured_fundraiser slug="example-fundraiser-slug" redirect="https://example.org/donate"]
     

      

     Sponsorships

     [sponsorships]

     Purpose : Render an asynchronously loaded list of sponsorship profiles tied to a sponsorship program. Filters can be applied via shortcode attributes or visitor query parameters.
     Attributes
     • program_id (string, required): Sponsorship program identifier to load profiles from. This attribute is mandatory even though it is not part of the default shortcode_atts map.
     • status (string, optional): Limit results by sponsorship status (for example available, sponsored).
     • per_page (integer, optional): Limit results returned per request. Defaults to the module API configuration when omitted.
     • reject (string, optional): Flag forwarded to the API to exclude certain sponsorships (e.g., featured).
     Filter Query Parameters Visitors can append the following query parameters to refine results without editing the shortcode:
     • gender (Male or Female)
     • age (min-max or single age value)
     • country (two-letter country code or name)
     • location (location slug)
     • query (keyword search)
     • _page (pagination index)
     Example

     [sponsorships program_id="abc123" per_page="24" status="available"]
     

      

     [sponsorship] / [sponsorship_child]

     Purpose : Display a single sponsorship profile. Both shortcode tags are aliases and render the same view.
     Attributes
     • sponsorship (string, required): Sponsorship ID or slug returned from the API.
     Example

     [sponsorship sponsorship="child-12345"]
     

      

     Customization Tips
     • Pair with [sponsorships] by linking individual profiles (?sponsorship=child-12345) to transition from the list view to the single view seamlessly.

     Trips

     [trips]

     Purpose : Display a searchable and paginated list of trips. Supports geographic, thematic, and temporal filters and gracefully switches between list and grid layouts.
     Attributes
     • limit (integer, optional): Number of trips to request per page. Default: 10.
     • country (integer, optional): Filter by country ID. Defaults to get_query_var('country').
     • region (integer, optional): Filter by region ID. Defaults to get_query_var('region').
     • cause (string, optional): Filter by cause slug.
     • starts_at (string, optional): Limit trips starting on or after the provided ISO date.
     • ends_at (string, optional): Limit trips ending on or before the provided ISO date.
     • past (boolean, optional): When truthy, return past trips only.
     • upcoming (boolean, optional): When truthy, return upcoming trips only (overridden when include_past="true").
     • past_events (boolean, optional): Include archived trips in results. Defaults to visitor query parameter.
     • include_past (boolean, optional): When true, merge past events into the upcoming list and ignore upcoming.
     • grid (boolean, optional): Render the grid layout when set to true.
     • tag (string, optional): Filter by trip tag slug.
     • trip_tag (string, optional): Alternate tag filter driven by the trip_tag query parameter.
     • query (string, optional): Keyword search applied to trip titles and descriptions.
     • page (integer, optional): Starting pagination index. Defaults to _page query parameter.
     • sort (string, optional): API sort field such as date or name.
     • dir (string, optional): Sort direction (asc or desc).
     Example

     [trips limit="50" region="1" sort="date" dir="asc" upcoming="true" grid="true"]
     

      

     Customization Tips
     • Combine with [trips_filters] for an interactive filtering sidebar.
     • Append ?trip=<ID> to auto-open the single trip view from the listing.
     • Use include_past="true" to create an archive view while retaining upcoming trips in the same feed.

     [trip]

     Purpose : Display a single trip profile pulled from the Events API.
     Attributes
     • trip (integer, required): Trip identifier (event ID) returned from the API or listing.
     Example

     [trip trip="98765"]
     

      

     [trips_filters]

     Purpose : Render the interactive filter UI used by the [trips] shortcode. The component reads configuration from the PureBase module to populate regions, countries, departure dates, and trip types.
     Attributes
     • None
     Example

     [trips_filters]
     

      

     Customization Tips
     • Automatically hides itself when the trip query parameter is present, allowing single trip pages to omit redundant UI.
     • Works best when placed above the [trips] shortcode inside the same page template or block.