# MOBILE CALENDAR BOOKING ENGINE - WORDPRESS PLUGIN
# Official WordPress plugin for Mobile Calendar booking engine integration
# Version: 1.0.0
# Release Date: November 11, 2025

================================================================================
PLUGIN STRUCTURE
================================================================================

mobile-calendar-booking-engine/
│
├── mobile-calendar-booking-engine.php   # MAIN PLUGIN FILE
│   ├── Plugin metadata (name, version, author, etc.)
│   ├── Constants definition (MCBE_VERSION, MCBE_PLUGIN_DIR, etc.)
│   ├── Main class Mobile_Calendar_Booking_Engine (Singleton)
│   ├── Activation/deactivation hooks
│   └── Component initialization
│
├── includes/                             # PHP CLASSES
│   ├── class-mcbe-admin.php             # Admin panel
│   │   ├── Settings page rendering
│   │   ├── Step-by-step instructions
│   │   ├── OAuth callback handling
│   │   └── Manual token form
│   │
│   ├── class-mcbe-api.php               # API communication
│   │   ├── authenticate_user() - OAuth
│   │   ├── get_auth_url() - Authorization URL
│   │   └── verify_token() - Token verification
│   │
│   ├── class-mcbe-settings.php          # Settings management
│   │   ├── get_widget_token()
│   │   ├── set_widget_token()
│   │   ├── get_api_url()
│   │   └── is_configured()
│   │
│   ├── class-mcbe-blocks.php            # Gutenberg blocks registration
│   │   ├── register_blocks() - Registers both blocks
│   │   ├── render_button_block() - Button rendering (server-side)
│   │   └── render_searchbar_block() - Search bar rendering (server-side)
│   │
│   ├── class-mcbe-frontend.php          # Frontend assets
│   │   └── enqueue_assets() - Loads CSS/JS
│   │
│   └── elementor-widgets/               # Elementor widget integration
│       ├── booking-button.php           # Booking button widget
│       └── search-bar.php               # Search bar widget
│
├── blocks/                               # GUTENBERG BLOCKS
│   ├── button/                          # Booking button block
│   │   ├── block.js                     # Block JavaScript (React)
│   │   │   ├── InspectorControls - settings
│   │   │   ├── ColorPicker - color selection
│   │   │   ├── RangeControl - border radius
│   │   │   └── Preview - editor preview
│   │   │
│   │   └── editor.css                   # Editor styles
│   │
│   └── searchbar/                       # Search bar block
│       ├── block.js                     # Block JavaScript (React)
│       │   ├── InspectorControls - settings
│       │   ├── ToggleControl - show/hide fields
│       │   ├── SelectControl - layout
│       │   └── Preview - search bar preview
│       │
│       └── editor.css                   # Editor styles
│
├── assets/                               # STATIC ASSETS
│   ├── css/
│   │   ├── admin.css                    # Admin panel styles
│   │   │   ├── .mcbe-admin-wrap
│   │   │   ├── .mcbe-setup-card
│   │   │   ├── .mcbe-steps (numbered steps)
│   │   │   ├── .mcbe-token-display
│   │   │   └── Responsive design
│   │   │
│   │   └── searchbar.css                # Search bar styles
│   │       ├── .mcbe-searchbar-wrapper
│   │       ├── .mcbe-searchbar-horizontal/vertical
│   │       ├── .mcbe-searchbar-field
│   │       ├── Flatpickr custom styles
│   │       └── Media queries
│   │
│   ├── js/
│   │   ├── admin.js                     # Admin panel JavaScript
│   │   │   └── Copy token to clipboard
│   │   │
│   │   └── searchbar.js                 # Search bar JavaScript
│   │       ├── initializeSearchBars()
│   │       ├── initializeDatePickers() - Flatpickr
│   │       └── initializeSubmitButton() - Opens modal
│   │
│   └── vendor/
│       └── flatpickr/                   # Date picker library
│           ├── css/
│           ├── js/
│           └── l10n/                    # 40+ language files
│
├── static/                               # BOOKING ENGINE WIDGET
│   ├── css/
│   │   └── be-widget-v2.css            # Widget styles
│   │       ├── .mc-booking-engine-overlay
│   │       ├── .mc-booking-engine-modal
│   │       ├── .mc-booking-engine-iframe
│   │       ├── .mc-booking-engine-button
│   │       └── Responsive design
│   │
│   └── js/
│       └── be-widget-v2.js             # Widget JavaScript
│           ├── MobileCalendarBookingEngine API
│           ├── init() - Widget initialization
│           ├── buildUrl() - URL building with parameters
│           ├── createModal() - Modal creation
│           └── Auto-init for data-attributes
│
├── languages/                            # TRANSLATIONS
│   └── *.po, *.mo files                 # 40+ language translations
│
├── README.md                             # User documentation
├── readme.txt                            # WordPress.org readme
├── uninstall.php                         # Cleanup on uninstall
└── .gitignore                            # Git ignore rules

