DonateProvider
The DonateProvider is a context provider that manages the state and settings for donation-related components, such as CheckoutDonate. It handles fetching donation configurations, updating settings, and providing this data to its children components. To function correctly, DonateProvider must be placed within a PaymentProvider.
This structure ensures that donation components have access to both the general payment context and the specific donation settings.
Props#
The DonateProvider accepts the following props to configure its behavior:
Prop | Type | Required | Description |
|---|---|---|---|
|
| Yes | A unique identifier for this specific donation instance. It's used to fetch and store settings, ensuring that different donation points in your application have their own configurations. |
|
| Yes | A description to help identify this donation instance in logs or admin interfaces. |
|
| No | An object with default settings for the donation component. These settings are used when no configuration has been saved for the given |
|
| Yes | The child components that will be rendered within the provider. Typically, this will include one or more |
|
| No | A flag to control whether the donation functionality is active. Defaults to |
|
| No | If set to |
DonateConfigSettings#
The defaultSettings prop accepts an object with the following structure:
Key | Type | Description |
|---|---|---|
|
| Configuration for donation amounts. Contains |
|
| Custom text for the main donation button (e.g., "Like", "Support"). |
|
| Defines the display style for the donation history. |
Usage Example#
Here is a complete example of how to set up DonateProvider to wrap a CheckoutDonate component. This setup ensures that the donation button has access to the necessary context from both providers.
import {
PaymentProvider,
DonateProvider,
CheckoutDonate,
} from '@blocklet/payment-react';
function DonationSection() {
// Assume `session` and `connectApi` are available
// from your application's authentication and API layers.
return (
<PaymentProvider session={session} connect={connectApi}>
<DonateProvider
mountLocation="unique-blog-post-123"
description="Donation button for the blog post about React Hooks"
defaultSettings={{
btnText: 'Support the Author',
amount: {
presets: ['1', '5', '10'],
custom: true,
minimum: '1',
},
}}>
<CheckoutDonate
settings={{
target: 'post-123',
title: 'Support Author',
description: 'If you find this article helpful, feel free to buy me a coffee',
reference: 'https://your-site.com/posts/123',
beneficiaries: [
{
address: 'user-did-address',
share: '100',
},
],
}}
/>
</DonateProvider>
</PaymentProvider>
);
}Using the Context#
You can access the donation context's state and functions using the useDonateContext hook. This is useful for building custom UI or logic that interacts with the donation settings.
import { useDonateContext } from '@blocklet/payment-react';
import { Button, Typography } from '@mui/material';
function CustomDonateUI() {
const { settings, refresh, updateSettings } = useDonateContext();
const handleUpdateBtnText = async () => {
try {
await updateSettings({ btnText: 'New Button Text!' });
// The settings will be automatically refreshed.
} catch (error) {
console.error('Failed to update settings:', error);
}
};
return (
<div>
<Typography>Current Button Text: {settings.settings?.btnText}</Typography>
<Button onClick={handleUpdateBtnText}>Change Text</Button>
<Button onClick={() => refresh(true)}>Force Refresh</Button>
</div>
);
}Context Values#
The useDonateContext hook returns an object with the following properties:
Key | Type | Description |
|---|---|---|
|
| An object containing the current settings for the donation instance, including its active status and configuration. |
|
| A function to manually trigger a refresh of the donation settings from the server. Pass |
|
| An async function to update and persist new settings for the donation instance. |
|
| An Axios instance configured for making requests to the payment API. |
Utility Functions#
The library also exports utility functions to manage the donation settings cache outside of the React component lifecycle.
clearDonateCache#
Removes the cached settings for a specific mountLocation from localStorage.
import { clearDonateCache } from '@blocklet/payment-react';
// Call this when you know the settings are stale
clearDonateCache('unique-blog-post-123');clearDonateSettings#
Sends a DELETE request to the server to completely remove the settings for a mountLocation and also clears the local cache.
import { clearDonateSettings } from '@blocklet/payment-react';
// Use this to reset a donation instance to its default state
async function resetDonationSettings() {
await clearDonateSettings('unique-blog-post-123');
}After setting up the provider, the next step is to implement the donation UI. See the CheckoutDonate documentation for details.