feat: restructure docs into store, marketing, builder, and config sections
This commit is contained in:
Dwindi Ramadhana
311
contents/docs/developer/addons/custom-channels/index.mdx
Normal file
311
contents/docs/developer/addons/custom-channels/index.mdx
Normal file
@@ -0,0 +1,311 @@
|
||||
---
|
||||
title: Custom Notification Channels
|
||||
description: Learn how to add custom notification channels like WhatsApp, SMS, or Telegram to WooNooW
|
||||
---
|
||||
|
||||
# Custom Notification Channels
|
||||
|
||||
WooNooW supports custom notification channels through a pluggable architecture. You can extend the notification system to send messages via WhatsApp, SMS, Telegram, or any other service.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The multi-channel notification system consists of three core components:
|
||||
|
||||
1. **`ChannelInterface`** - Contract that all channels must implement
|
||||
2. **`ChannelRegistry`** - Central registry for managing channels
|
||||
3. **`NotificationManager`** - Sends notifications through registered channels
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[NotificationManager] --> B[ChannelRegistry]
|
||||
B --> C[Email Channel]
|
||||
B --> D[WhatsApp Channel]
|
||||
B --> E[SMS Channel]
|
||||
B --> F[Custom Channel]
|
||||
```
|
||||
|
||||
## Creating a Custom Channel
|
||||
|
||||
### Step 1: Implement ChannelInterface
|
||||
|
||||
Create a class that implements `WooNooW\Core\Notifications\Channels\ChannelInterface`:
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace MyPlugin\Channels;
|
||||
|
||||
use WooNooW\Core\Notifications\Channels\ChannelInterface;
|
||||
|
||||
class WhatsAppChannel implements ChannelInterface {
|
||||
|
||||
public function get_id() {
|
||||
return 'whatsapp';
|
||||
}
|
||||
|
||||
public function get_label() {
|
||||
return __('WhatsApp', 'my-plugin');
|
||||
}
|
||||
|
||||
public function is_configured() {
|
||||
$api_key = get_option('my_whatsapp_api_key');
|
||||
return !empty($api_key);
|
||||
}
|
||||
|
||||
public function send($event_id, $recipient, $data) {
|
||||
// Your sending logic here
|
||||
return [
|
||||
'success' => true,
|
||||
'message' => 'Sent successfully'
|
||||
];
|
||||
}
|
||||
|
||||
public function get_config_fields() {
|
||||
return [
|
||||
[
|
||||
'id' => 'my_whatsapp_api_key',
|
||||
'label' => 'API Key',
|
||||
'type' => 'text',
|
||||
],
|
||||
];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Register Your Channel
|
||||
|
||||
Register your channel with the `ChannelRegistry` during plugin initialization:
|
||||
|
||||
```php
|
||||
use WooNooW\Core\Notifications\ChannelRegistry;
|
||||
use MyPlugin\Channels\WhatsAppChannel;
|
||||
|
||||
add_action('init', function() {
|
||||
$channel = new WhatsAppChannel();
|
||||
ChannelRegistry::register($channel);
|
||||
});
|
||||
```
|
||||
|
||||
### Step 3: Enable in Settings
|
||||
|
||||
Once registered, your channel will be available in the notification settings UI, where users can configure which events should use WhatsApp.
|
||||
|
||||
## Interface Reference
|
||||
|
||||
### get_id()
|
||||
|
||||
Returns a unique identifier for your channel.
|
||||
|
||||
```php
|
||||
public function get_id(): string
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```php
|
||||
public function get_id() {
|
||||
return 'whatsapp'; // or 'sms', 'telegram', etc.
|
||||
}
|
||||
```
|
||||
|
||||
### get_label()
|
||||
|
||||
Returns a human-readable label for the admin UI.
|
||||
|
||||
```php
|
||||
public function get_label(): string
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```php
|
||||
public function get_label() {
|
||||
return __('WhatsApp Business', 'my-plugin');
|
||||
}
|
||||
```
|
||||
|
||||
### is_configured()
|
||||
|
||||
Checks if the channel has all required configuration (API keys, credentials, etc.).
|
||||
|
||||
```php
|
||||
public function is_configured(): bool
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```php
|
||||
public function is_configured() {
|
||||
$api_key = get_option('my_whatsapp_api_key');
|
||||
$phone = get_option('my_whatsapp_phone');
|
||||
return !empty($api_key) && !empty($phone);
|
||||
}
|
||||
```
|
||||
|
||||
### send()
|
||||
|
||||
Sends a notification through this channel.
|
||||
|
||||
```php
|
||||
public function send(string $event_id, string $recipient, array $data): bool|array
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `$event_id` - Event identifier (e.g., `'order_completed'`, `'newsletter_confirm'`)
|
||||
- `$recipient` - Recipient type (`'customer'` or `'staff'`)
|
||||
- `$data` - Context data including order, user, custom variables
|
||||
|
||||
**Returns:**
|
||||
- `bool` - Simple success/failure
|
||||
- `array` - Detailed result with `success` and `message` keys
|
||||
|
||||
**Example:**
|
||||
```php
|
||||
public function send($event_id, $recipient, $data) {
|
||||
$phone = $this->get_recipient_phone($recipient, $data);
|
||||
$message = $this->build_message($event_id, $data);
|
||||
|
||||
$response = wp_remote_post('https://api.provider.com/send', [
|
||||
'body' => [
|
||||
'to' => $phone,
|
||||
'message' => $message,
|
||||
'api_key' => get_option('my_api_key'),
|
||||
],
|
||||
]);
|
||||
|
||||
if (is_wp_error($response)) {
|
||||
return [
|
||||
'success' => false,
|
||||
'message' => $response->get_error_message(),
|
||||
];
|
||||
}
|
||||
|
||||
return ['success' => true];
|
||||
}
|
||||
```
|
||||
|
||||
### get_config_fields()
|
||||
|
||||
Returns configuration fields for the admin settings UI (optional).
|
||||
|
||||
```php
|
||||
public function get_config_fields(): array
|
||||
```
|
||||
|
||||
**Field Structure:**
|
||||
```php
|
||||
[
|
||||
'id' => 'option_name',
|
||||
'label' => 'Field Label',
|
||||
'type' => 'text|select|textarea',
|
||||
'description' => 'Help text',
|
||||
'options' => [], // For select fields
|
||||
'default' => 'value',
|
||||
]
|
||||
```
|
||||
|
||||
## Complete Example: WhatsApp Channel
|
||||
|
||||
See the reference implementation:
|
||||
[WhatsAppChannel.example.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/Channels/WhatsAppChannel.example.php)
|
||||
|
||||
This example includes:
|
||||
- ✅ Twilio API integration
|
||||
- ✅ Phone number extraction from orders/users
|
||||
- ✅ Message templates for common events
|
||||
- ✅ Configuration fields for admin settings
|
||||
|
||||
## Message Customization
|
||||
|
||||
Use filters to customize messages for specific events:
|
||||
|
||||
```php
|
||||
add_filter('woonoow_whatsapp_message_order_completed', function($message, $data) {
|
||||
if (isset($data['order'])) {
|
||||
$order = $data['order'];
|
||||
return sprintf(
|
||||
"🎉 Order #%s confirmed! Track here: %s",
|
||||
$order->get_order_number(),
|
||||
$order->get_view_order_url()
|
||||
);
|
||||
}
|
||||
return $message;
|
||||
}, 10, 2);
|
||||
```
|
||||
|
||||
## Available Events
|
||||
|
||||
Your channel can handle any registered notification event:
|
||||
|
||||
| Event | Recipient | Data Available |
|
||||
|-------|-----------|----------------|
|
||||
| `order_completed` | customer | `order`, `user_id` |
|
||||
| `order_cancelled` | customer | `order`, `user_id` |
|
||||
| `newsletter_confirm` | customer | `email`, `confirmation_url` |
|
||||
| `newsletter_welcome` | customer | `email`, `user_id` |
|
||||
| `subscription_expiring` | customer | `subscription`, `user_id` |
|
||||
|
||||
See [Event Registry](/hooks/notifications#event-registry) for the complete list.
|
||||
|
||||
## Testing Your Channel
|
||||
|
||||
```php
|
||||
// Manual test
|
||||
use WooNooW\Core\Notifications\NotificationManager;
|
||||
|
||||
NotificationManager::send('order_completed', 'whatsapp', [
|
||||
'order' => wc_get_order(123),
|
||||
'user_id' => 1,
|
||||
]);
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Validate Configuration**: Always check `is_configured()` before attempting to send
|
||||
2. **Handle Errors Gracefully**: Return detailed error messages for debugging
|
||||
3. **Log Send Attempts**: Use `do_action()` for tracking/analytics
|
||||
4. **Support Filtering**: Allow message customization via filters
|
||||
5. **Rate Limiting**: Consider implementing rate limiting for API calls
|
||||
|
||||
## Hooks
|
||||
|
||||
### Registration Hook
|
||||
```php
|
||||
// Register channels during init
|
||||
add_action('init', function() {
|
||||
ChannelRegistry::register(new MyChannel());
|
||||
});
|
||||
```
|
||||
|
||||
### Custom Hooks in Your Channel
|
||||
```php
|
||||
// Allow logging/tracking
|
||||
do_action('my_channel_sent', $event_id, $recipient, $result);
|
||||
|
||||
// Allow message customization
|
||||
$message = apply_filters(
|
||||
"my_channel_message_{$event_id}",
|
||||
$default_message,
|
||||
$data
|
||||
);
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Channel not appearing in settings?**
|
||||
- Ensure `ChannelRegistry::register()` is called during `init`
|
||||
- Check that `get_id()` returns a unique string
|
||||
- Verify `is_configured()` returns `true`
|
||||
|
||||
**Messages not sending?**
|
||||
- Check notification settings: Marketing > Notifications
|
||||
- Verify the event has your channel enabled
|
||||
- Enable debug mode and check logs
|
||||
- Test `is_configured()` returns true
|
||||
|
||||
**API errors?**
|
||||
- Validate API credentials in settings
|
||||
- Check API provider status/quotas
|
||||
- Review error logs for API responses
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Notification System](/core-concepts/notifications)
|
||||
- [Event Registry](/hooks/notifications#event-registry)
|
||||
- [Notification Hooks](/hooks/notifications)
|
||||
103
contents/docs/developer/addons/page-templates/index.mdx
Normal file
103
contents/docs/developer/addons/page-templates/index.mdx
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: Custom Page Templates
|
||||
description: Learn how to register custom starting templates for the Page Editor.
|
||||
---
|
||||
|
||||
WooNooW allows developers to register custom page templates. These templates appear in the "Create New Page" modal, allowing users to start with a pre-configured layout instead of a blank page.
|
||||
|
||||
## Registering a Template
|
||||
|
||||
To add a new template, use the `woonoow_page_templates` filter. You should append your template definition to the existing array.
|
||||
|
||||
```php
|
||||
add_filter('woonoow_page_templates', function($templates) {
|
||||
$templates[] = [
|
||||
'id' => 'my-custom-landing',
|
||||
'label' => 'Product Launch',
|
||||
'description' => 'A structured page for new product announcements.',
|
||||
'icon' => 'rocket', // Lucide icon name (lowercase)
|
||||
'sections' => [
|
||||
// Section definitions...
|
||||
]
|
||||
];
|
||||
return $templates;
|
||||
});
|
||||
```
|
||||
|
||||
## Template Structure
|
||||
|
||||
Each template requires the following properties:
|
||||
|
||||
| Property | Type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `id` | string | Unique identifier for the template. |
|
||||
| `label` | string | Display name shown in the modal. |
|
||||
| `description` | string | Short description of the template's purpose. |
|
||||
| `icon` | string | Name of a Lucide icon (e.g., `layout`, `users`, `rocket`). |
|
||||
| `sections` | array | Array of section objects defining the initial layout. |
|
||||
|
||||
### Defining Sections
|
||||
|
||||
Sections are the building blocks of a page. Each section object mimics the structure stored in the database.
|
||||
|
||||
```php
|
||||
[
|
||||
'id' => uniqid('section_'), // Must be unique
|
||||
'type' => 'hero', // Component type (hero, feature-grid, image-text, etc.)
|
||||
'props' => [
|
||||
'title' => ['type' => 'static', 'value' => 'Hello World'],
|
||||
'subtitle' => ['type' => 'static', 'value' => 'This is a template.'],
|
||||
],
|
||||
'styles' => [
|
||||
'contentWidth' => 'contained', // 'full' or 'contained'
|
||||
'padding' => 'medium',
|
||||
]
|
||||
]
|
||||
```
|
||||
|
||||
## Example: Full Configuration
|
||||
|
||||
Here is a complete example that registers a "Support Page" template with a Hero and a FAQ section.
|
||||
|
||||
```php
|
||||
add_filter('woonoow_page_templates', function($templates) {
|
||||
$templates[] = [
|
||||
'id' => 'support-page',
|
||||
'label' => 'Support Center',
|
||||
'description' => 'Help desk layout with search and FAQ grid.',
|
||||
'icon' => 'help-circle',
|
||||
'sections' => [
|
||||
// Hero Section
|
||||
[
|
||||
'id' => uniqid('section_'),
|
||||
'type' => 'hero',
|
||||
'props' => [
|
||||
'title' => ['type' => 'static', 'value' => 'How can we help?'],
|
||||
'cta_text' => ['type' => 'static', 'value' => 'Contact Support'],
|
||||
'cta_url' => ['type' => 'static', 'value' => '/contact'],
|
||||
],
|
||||
'styles' => ['contentWidth' => 'full']
|
||||
],
|
||||
// Content Section
|
||||
[
|
||||
'id' => uniqid('section_'),
|
||||
'type' => 'content',
|
||||
'props' => [
|
||||
'content' => ['type' => 'static', 'value' => '<h2>Frequently Asked Questions</h2><p>Find answers below.</p>']
|
||||
],
|
||||
'styles' => ['contentWidth' => 'contained']
|
||||
]
|
||||
]
|
||||
];
|
||||
return $templates;
|
||||
});
|
||||
```
|
||||
|
||||
## Available Section Types
|
||||
|
||||
Common available section types include:
|
||||
- `hero`: Large banner with title, subtitle, and CTA.
|
||||
- `content`: Rich text editor content.
|
||||
- `image-text`: Split layout with image and text.
|
||||
- `feature-grid`: Grid of icons and text.
|
||||
- `cta-banner`: Call to action strip.
|
||||
Reference in New Issue
Block a user