================================================================================
PLUGIN FEATURES
================================================================================

1. ADMIN PANEL
   ✓ Step-by-step configuration wizard
   ✓ OAuth connection with Mobile Calendar
   ✓ Manual token entry option
   ✓ Connection status indicator
   ✓ Widget usage instructions
   ✓ Token update/disconnect functionality

2. GUTENBERG BLOCK - BOOKING BUTTON
   ✓ Full visual customization:
     - Button text
     - Background color (ColorPicker)
     - Text color (ColorPicker)
     - Border radius (RangeControl 0-50px)
     - Padding controls
     - Alignment (left/center/right)
   ✓ Optional booking parameters:
     - Room IDs (comma-separated)
     - Number of adults (comma-separated)
     - Number of children (comma-separated)
     - Check-in date (YYYY-MM-DD)
     - Check-out date (YYYY-MM-DD)
     - Language (40+ languages)
   ✓ Live preview in editor
   ✓ Server-side rendering

3. GUTENBERG BLOCK - SEARCH BAR
   ✓ Professional date picker (Flatpickr):
     - Dual-month calendar view
     - 40+ language localizations
     - Default dates (today → tomorrow)
     - Format: dd.mm.yyyy
     - Date validation
   ✓ Guest selection:
     - Adults (1-20)
     - Children (0-20)
     - Optional field visibility
   ✓ Two layout options:
     - Horizontal (inline bar)
     - Vertical (stacked column)
   ✓ Customization:
     - Primary color
     - Button text
     - Language selection
   ✓ Live preview in editor
   ✓ Responsive design

4. ELEMENTOR WIDGETS
   ✓ Booking Button Widget
     - All Gutenberg block features
     - Native Elementor controls
     - Style tab integration
   ✓ Search Bar Widget
     - All Gutenberg block features
     - Native Elementor controls
     - Advanced styling options

5. BOOKING ENGINE MODAL
   ✓ Opens in overlay modal
   ✓ Iframe with full Mobile Calendar system
   ✓ Close button (X)
   ✓ Close via Escape key or backdrop click
   ✓ Smooth open/close animations
   ✓ Loading indicator
   ✓ Responsive on all devices
   ✓ Parameter passing (dates, rooms, guests)

6. SECURITY
   ✓ Input sanitization for all data
   ✓ Nonce verification for forms
   ✓ Capability checks (manage_options)
   ✓ Direct access protection (ABSPATH)
   ✓ index.php files in all directories
   ✓ Secure token storage
   ✓ XSS protection (esc_html, esc_attr, esc_url)

7. COMPATIBILITY
   ✓ WordPress 5.8+
   ✓ PHP 7.4+
   ✓ Gutenberg (Block Editor)
   ✓ Elementor Page Builder
   ✓ Multisite ready
   ✓ WPML compatible
   ✓ All modern browsers
   ✓ Mobile responsive

