Client Sync - Version: 1.5 Developer Documentation Outline Print

Client Sync Plugin - Developer Documentation Outline

Version: 1.5 (Draft - Reflecting WooCommerce Integration & Admin UI Restructure)
Date: October 26, 2023

(Note: This outline is based on the information provided and recent changes. It should be verified against the actual codebase for accuracy and completeness.)*

1. Overview & Purpose

• 1.1. Mission: Client Sync is a WordPress plugin designed to provide a comprehensive scheduling and client management system, optionally integrated with WooCommerce for payments. It caters to Administrators, potential Managers, and Clients across various business types.

• 1.2. Core Features:

  • Client Registration (WP Users) with Custom Fields.

  • Appointment Scheduling based on predefined availability (Standard Schedule Template + Manual Management).

  • Appointment Management (CPT, Admin/Manager Views, Frontend Views).

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

  • Appointment Notes (via Post Content).

  • Manager roles/views (via manager-*.php files and capability checks).

  • Visual Calendar Interfaces (Admin, Manager, Frontend).

  • Payment Integration:

    • WooCommerce Integration (Primary): Leverages WC products, cart, checkout, payment gateways (including tokenization for direct charge/pay-on-day via compatible gateways like WC Payments).

    • (Basic payments.php likely deprecated or for non-WC flows if any).

  • Email Notifications: Customizable templates for various events.

  • SMS Notifications (Optional): Requires third-party gateway setup (e.g., Twilio).

  • Cron-based Automation: For automatic slot generation and scheduled payment processing (Pay on Day).

  • Configurable Frontend Calendar Styling (Time Range).

• 1.3. Target Audience: WordPress developers, theme developers, site builders needing to customize, extend, or integrate with the Client Sync plugin.

2. Plugin Structure (File Organization)

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

  • Plugin header, constants (cs_PLUGIN_DIR, cs_PLUGIN_URL, cs_VERSION, WC option constants).

  • Includes/requires core functionality files from /includes.

  • Registers appointment Custom Post Type (cs_register_appointment_post_type).

  • Registers Custom Post Statuses (cs_register_custom_post_statuses, e.g., cs_pending_payment).

  • Activation/Deactivation hooks (cs_activate_plugin, cs_deactivate_plugin).

  • Registers Admin Menus (cs_combined_custom_fields_admin_menu):

    • Top-level "Client Sync".

    • Submenu "Calendar & Settings" (main tabbed page).

    • Submenu "Custom Fields" (new dedicated page).

    • Submenu "Add New Appointment".

    • Submenu "Available Slots List".

    • Submenu "Automation".

    • Submenu "Payments".

  • Registers global AJAX handlers (e.g., save standard slots, get available slots, save available slots).

  • Registers admin_post handlers (e.g., save standard schedule times, save calendar times, remove past slots, generate slots, custom field saves).

  • Registers meta boxes for appointment CPT (cs_add_appointment_meta_boxes).

  • Primary CPT save logic (cs_save_appointment_meta_data).

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

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

  • Loads text domain.

  • Includes wc-integration.php conditionally if WooCommerce is active.

  • pre_get_posts hook modification (cs_include_custom_statuses_in_all_view).

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

  • admin-*.php: Admin screen content/logic (e.g., admin-appointment-calendar.php, admin-manage-time-slots.php).

  • frontend-*.php: Frontend rendering helpers (e.g., frontend-custom-fields.php).

  • Feature Files: appointments.php, registration.php, notes.php, user-account.php, etc. (Shortcodes, form processing).

  • manager-*.php: Shortcodes/logic for Manager views.

  • calendar-helper.php: Shared calendar data prep (cs_get_calendar_data) and settings form rendering.

  • notifications.php, admin-notifications.php: Notification system core and admin UI.

  • cron.php, admin-automation.php: Cron jobs and automation settings UI.

  • payments.php: WooCommerce integration settings UI.

  • wc-integration.php: WooCommerce hook handlers (order status sync, etc.).

  • admin-custom-field-handlers.php: Saving/processing logic for custom field definitions.

  • image-map-field.php: (Currently potential helpers, main logic integrated elsewhere).

• 2.3. /assets (Static Files):

  • /css: Stylesheets (admin, frontend, calendar, image marker).

  • /js: JavaScript files (admin interactions, frontend calendar, custom fields UI, image marker).

• 2.4. /languages: Translation files (.pot, .po, .mo).

• 2.5. /vendor (Optional): Third-party libraries (e.g., SMS SDK via Composer).

