Client Sync Plugin Structure Overview

The Client Sync plugin manages clients, appointments, payments, and related data within WordPress. It utilizes custom post types, custom taxonomies (if implemented), custom fields (user and post meta), and various WordPress APIs (Settings API, AJAX, Cron, WP_List_Table, WooCommerce).

Core Components:

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

   • Acts as the central entry point.

   • Defines core plugin constants (CS_PLUGIN_DIR, CS_PLUGIN_URL, CS_VERSION, options, meta keys).

   • Registers the appointment Custom Post Type (cs_register_appointment_post_type).

   • Registers custom Post Statuses for appointments (cs_register_custom_post_statuses).

   • Handles plugin activation (cs_activate_plugin) and deactivation (cs_deactivate_plugin) hooks (managing defaults, flushing rewrites, scheduling/unscheduling cron).

   • Includes all other functional files from the includes/ directory.

   • Sets up the main WordPress admin menu and tabbed settings pages (cs_combined_custom_fields_admin_menu).

   • Registers all plugin settings options using the Settings API (cs_register_plugin_settings).

   • Contains callback functions for rendering content on the main admin tabs that use the Settings API (cs_style_settings_page_content).

   • Includes core AJAX handlers (cs_ajax_get_calendar_events, cs_ajax_get_available_slots_for_date, cs_ajax_save_available_slots).

   • Includes core admin-post handlers (cs_handle_standard_schedule_times_admin_post, cs_handle_remove_past_slots_submission, cs_handle_list_view_delete_actions, cs_handle_generate_slots_submission).

   • Hooks the save_post_appointment action (cs_save_appointment_meta_data) to handle saving core and custom meta data from the admin edit screen.

   • Hooks pre_get_posts (cs_include_custom_statuses_in_all_view) to modify the Appointments list table query.

   • Hooks wp_enqueue_scripts and admin_enqueue_scripts to load necessary CSS/JS, including conditionally loading FullCalendar and other libraries (often from CDN).

   • Localizes data for frontend and admin JavaScripts (wp_localize_script).

2. includes/ Directory: Contains modular files grouped by functionality.

Key Functional Areas:

1. Appointments (Core):

   • Data Model: appointment CPT (post author is the client), Post Meta (cs_appointment_date, cs_time_slot, cs_appointment_duration, custom field keys).

   • Frontend Booking ([cs_appointment]):

     • appointments.php: Renders the HTML structure (filter dropdowns, calendar div, form fields). Displays messages from transients. Localizes booking-specific data for JS.

     • appointment-handlers.php: Handles the template_redirect hook to intercept POST submissions from the frontend form. Performs validation, slot availability check, orchestrates payment flow (direct charge, Pay on Day, checkout redirect, or free booking), creates/updates the appointment post, saves meta via cs_save_appointment_meta_helper, triggers notifications.

     • frontend-appointment-calendar.js: Frontend JavaScript. Initializes FullCalendar. If availability dimensions are configured, it manages filter dropdown changes. Fetches calendar events via AJAX (wp_ajax_cs_get_calendar_events) sending selected filters. Updates the calendar display, highlights selected slots, populates hidden form fields, and manages the submit button state based on slot and payment selection.

   • Admin Management:

     • admin-appointment-columns.php: Adds/modifies columns on the Appointments list table.

     • admin-appointment-meta-boxes.php: Defines and renders meta boxes on the Appointment edit screen (Client selection, Time Slot selection, Custom Fields display).

     • admin-appointment-calendar.php: Renders the content for the "Appointment Calendar" tab in the admin (uses calendar-helper.php for data, cs-calendar-admin.js for display logic).

     • admin-appointment-slot-selector.js: JavaScript for the Time Slot meta box on the admin edit screen. Populates the slot select dropdown based on the chosen date using AJAX (wp_ajax_cs_get_available_slots).

   • Frontend Display:

     • appointment-detail.php: Handles the [cs_appointment_detail] shortcode to display details of a single appointment (reads view_id from URL, fetches post and meta).

