Client Sync Plugin - Developer Documentation Outline 1.3 Print

Client Sync Plugin - Developer Documentation Outline

Version: 1.3 (Based on provided files)

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.

  • Appointment Scheduling based on predefined availability.

  • Appointment Management (Viewing, Editing).

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

  • Appointment Notes.

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

  • Visual Calendar Interfaces (Admin & Frontend).

  • Payment Integration (Basic - payments.php).

2. Plugin Structure (File Organization)

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

  • Plugin header information.

  • Constants (cs_PLUGIN_DIR, cs_PLUGIN_URL).

  • 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).

  • 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 (like custom columns, meta boxes, calendar views).

  • frontend-*.php: Helper functions specifically for frontend rendering (like frontend-custom-fields.php).

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

  • manager-*.php: Shortcodes and logic specifically for users with a 'Manager' role (or similar capability).

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

  • image-map-field.php: (Potentially redundant if logic is now in frontend-custom-fields.php and admin-appointment-meta-boxes.php, review needed).

• /assets (Static Files):

  • /css: Stylesheets for frontend (style.css), admin (admin-style.css), calendar (cs-calendar.css), and image map (image-marker.css).

  • /js: JavaScript files for frontend interactions (frontend-image-marker.js) and admin interactions (various admin-*.js, cs-calendar-admin.js).

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

3. Core Concepts

• Appointment Custom Post Type (CPT):

  • The central data store for individual appointments.

  • Defined in client-sync.php.

  • publicly_queryable is false - appointments don't have their own frontend pages by default.

  • post_author relationship links the appointment to the Client (User).

  • Core data (Date, Time Slot Identifier, Duration) stored in post meta (cs_appointment_date, cs_time_slot, cs_appointment_duration).

  • Notes are intended to be stored in post_content.

  • Custom field data is stored in post meta using keys defined by the admin.

• Admin Settings Area (Client Sync Menu):

  • Registered in client-sync.php (cs_combined_custom_fields_admin_menu).

  • Uses a tabbed interface rendered by cs_combined_custom_fields_admin_page (client-sync.php).

  • Each tab calls a specific content function located in one of the includes/admin-*.php files (e.g., cs_appointment_calendar_content in admin-appointment-calendar.php).

• Custom Fields System:

  • Two Types: Client (User) Custom Fields and Appointment Custom Fields.

  • Definition Storage: Field definitions (key, label, type, options, etc.) are stored in the wp_options table.

    • User Fields: cs_custom_fields (option name)

    • User Fields Order: cs_custom_fields_order (option name)

    • Appointment Fields: cs_appointment_custom_fields (option name)

    • Appointment Fields Order: cs_appointment_custom_fields_order (option name)

  • Definition UI: Managed via "Client Custom Fields" and "Appointment Custom Fields" tabs in the admin area. Logic in includes/admin-custom-fields.php and includes/admin-appointment-custom-fields.php. Saving/Deleting/Reordering handled by admin-custom-field-handlers.php via admin-post.php actions.

  • Data Storage:

    • User Field Data: Stored in wp_usermeta table using the defined field key.

    • Appointment Field Data: Stored in wp_postmeta table (for the appointment CPT) using the defined field key.

  • Rendering:

    • Admin (Appointment Edit): cs_render_appointment_meta_box_content in includes/admin-appointment-meta-boxes.php.

    • Admin (User Profile): Functions/hooks in includes/admin-custom-fields.php display fields on user profile pages.

    • Frontend: Primarily handled by shortcode functions (appointments.php, registration.php, user-account.php) often using the helper cs_render_frontend_custom_field from includes/frontend-custom-fields.php.

  • Saving:

    • Admin (Appointment Edit): cs_save_appointment_meta_data in client-sync.php.

    • Admin (User Profile): Hooks in includes/admin-custom-fields.php (e.g., profile_update, edit_user_profile_update).

    • Frontend: Form processing logic within the respective shortcode handler functions (e.g., in appointments.php, registration.php, user-account.php).

• Scheduling Logic:

  • Standard Day Schedule: Defines a template for a typical day's availability.

    • UI: "Standard Day Schedule" tab (admin-standard-day-schedule.php). Uses FullCalendar (admin-standard-schedule-fc.js) for visual slot definition.

    • Storage: cs_standard_day_schedule option (stores start/end times, duration, breaks, and visually defined slots array).

    • Saving: cs_save_standard_slots AJAX handler (client-sync.php).

  • Available Time Slots: Defines specific, individual date/time slots that can be booked. This is the primary source for the frontend calendar.

    • UI: "Manage Time Slots" tab (admin-manage-time-slots.php). Uses FullCalendar (admin-manage-slots-fc.js) and date range generation form. Includes interaction JS (admin-manage-time-slots-interactions.js). Also listed in "Available Slots List" (admin-available-slots-list.php).

    • Storage: cs_available_time_slots option (stores an array of ['date' => 'Y-m-d', 'start_time' => 'H:i', 'end_time' => 'H:i']).

    • Saving/Updating:

      • Manual Add/Drag (Calendar): cs_ajax_save_available_slots AJAX handler (client-sync.php).

      • Generation: cs_handle_generate_slots_submission admin post handler (client-sync.php).

      • Deletion (List): cs_handle_list_view_delete_actions admin post handler (client-sync.php).

      • Deletion (Past): cs_handle_remove_past_slots_submission admin post handler (client-sync.php).

  • Booking:

    • Frontend calendar (appointments.php shortcode [cs_appointment]) displays events based on cs_available_time_slots.

    • Booked slots (existing appointment posts) are queried to mark slots as unavailable.

    • Form submission creates a new appointment post and saves relevant meta (time slot identifier, custom fields).

