Client Sync Plugin - Developer Documentation Outline 1,4 Print

Client Sync Plugin - Developer Documentation Outline
Version: 1.4 (Reflecting Notification System Addition)

1. Overview & Purpose

• Mission: Client Sync is a WordPress plugin designed to provide a comprehensive scheduling and client management system for Administrators and Clients in a diverse spectrum of business categories.

• Core Features:

  • Client Registration with custom fields (including optional phone for SMS).

  • Appointment Scheduling based on predefined availability.

  • Appointment Management (Viewing, Editing).

  • Custom Fields for both Clients (Users) and Appointments.

  • Appointment Notes (via Post Content).

  • Manager roles/views (implied by manager-*.php files).

  • Visual Calendar Interfaces (Admin & Frontend).

  • Payment Integration (Basic - payments.php, WooCommerce integration planned).

  • Email & SMS Notifications: Customizable notifications for admins and clients triggered by various events (new appointments, cancellations, etc.).

2. Plugin Structure (File Organization)

• client-sync.php (Main Plugin File):

  • Plugin header information.

  • Constants (cs_PLUGIN_DIR, cs_PLUGIN_URL).

  • (Potentially includes vendor/autoload.php if using Composer for SMS SDKs).

  • Includes/requires all necessary functionality files from /includes.

  • Registers the appointment Custom Post Type (cs_register_appointment_post_type).

  • Activation/Deactivation hooks (cs_activate_plugin, cs_deactivate_plugin).

  • Registers main Admin Menu (cs_combined_custom_fields_admin_menu).

  • Registers global AJAX handlers (e.g., cs_save_standard_slots, cs_get_available_slots, cs_save_available_slots).

  • Registers global Admin Post handlers (e.g., standard schedule times, remove past slots, generate slots, list view delete).

  • Registers meta boxes for the 'appointment' CPT (cs_add_appointment_meta_boxes).

  • Contains the primary save logic for appointment meta data from the admin editor (cs_save_appointment_meta_data).

  • Registers Notification Trigger Hooks (save_post_appointment, transition_post_status, user_register).

  • Handles general script/style enqueuing (cs_enqueue_scripts, cs_admin_enqueue_scripts).

  • Loads text domain for translations.

• /includes (Core Functionality): Contains PHP files organized by feature area.

  • admin-*.php: Files related to specific admin screens, settings tabs, or admin-specific logic.

  • frontend-*.php: Helper functions specifically for frontend rendering.

  • Files named after features (e.g., appointments.php, registration.php, notes.php, user-account.php): Handle shortcode registration, display logic, and form processing.

  • manager-*.php: Shortcodes and logic for users with a 'Manager' role.

  • calendar-helper.php: Utility functions related to time slots and scheduling calculations.

  • image-map-field.php: (Review status needed).

  • notifications.php: Contains the core notification sending logic (cs_send_notification, cs_send_sms), placeholder processing, and helper functions to get recipient data. Requires SMS SDK (e.g., Twilio) if SMS is enabled.

  • admin-notifications.php: Defines the "Notifications" admin settings tab UI, registers settings (using Settings API) for email/SMS providers, credentials, templates, and event toggles.

• /assets (Static Files):

  • /css: Stylesheets for frontend, admin, calendar, image map.

  • /js: JavaScript files for frontend and admin interactions.

  • (No new dedicated JS/CSS specifically for basic notification settings UI, relies on core WP/admin styles and potential shared admin JS).

• /languages (Translation Files): Contains .pot, .po, and .mo files for internationalization.

• /vendor (Optional - If using Composer): Contains third-party libraries like the Twilio SDK.

  • autoload.php

3. Core Concepts

• Appointment Custom Post Type (CPT): (Description unchanged)

• Admin Settings Area (Client Sync Menu):

  • Registered in client-sync.php.

  • Uses a tabbed interface rendered by cs_combined_custom_fields_admin_page.

  • Tabs include: Appointment Calendar, Client List, Client Custom Fields, Appointment Custom Fields, Manage Time Slots, Standard Day Schedule, Notifications.

  • Each tab calls a specific content function (e.g., cs_notifications_settings_page from admin-notifications.php).

• Custom Fields System: (Description largely unchanged, but note cs_client_phone implication)

  • User Field Data: Stored in wp_usermeta. Includes the standard cs_client_phone meta key for storing client phone numbers for SMS notifications.

• Scheduling Logic: (Description unchanged)