2. Time Slots (Availability):

   • Data Model: Stored as an array in the cs_available_time_slots option. Each slot entry includes date, start_time, end_time, and optionally dimensions (key-value pairs from selected filtering fields).

   • Management UI:

     • admin-manage-time-slots.php: Renders the content for the "Manage Time Slots" tab. Includes an interactive calendar editor (using admin-manage-slots-fc.js), a bulk generation form, and a list table link. Uses calendar-helper.php for calendar data. Displays messages from transients.

     • admin-standard-day-schedule.php: Renders the content for the "Standard Day Schedule" tab. Defines the visual template for a typical day's slots (stored in cs_standard_day_schedule option). Uses admin-standard-schedule-fc.js for the visual editor.

     • admin-available-slots-list.php: Defines and renders the CS_Available_Slots_List_Table (a custom WP_List_Table) for managing available slots in a list format. Handles sorting and passes delete actions to client-sync.php handlers.

   • Logic:

     • client-sync.php: Contains cs_calculate_slots helper, and admin-post handlers for generating/removing/deleting slots (cs_handle_generate_slots_submission, cs_handle_remove_past_slots_submission, cs_handle_list_view_delete_actions).

     • admin-manage-slots-fc.js: JavaScript for the interactive calendar on the "Manage Time Slots" tab. Allows creating, dragging, resizing, and deleting available slots visually. Saves changes via AJAX (wp_ajax_cs_save_available_slots). Shows booked slots for reference.

     • admin-standard-schedule-fc.js: JavaScript for the visual editor on the "Standard Day Schedule" tab. Allows creating, dragging, resizing slots as a template. Saves changes via AJAX (wp_ajax_cs_save_standard_slots).

     • admin-manage-time-slots-interactions.js: General JavaScript for non-calendar interactions on the "Manage Time Slots" tab (toggling alternative forms, etc.).

3. Custom Fields:

   • Data Model: Definitions stored in cs_custom_fields (users) and cs_appointment_custom_fields (appointments) options (array of fields with keys like label, type, options, required, html_content, image_id, layout). Order stored in cs_custom_fields_order and cs_appointment_custom_fields_order options. Values stored as user meta or post meta.

   • Admin Management:

     • client-sync.php: Sets up the "Custom Fields" submenu page (cs_custom_fields_admin_page).

     • admin-custom-fields.php: Renders the UI for managing client custom fields.

     • admin-appointment-custom-fields.php: Renders the UI for managing appointment custom fields.

     • admin-custom-field-handlers.php: Handles saving/updating/deleting/ordering custom field definitions (admin-post.php handlers). Displays notices.

     • admin-custom-fields.js: JavaScript for the Custom Fields definition UI (toggling conditional fields, edit/cancel form state, media uploader for image map).

   • Frontend/Admin Use:

     • frontend-custom-fields.php: Helper function (cs_render_frontend_custom_field) to render custom field inputs/displays on frontend forms ([cs_registration], [cs_user_account], [cs_appointment]).

     • client-sync.php: cs_save_appointment_meta_data saves appointment custom field values from the admin edit screen.

     • appointment-helpers.php: cs_sanitize_custom_field_value and cs_save_appointment_meta_helper handle sanitizing and saving custom field values from frontend submissions.

     • registration.php: Handles saving client custom field values during registration.

     • user-account.php: Handles saving client custom field values from the account update form.

     • admin-user-columns.php: Displays client custom field values as columns on the Users list table.

     • admin-appointment-columns.php: Displays client custom field values as columns on the Appointments list table.

     • image-map-field.php: Placeholder for image map specific helpers if needed.

     • frontend-image-marker.js: JavaScript for the interactive image map custom field on frontend forms.

4. Payments (WooCommerce Integration):

   • Data Model: Settings stored in options (cs_wc_integration_enabled, cs_wc_appointment_product_id). Order/Payment meta stored on Appointment post (_cs_wc_order_id, _cs_payment_status, etc.). Order data stored in WooCommerce.

   • Admin Management:

     • payments.php: Renders the content for the "Payments" settings page/tab (uses Settings API).

   • Logic:

     • wc-integration.php: Handles WooCommerce hooks (woocommerce_order_status_changed) to update appointment status/meta when order status changes. Contains logic for processing direct token charges and handling results.

     • cron.php: Handles the scheduled "Pay on Day" cron event (cs_cron_charge_due_payments) which uses WC APIs to create orders and process payments for appointments due on the current day.

     • appointment-handlers.php: Orchestrates the frontend booking payment flow (direct charge via token, redirect to checkout, or schedule Pay on Day) using WooCommerce functions.

     • appointments.php: Displays payment options (saved cards, Pay on Day, Checkout) on the frontend form based on settings and user's saved tokens.