3. Core Concepts

• 3.1. Appointment Custom Post Type (CPT): appointment post type stores individual bookings. Includes standard fields (title, content for notes, author for client) and custom meta.

• 3.2. Custom Post Statuses: Extends WP statuses (e.g., cs_pending_payment, cs_paid_on_day, cs_failed_on_day, confirmed) to track appointment lifecycle, especially with payments.

• 3.3. Admin Settings Areas:

  • Client Sync -> Calendar & Settings: (client-sync slug) Main tabbed interface.

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

  • Client Sync -> Custom Fields: (cs-custom-fields slug) New dedicated page with internal tabs.

    • Tabs: Client Custom Fields, Appointment Custom Fields.

  • Client Sync -> Available Slots List: (cs-available-slots-list slug) WP_List_Table view.

  • Client Sync -> Automation: (cs-automation slug) Settings for cron jobs.

  • Client Sync -> Payments: (cs-payments slug) WooCommerce integration settings.

• 3.4. Custom Fields System: Definitions stored in options (cs_custom_fields, cs_appointment_custom_fields). Data stored in wp_usermeta (for users) or wp_postmeta (for appointments). Rendered via frontend-custom-fields.php helper.

• 3.5. Scheduling Logic:

  • Available slots stored in cs_available_time_slots option.

  • Standard Day Schedule template (cs_standard_day_schedule option) used for generation.

  • Manual addition/deletion via Manage Time Slots calendar/list.

  • Automatic generation via Cron (cs_cron_auto_generate_slots).

• 3.6. Notification System: Email notifications triggered by hooks. Configurable templates and recipients via Notifications tab. (SMS optional).

• 3.7. WooCommerce Integration:

  • Enabled via CS_OPTION_WC_INTEGRATION_ENABLED.

  • Links appointments to a specific WC Product ID (CS_OPTION_WC_APPOINTMENT_PRODUCT_ID).

  • Frontend booking flow redirects to checkout or attempts direct charge/schedules pay-on-day via saved tokens (requires compatible gateway like WC Payments).

  • Uses WC hooks (woocommerce_order_status_changed) to update appointment status (confirmed, cs_paid_on_day) based on order payment.

  • Stores WC Order ID/Link in appointment meta (_cs_wc_order_id, _cs_wc_order_link).

• 3.8. Cron System:

  • Auto Slot Generation: Hook CS_CRON_HOOK_AUTO_GENERATE. Uses Standard Day Schedule.

  • Pay on Day Charge: Hook CS_CRON_HOOK_PAY_ON_DAY. Processes appointments marked pending_on_day, attempts charge via saved token, updates status (cs_paid_on_day, cs_failed_on_day).

• 3.9. Frontend Styling:

  • Basic CSS (style.css, cs-calendar.css).

  • Configurable frontend calendar time range via Style tab (cs_frontend_calendar_start_time, cs_frontend_calendar_end_time options).

4. Key Workflows

• 4.1. Adding Custom Fields: Admin -> Custom Fields -> Select Client/Appointment Tab -> Define field -> Save. (Handled by cs_handle_save_*_custom_fields).

• 4.2. Defining Availability:

  • Template: Admin -> Calendar & Settings -> Standard Day Schedule -> Edit visually -> Save (AJAX cs_save_standard_slots).

  • Manual: Admin -> Calendar & Settings -> Manage Time Slots -> Edit visually -> Save (AJAX cs_save_available_slots).

  • Generation: Admin -> Calendar & Settings -> Manage Time Slots -> Generate form OR Admin -> Automation -> Regenerate / Auto-Cron.

• 4.3. Client Booking ([cs_appointment]):

  • Client selects available slot on FullCalendar.

  • JS populates hidden form fields (date, slot ID, duration).

  • Client fills custom fields.

  • If Payment Required:

    • Client selects payment option (Direct Charge Token / Pay on Day Token / Checkout).

    • Form Submit -> cs_appointment_form_shortcode handler (in appointments.php).

    • Validation & Slot Check.

    • Create provisional appointment post (status cs_pending_payment).

    • If Direct Charge: Attempt payment via WC_Payment_Gateway->process_payment. Update status (confirmed or failed) & redirect.

    • If Pay on Day: Update status (confirmed), save payment meta (pending_on_day, token ID, due date). Redirect.

    • If Checkout: Add product to WC cart, redirect to wc_get_checkout_url(). (Status updated later via WC hook).

  • If Free:

    • Form Submit -> cs_appointment_form_shortcode handler.

    • Validation & Slot Check.

    • Create appointment post (status confirmed).

    • Redirect.

  • Notifications triggered based on outcome (new_appointment_client, payment_successful_client, etc.).