• Notification System: (NEW Concept)

  • Purpose: Provides automated Email and SMS notifications for various plugin events.

  • Central Function: cs_send_notification($event_type, $object_id, $data) in includes/notifications.php.

  • Event Types: Predefined keys (e.g., new_appointment_client, appointment_cancelled_admin, new_client_registration) trigger specific notifications.

  • Settings: Managed via the "Notifications" tab. Includes:

    • General Email: From Name/Address, Admin Recipients.

    • General SMS: Provider selection (e.g., Twilio, None), API Credentials (SID, Token, From Number), Admin SMS Recipients.

    • Per-Event: Enable/disable toggles for Admin/Client Email and Admin/Client SMS; Customizable Subject (Email only) and Body templates (Email & SMS).

  • Placeholders: Templates use placeholders (e.g., {client_first_name}, {appointment_date_formatted}, {client_phone}) dynamically replaced with event data via cs_process_placeholders().

  • Email Delivery: Uses standard wp_mail(). Headers configurable via settings.

  • SMS Delivery: Requires configuration of a third-party gateway (e.g., Twilio). Uses cs_send_sms() which calls the respective provider's SDK (requires SDK installation, e.g., via Composer). Requires client phone numbers in cs_client_phone user meta (E.164 format recommended).

4. Key Workflows

• Adding an Appointment Field: (Unchanged)

• Defining Availability: (Unchanged)

• Client Booking Appointment: Client submits form -> Appointment CPT created -> cs_send_notification('new_appointment_client', $appt_id) called (triggers Email/SMS based on settings).

• Admin Edits Appointment: Admin saves Appointment CPT -> save_post_appointment hook triggers cs_save_appointment_meta_data -> cs_handle_appointment_save_notifications called -> cs_send_notification('appointment_updated_admin', $post_id) called (triggers Email/SMS based on settings).

• Admin Cancels Appointment: Admin trashes Appointment CPT -> transition_post_status hook triggers cs_handle_appointment_status_change_notifications -> cs_send_notification('appointment_cancelled_admin', $post_id) called (triggers Email/SMS based on settings).

• Client Registers: Client submits registration form -> User created -> user_register hook triggers cs_handle_new_user_notifications -> cs_send_notification('new_client_registration', $user_id) called (triggers Email/SMS based on settings).

• Admin Configures Notifications: Admin Nav -> Client Sync -> Calendar & Settings -> Notifications Tab -> Configure provider, credentials, recipient lists, enable/disable events, customize templates -> Save Settings.

5. Frontend Display (Shortcodes)

• (List of shortcodes unchanged, but their actions might now trigger notifications).

• [cs_registration] and [cs_user_account] should ideally include the cs_client_phone field for SMS capability.

6. Data Storage Summary

• Options (wp_options):

  • Plugin settings (calendar display times, schedule templates, custom field definitions, available time slots).

  • cs_notification_settings: Array storing per-event notification settings (email/SMS enabled flags, subject/body templates).

  • cs_sms_settings: Array storing global SMS gateway settings (provider choice, API keys like Twilio SID/Token/From Number).

  • cs_email_from_name, cs_email_from_address: Global sender info for emails.

  • cs_notification_admin_recipients: Comma-separated admin email addresses.

  • cs_sms_admin_recipients: Comma-separated admin phone numbers (E.164).

  • cs_client_list_custom_field_column, cs_appt_list_cf_columns (display settings).

• Post Meta (wp_postmeta): (Unchanged - Appointment data)

• User Meta (wp_usermeta):

  • Custom user/client field values.

  • cs_client_phone: Stores client's phone number (ideally E.164) for SMS.

• Posts (wp_posts): (Unchanged - Appointment CPT entries)

7. AJAX Handlers (Defined in client-sync.php)

• (List unchanged - notifications are primarily triggered via WP action hooks, not direct AJAX calls).

8. Assets (CSS/JS)

• Enqueuing: Handled conditionally in cs_enqueue_scripts and cs_admin_enqueue_scripts.

• Key JS/CSS files: (List largely unchanged).

• Admin Notification Tab: Uses core WP styles, wp_editor assets (enqueued conditionally if WP Editor is used for templates), and potentially minimal inline JS for field dependency (like showing Twilio fields only when Twilio is selected).

9. Hooks & Filters

• Uses various action and filter hooks (init, admin_menu, save_post_*, profile_update, wp_ajax_*, add_shortcode, wp_enqueue_scripts, admin_enqueue_scripts).

• Key Notification Hooks (Actions):

  • save_post_appointment (priority 20, handler: cs_handle_appointment_save_notifications)

  • transition_post_status (handler: cs_handle_appointment_status_change_notifications)

  • user_register (handler: cs_handle_new_user_notifications)

• Key Notification Hooks (Filters - used internally):

  • cs_notification_placeholder_data

  • cs_notification_email_headers

  • cs_send_sms_result

  • cs_notification_event_types

• Existing custom filters (e.g., cs_client_selection_roles).

10. Future Development Considerations

• WooCommerce Integration: Plan and implement integration for paid appointments, leveraging WooCommerce products, cart, and checkout.

• Refine Manager role implementation and capabilities.

• Refine frontend shortcodes (manager ones, passing IDs).

• Enhance SMS: Add support for more gateways, improve E.164 validation/formatting, consider opt-in/out mechanisms for clients.

• Appointment Reminders: Implement WP-Cron based reminder system using the notification framework.

• Consider performance implications of get_users() / get_posts().

• Add unit/integration tests.

• Ensure all user-facing strings (including notification settings and default templates) are translatable.

This updated outline provides a comprehensive overview including the newly added notification layer.