5. Notifications:

   • Data Model: Settings stored in the cs_notification_settings option (nested array per event type and recipient). Email "From" name/address and Admin recipients stored in separate options.

   • Logic:

     • notifications.php: Defines notification event types and their placeholders, default subjects/bodies, and the main cs_send_notification function which handles fetching settings, preparing data, processing placeholders, and sending emails via wp_mail.

     • admin-notifications.php: Renders the content for the "Notifications" settings page/tab (uses Settings API).

     • Various handlers (e.g., appointment-handlers.php, cron.php, wc-integration.php, client-sync.php for status transitions, registration.php for new users) call cs_send_notification to trigger emails.

6. Automation (Cron):

   • Data Model: Settings stored in options (cs_auto_generate_enabled, cs_auto_generate_lookahead). Standard Day Schedule template in cs_standard_day_schedule. Available slots in cs_available_time_slots.

   • Admin Management:

     • admin-automation.php: Renders the content for the "Automation" settings page/tab (uses Settings API). Includes a manual regeneration form (handler in cron.php).

   • Logic:

     • cron.php: Defines cron hooks and callbacks (cs_cron_auto_generate_slots, cs_cron_charge_due_payments). cs_execute_auto_generate_slots generates slots based on the standard template and lookahead setting, updating the cs_available_time_slots option. cs_execute_charge_due_payments handles the Pay on Day charging process. Includes helpers for slot generation/manipulation.

Data Storage:

• Post Type: appointment

• Meta Keys (Appointment): cs_appointment_date, cs_time_slot, cs_appointment_duration, _cs_payment_status, _cs_payment_due_date, _cs_wc_token_id, _cs_wc_order_id, _cs_wc_order_link, _cs_payment_attempt_log, plus keys for custom appointment fields defined by the user.

• Meta Keys (User): Keys for custom client fields defined by the user.

• Options: cs_available_time_slots, cs_standard_day_schedule, cs_custom_fields, cs_custom_fields_order, cs_appointment_custom_fields, cs_appointment_custom_fields_order, cs_calendar_start_time, cs_calendar_end_time, cs_calendar_slot_duration, cs_frontend_calendar_style (includes initial_view), cs_login_page_url, cs_availability_dimensions_fields, cs_auto_generate_enabled, cs_auto_generate_lookahead, cs_notification_settings, cs_email_from_name, cs_email_from_address, cs_notification_admin_recipients, cs_wc_integration_enabled, cs_wc_appointment_product_id.

Key Interaction Points/Hooks:

• init: Register CPTs, statuses, settings.

• admin_menu: Set up admin menus.

• admin_init: Register settings (Settings API), handle admin-post form submissions.

• wp_enqueue_scripts: Enqueue frontend assets.

• admin_enqueue_scripts: Enqueue admin assets.

• wp_ajax_* / wp_ajax_nopriv_*: Handle AJAX requests.

• template_redirect: Intercept frontend form POST submissions.

• save_post_appointment: Save meta data when an appointment is saved (admin edit screen).

• transition_post_status: Trigger notifications on status changes.

• user_register: Trigger new user notifications.

• update_option_*: Trigger actions when specific options are updated (e.g., scheduling cron).

• cs_cron_*: Custom WP Cron events.

• woocommerce_*: WooCommerce specific hooks for integration.

• manage_users_columns, manage_users_custom_column, manage_users_sortable_columns, pre_get_users: Hooks for customizing the Users list table.

• manage_appointment_posts_columns, manage_appointment_posts_custom_column, manage_edit-appointment_sortable_columns, pre_get_posts: Hooks for customizing the Appointment CPT list table.

This overview should provide a solid foundation for understanding the plugin's architecture and identifying where to implement new features or modify existing ones.