• 4.4. Admin Edits Appointment: Admin opens Appt CPT editor -> Modifies details/time/client -> Save -> cs_save_appointment_meta_data runs -> cs_handle_appointment_save_notifications triggers appointment_updated_admin.

• 4.5. Admin Cancels Appointment: Admin trashes Appt CPT -> transition_post_status hook -> cs_handle_appointment_status_change_notifications triggers appointment_cancelled_*.

• 4.6. Client Registration ([cs_registration]): Client submits form -> cs_registration_form_shortcode handler -> wp_insert_user -> Custom meta saved -> user_register hook -> cs_handle_new_user_notifications triggers new_client_registration.

• 4.7. Pay-on-Day Cron (cs_execute_charge_due_payments): Runs daily -> Queries 'confirmed' appointments due today with 'pending_on_day' status -> Creates WC Order -> Attempts process_payment with saved token -> Updates appointment status (cs_paid_on_day / cs_failed_on_day) and meta -> Triggers notifications.

• 4.8. Auto-Generation Cron (cs_execute_auto_generate_slots): Runs daily -> Checks lookahead period -> Generates missing slots based on Standard Day Schedule template -> Updates cs_available_time_slots option.

5. Frontend Display (Shortcodes)

• [cs_appointment]: Main booking calendar and form.

• [cs_registration]: User registration form with custom fields.

• [cs_user_account]: Allows logged-in users to update profile info and custom fields.

• [cs_view_notes]: Displays a list of the current user's appointments with links to details.

• [cs_appointment_detail]: Displays details of a single appointment (expects view_id query param).

• [cs_calendar]: Manager/Admin view of the full appointment calendar.

• [cs_manager_appointments]: Manager/Admin list view of all appointments.

• [cs_manager_edit_appointment]: (Potentially outdated) Form to edit details. Recommend using WP Admin instead.

• [cs_manager_edit_notes]: (Potentially outdated) Form to edit notes. Recommend using WP Admin instead.

• [cs_display_user_info]: Basic display of logged-in user info.

• [cs_display_user_name]: Basic display of logged-in user name.

6. Data Storage Summary

• wp_options:

  • cs_custom_fields, cs_custom_fields_order: Client custom field definitions & order.

  • cs_appointment_custom_fields, cs_appointment_custom_fields_order: Appointment custom field definitions & order.

  • cs_available_time_slots: Array of available {date, start_time, end_time} slots.

  • cs_standard_day_schedule: Array defining template {workday_start, workday_end, break_start, break_end, slots:[{start, end}]}.

  • cs_notification_settings: Array storing per-event notification settings (enabled flags, templates).

  • cs_email_from_name, cs_email_from_address, cs_notification_admin_recipients: General email settings.

  • cs_wc_integration_enabled, cs_wc_appointment_product_id: WooCommerce settings.

  • cs_frontend_calendar_start_time, cs_frontend_calendar_end_time: Frontend calendar view range.

  • cs_auto_generate_enabled, cs_auto_generate_lookahead_days: Automation settings.

  • cs_calendar_start_time, cs_calendar_end_time: Admin calendar view range.

  • cs_standard_schedule_calendar_start_time, cs_standard_schedule_calendar_end_time: Standard Schedule Editor view range.

  • (List table column display settings).

• wp_postmeta (for appointment CPT):

  • cs_appointment_date (YYYY-MM-DD).

  • cs_time_slot (YYYY-MM-DDTHH:MM - Unique identifier).

  • cs_appointment_duration (Minutes).

  • Appointment custom field values (meta keys match definition keys).

  • _cs_wc_order_id: Linked WooCommerce order ID.

  • _cs_wc_order_link: Direct link to WC order edit screen.

  • _cs_payment_status: Tracks payment state (e.g., pending_on_day, paid_via_checkout, paid_on_day, failed_on_day, failed_token_invalid, failed_exception).

  • _cs_payment_due_date: Date payment is expected (for pay-on-day).

  • _cs_payment_method_token_id: WC Payment Token ID used/to be used.

  • _cs_payment_attempt_log: Log entries for payment attempts.

• wp_usermeta:

  • Client custom field values (meta keys match definition keys).

  • Standard WP user fields (first_name, last_name, etc.).

• wp_posts:

  • appointment CPT entries (includes post_content for notes, post_author for client link, post_status for standard and custom statuses).