4. Key Workflows

• Adding an Appointment Field: Admin Nav -> Client Sync -> Appointment Custom Fields -> Define Field -> Save. (Handled by admin-appointment-custom-fields.php UI + admin-custom-field-handlers.php saving).

• Defining Availability: Admin Nav -> Client Sync -> Manage Time Slots -> Use calendar/generator -> Save Slots. (Handled by admin-manage-time-slots.php UI + cs_ajax_save_available_slots / cs_handle_generate_slots_submission).

• Client Booking Appointment: Client visits page with [cs_appointment] -> Selects slot on calendar -> Fills form -> Submits. (Handled by appointments.php shortcode function, including validation, CPT creation, meta saving).

• Admin Edits Appointment: Admin Nav -> Appointments -> Edit Appointment -> Modifies client/time slot/custom fields -> Update. (Handled by WP Post Editor + Meta Boxes from admin-appointment-meta-boxes.php + Saving logic in cs_save_appointment_meta_data).

5. Frontend Display (Shortcodes)

• [cs_appointment]: Main booking calendar and form (includes/appointments.php).

• [cs_registration]: User registration form with custom fields (includes/registration.php).

• [cs_user_account]: Allows users to view/edit their profile and custom fields (includes/user-account.php).

• [cs_view_notes]: Displays notes for the logged-in user's appointments (includes/notes.php).

• [cs_appointment_detail]: Displays details of a specific appointment (includes/appointment-detail.php). Needs review: How is the appointment ID passed?

• [cs_manager_appointments]: Lists appointments for managers (includes/manager-appointments.php).

• [cs_manager_calendar]: Calendar view for managers (includes/manager-calendar.php).

• [cs_manager_edit_notes]: Allows managers to edit appointment notes (includes/manager-edit-notes.php). Needs review: How is the target appointment selected?

• [cs_manager_edit_appointment]: Allows managers to edit appointment custom fields (includes/manager-edit-appointment.php). Needs review: How is the target appointment selected?

• [cs_user_info], [cs_user_email], etc.: Simple display shortcodes (includes/user-display.php).

6. Data Storage Summary

• Options (wp_options):

  • Plugin settings (calendar display times, schedule templates, custom field definitions, available time slots). cs_calendar_start_time, cs_standard_day_schedule, cs_available_time_slots, cs_custom_fields, cs_appointment_custom_fields, etc.

• Post Meta (wp_postmeta): Linked to appointment CPT posts.

  • cs_appointment_date, cs_time_slot, cs_appointment_duration.

  • Custom appointment field values (using the defined field key).

• User Meta (wp_usermeta): Linked to User IDs.

  • Custom user/client field values (using the defined field key).

• Posts (wp_posts): Stores appointment CPT entries. post_author links to client User ID. post_content stores notes. post_title is auto-generated.

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

• wp_ajax_cs_save_standard_slots: Saves visually defined slots from the Standard Day Schedule tab.

• wp_ajax_cs_get_available_slots: Fetches available slots for a specific date (used by Admin appointment editor).

• wp_ajax_cs_save_available_slots: Saves available slots added/edited via the Manage Time Slots calendar UI.

8. Assets (CSS/JS)

• Enqueuing: Handled conditionally in cs_enqueue_scripts (frontend) and cs_admin_enqueue_scripts (admin) within client-sync.php. Logic checks for specific shortcodes or admin pages/tabs.

• Key JS Files:

  • frontend-image-marker.js: Handles image map interaction on forms.

  • admin-custom-fields.js: Handles UI interactions on the custom field definition screens (edit/cancel, conditional fields, media uploader).

  • cs-calendar-admin.js: JS for the main admin appointment calendar view.

  • admin-standard-schedule-fc.js: JS for the visual Standard Day editor.

  • admin-manage-slots-fc.js: JS for the Manage Time Slots calendar UI.

  • admin-manage-time-slots-interactions.js: JS for the date range generation form on the Manage Time Slots tab.

  • admin-appointment-slot-selector.js: JS for the date/slot selector meta box in the appointment editor.

• Key CSS Files: Styles for admin, frontend, calendar, and image map components.

9. Hooks & Filters

• The plugin uses various action and filter hooks (add_action, add_filter).

• Key examples: init (register CPT), admin_menu, save_post_appointment, profile_update, wp_ajax_*, shortcode hooks (add_shortcode), wp_enqueue_scripts, admin_enqueue_scripts.

• Custom filters exist (e.g., cs_client_selection_roles).

• Developers should search the codebase for add_action, add_filter, do_action, apply_filters to understand extensibility points.

10. Future Development Considerations

• Review Manager role implementation and capabilities.

• Refine frontend shortcodes (especially manager ones) for selecting target appointments/users if not already robust.

• Enhance payment integration beyond basic framework.

• Consider performance implications of get_users() and get_posts() calls, especially on sites with many users/appointments. Implement caching or AJAX lookups where appropriate.

• Add unit/integration tests.

• Ensure all user-facing strings are translatable using the client-sync text domain.

This document provides a solid foundation for understanding how Client Sync is put together. When expanding the plugin, refer back to this structure to see where new functionality might fit or what existing components need modification.