================================================================================
HOW TO USE THE PLUGIN
================================================================================

STEP 1: INSTALLATION
--------------------
1. Upload folder to /wp-content/plugins/
2. Activate in WordPress admin (Plugins menu)

STEP 2: CONFIGURATION
---------------------
1. Go to: WordPress Admin → Mobile Calendar
2. Option A: Click "Connect with Mobile Calendar" → Log in → Authorize
3. Option B: Enter token manually → Save

STEP 3: ADDING WIDGETS
-----------------------
A) Booking Button:
   1. Edit any page/post
   2. Click + (add block)
   3. Search for "Booking Button"
   4. Customize appearance in sidebar
   5. Publish

B) Search Bar:
   1. Edit any page/post
   2. Click + (add block)
   3. Search for "Search Bar"
   4. Customize in sidebar
   5. Publish

C) Elementor Widgets:
   1. Open page in Elementor
   2. Search for "Mobile Calendar"
   3. Drag widget to page
   4. Configure settings
   5. Publish

STEP 4: TESTING
----------------
1. Open page on frontend
2. Click button/fill search bar
3. Modal with booking system should open
4. Test on mobile devices

================================================================================
API INTEGRATION
================================================================================

PRODUCTION ENDPOINT: https://booking.mobile-calendar.com

1. OAUTH AUTHORIZATION
   GET /api/v1/wordpress/authorize
   Query: redirect_uri, site_url
   → Returns: Authorization page

2. TOKEN EXCHANGE
   POST /api/v1/wordpress/auth
   Body: { code, site_url }
   → Returns: { widget_token }

3. TOKEN VERIFICATION
   GET /api/v1/wordpress/verify
   Header: Authorization: Bearer {token}
   → Returns: 200 OK | 401 Unauthorized

================================================================================
REQUIREMENTS
================================================================================

SERVER:
- PHP 7.4+
- WordPress 5.8+
- MySQL 5.6+ / MariaDB 10.0+

BROWSER:
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

EXTERNAL:
- Mobile Calendar account
- Widget token from Mobile Calendar dashboard
- Internet connection (Flatpickr vendor library)

================================================================================
PRODUCTION CHECKLIST
================================================================================

✓ All sandbox URLs changed to production URLs
✓ API endpoint: https://booking.mobile-calendar.com
✓ OAuth endpoints verified
✓ Token verification endpoint tested
✓ Multi-language support enabled (40+ languages)
✓ Security hardening complete
✓ Performance optimization applied
✓ Documentation updated
✓ Testing completed

================================================================================
DEVELOPER NOTES
================================================================================

DESIGN PATTERNS:
- Singleton for main class and all components
- Server-side rendering for blocks (better SEO, security)
- Hook-based architecture (filters and actions)

PERFORMANCE:
- Conditional asset loading (admin assets only in admin)
- Local Flatpickr vendor (no CDN dependency)
- Lazy loading iframe
- Optimized CSS/JS

EXTENSIBILITY:
- Developer hooks (mcbe_*)
- Filters for customization
- OOP structure - easy to extend

MULTI-LANGUAGE:
- 40+ languages supported
- Automatic WordPress locale detection
- Flatpickr localization included
- Admin panel auto-translation

FUTURE ENHANCEMENTS:
- [ ] Shortcode for Classic Editor
- [ ] Sidebar widget
- [ ] Cache layer
- [ ] Analytics integration
- [ ] WooCommerce integration
- [ ] Custom post types for rooms
- [ ] Multisite enhancements

================================================================================
SUPPORT
================================================================================

Website: https://mobile-calendar.com
Email: info@mobile-calendar.com
Phone: +48 502-300-023
Documentation: https://mobile-calendar.com/docs

================================================================================
LICENSE
================================================================================

GPL v2 or later
https://www.gnu.org/licenses/gpl-2.0.html

================================================================================
END OF DOCUMENTATION
================================================================================