• WooCommerce Tables:

  • Orders (wp_posts where post_type='shop_order', wp_wc_order_stats, etc.).

  • Order Items & Meta (wp_woocommerce_order_items, wp_woocommerce_order_itemmeta).

  • Payment Tokens (wp_woocommerce_payment_tokens, wp_woocommerce_payment_tokenmeta).

7. AJAX Handlers

• wp_ajax_cs_save_standard_slots: Saves visually edited Standard Day Schedule (Handler: cs_save_standard_slots in client-sync.php).

• wp_ajax_cs_get_available_slots: Fetches available slots for a specific date (for Admin CPT editor). (Handler: cs_ajax_get_available_slots_for_date in client-sync.php).

• wp_ajax_cs_save_available_slots: Saves visually edited available slots from Manage Time Slots calendar. (Handler: cs_ajax_save_available_slots in client-sync.php).

8. Key Hooks & Filters (Extensibility)

• Actions:

  • admin_init: Settings registration (cs_register_*_settings). Form handlers (cs_handle_*_submission). List table delete handler (cs_handle_list_view_delete_actions).

  • admin_menu: cs_combined_custom_fields_admin_menu.

  • admin_post_*: Handlers for non-Settings API forms (cs_handle_*_admin_post, e.g., saving calendar times, regenerating slots, saving custom fields).

  • wp_ajax_*: See Section 7.

  • save_post_appointment: cs_save_appointment_meta_data (priority 10), cs_handle_appointment_save_notifications (priority 20).

  • transition_post_status: cs_handle_appointment_status_change_notifications.

  • user_register: cs_handle_new_user_notifications.

  • add_meta_boxes_appointment: cs_add_appointment_meta_boxes.

  • wp_enqueue_scripts, admin_enqueue_scripts: Asset loading.

  • init: CPT registration (cs_register_appointment_post_type), Status registration (cs_register_custom_post_statuses).

  • plugins_loaded: cs_load_textdomain.

  • Cron Hooks: CS_CRON_HOOK_AUTO_GENERATE, CS_CRON_HOOK_PAY_ON_DAY.

  • WooCommerce Hooks: woocommerce_order_status_changed (cs_handle_wc_order_status_update).

  • User Profile Hooks: show_user_profile, edit_user_profile (cs_display_custom_user_fields_on_profile), personal_options_update, edit_user_profile_update (cs_save_custom_user_fields_on_profile), user_profile_update_errors (cs_validate_custom_user_fields_on_profile).

• Filters:

  • manage_appointment_posts_columns, manage_appointment_posts_custom_column, manage_edit-appointment_sortable_columns: Customize Appt list table.

  • manage_users_columns, manage_users_custom_column, manage_users_sortable_columns: Customize User list table.

  • pre_get_posts: cs_include_custom_statuses_in_all_view, cs_sort_user_list_by_custom_column.

  • cs_notification_placeholder_data, cs_notification_email_headers, cs_notification_event_types: Modify notification behavior.

  • cs_client_selection_roles: Control roles shown in client dropdown.

  • cs_appointment_fields_definitions, cs_user_fields_definitions (and aliases): Access custom field definitions.

  • cs_calendar_helper_booked_statuses, cs_manager_calendar_booked_statuses, cs_appointment_slot_check_statuses: Modify statuses considered 'booked'.

  • cs_can_view_other_client_names: Control visibility of client names on calendars.

  • cs_wc_token_gateway_id: Change the target gateway ID for token operations.

  • set-screen-option: cs_save_slots_screen_option.

9. JavaScript Usage

• Frontend:

  • frontend-appointment-calendar.js: Handles FullCalendar initialization, event clicking, populating form fields, updating button state based on selection and payment options. Relies on csAppointmentData localized object.

  • frontend-image-marker.js: Handles click-to-mark interactions on image map custom fields.

• Admin:

  • cs-calendar-admin.js: Basic admin calendar display (Appointments tab). Relies on csCalendarData.

  • admin-manage-slots-fc.js: Interactive FullCalendar for Manage Time Slots tab (create/edit/delete available slots). Relies on csManageSlotsData. Saves via AJAX (cs_save_available_slots).

  • admin-standard-schedule-fc.js: Interactive FullCalendar for Standard Day Schedule tab. Relies on csStandardScheduleData. Saves via AJAX (cs_save_standard_slots).

  • admin-custom-fields.js: UI interactions for the Custom Fields definition page (toggle fields, edit/cancel buttons, media uploader). Relies on csAdminCustomFieldData.