booking-package / lib / Documents.php

Documents.php in Booking Package trunk, at lib/Documents.php

476 lines 26.6 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	class booking_package_documents {
8
9	public $prefix = null;
10
11	public $pluginName = null;
12
13	public function __construct($prefix, $pluginName) {
14
15	$this->prefix = $prefix;
16	$this->pluginName = $pluginName;
17
18	}
19
20	public function numberOfAvailableDaysFromToday() {
21
22	$document = <<<EOF
23
24	<div>
25	<h2>Dynamic Override of "Number of Available Days From Today" on Frontend (Filter Hook)</h2>
26	<div>
27	This filter hook dynamically changes how many days in advance a booking can be made on the frontend booking calendar.
28	It is used to shorten (restrict) the default booking acceptance period configured in the admin dashboard based on specific calendars or custom conditions.
29	</div>
30	<strong style="font-size: 1.2em;">Filter Hook Details</strong>
31	<ul><li>Hook Name: <code>booking_package_frontend_available_days_from_today</code></li></ul>
32	<strong style="font-size: 1.2em;">Parameters</strong>
33	<ol>
34	<li><b>\$default_days</b> (int) The default number of available days configured in the "<b>Number of Available Days From Today</b>" within the Setting tab.</li>
35	<li><b>\$calendar_account_id</b> (int) The ID of the target calendar account.</li>
36	</ol>
37	<strong style="font-size: 1.2em;">Return Value</strong>
38	<ol>
39	<li>(int) The modified number of available days. (Must be an integer of 1 or greater)</li>
40	</ol>
41	<strong style="font-size: 1.2em;">Specifications and Important Notes</strong>
42	<ol>
43	<li><b>Return Value Restrictions</b>: The return value from the hook MUST be an integer of 1 or greater, and it MUST be less than the value configured in "<b>Number of Available Days From Today</b>" in the Setting tab.</li>
44	<li>This hook only functions when restricting the booking period to be shorter than the default setting. The override is applied only when the return value meets the conditions mentioned above (1 or greater AND less than the Setting tab value).</li>
45	<li>If a value of <code>0</code> or less is specified, or if a value greater than or equal to the Setting tab value (an extension of the period) is returned, the hook will be ignored, and the default setting will be applied as is.</li>
46	</ol>
47
48	<strong style="font-size: 1.2em;">Usage Example</strong>
49	<div>
50	Assuming the "<b>Number of Available Days From Today</b>" is set to 30 in the Setting tab, this example restricts the booking period to "7 days from today" only for a specific calendar (e.g., Calendar ID <code>5</code>).
51	</div>
52	<br>
53	<textarea class="booking-package-sample-code" style="display:none;">
54	<?php
55	/**
56	* Restrict the booking acceptance period to 7 days for a specific calendar.
57	*/
58
59	function custom_booking_available_days( \$default_days, \$calendar_account_id ) {
60	// Return 7 days only if the Calendar Account ID is 5.
61	// * Note: "Number of Available Days From Today" in the Setting tab must be set to 8 or more for this to work.
62	if ( \$calendar_account_id === 5 ) {
63	// Override the limit time to 90 minutes.
64	return 7;
65	}
66	// Maintain the default setting for all other calendars.
67	return \$default_days;
68	}
69	add_filter( 'booking_package_frontend_available_days_from_today', 'custom_booking_available_days', 10, 2 );
70	?>
71	</textarea>
72
73	</div>
74
75	EOF;
76
77	return $document;
78
79	}
80
81	public function cancellationLimitTime() {
82
83	$document = <<<EOF
84
85	<div>
86	<h2>Dynamic Override of Cancellation Limit Time (Filter Hook)</h2>
87	<div>
88	The cancellation limit time configured in the Calendar Account ("Allow Cancellation Up To") can be dynamically overridden using the <code>booking_package_override_cancellation_limit_time</code> filter hook.
89	<b>Please note that this hook is only executed when the "Allow Customer Cancellations" option is set to "Enabled" within the Calendar Account settings tab.</b>
90	This allows you to set highly specific cancellation deadlines down to the minute.
91	</div>
92	<strong style="font-size: 1.2em;">Filter Hook Details</strong>
93	<ul><li>Hook Name: <code>booking_package_override_cancellation_limit_time</code></li></ul>
94	<strong style="font-size: 1.2em;">Parameters</strong>
95	<ol>
96	<li><b>\$current_cancellation_limit_time</b> (int) (Target for modification) The current cancellation limit time in minutes retrieved from the calendar settings.</li>
97	<li><b>\$calendar_account_id</b> (int) The ID of the calendar account associated with this reminder.</li>
98	</ol>
99	<div>
100	<strong style="font-size: 1.2em;">Important:</strong> The return value <b>must be an integer (<code>int</code>) of <code>1</code> or greater</b>. If <code>0</code> or a non-numeric value is returned, the system will fall back to the original setting configured in the Calendar Account. It represents the number of minutes before the booking time that cancellations are allowed. There are no restrictions on the intervals, allowing you to specify exact times in 1-minute increments. For example:
101	<ul>
102	<li><code>15</code> (15 minutes prior)</li>
103	<li><code>105</code> (1 hour and 45 minutes prior)</li>
104	<li><code>150</code> (2 hour and 30 minutes prior)</li>
105	</ul>
106	</div>
107
108	<strong style="font-size: 1.2em;">Usage Example</strong>
109	<div>This is a sample code that overrides the default cancellation limit time, allowing customers to cancel up to 90 minutes (1.5 hours) before their booking specifically when the Calendar Account ID is <code>5</code>. For all other calendars, it returns <code>0</code> to keep their default settings.</div>
110	<br>
111	<textarea class="booking-package-sample-code" style="display:none;">
112	<?php
113	/** Dynamic Override of Cancellation Limit Time
114	*
115	* @param int \$current_cancellation_limit_time Current time in minutes
116	* @param int \$calendar_account_id Calendar Account ID
117	* @return int Modified time in minutes
118	*/
119
120	function my_custom_cancellation_time( \$current_cancellation_limit_time, \$calendar_account_id ) {
121	// Check if the target is Calendar Account ID 5
122	if ( \$calendar_account_id === 5 ) {
123	// Override the limit time to 90 minutes.
124	return 90;
125	}
126	// Return 0 (or \$current_cancellation_limit_time) to use the original setting
127	return 0;
128	}
129	add_filter( 'booking_package_override_cancellation_limit_time', 'my_custom_cancellation_time', 10, 1 );
130	?>
131	</textarea>
132
133	</div>
134
135	EOF;
136
137	return $document;
138
139	}
140
141	public function reminderNotificationTime() {
142
143	$document = <<<EOF
144
145	<div>
146	<h2>Dynamic Override of Reminder Notification Time (Filter Hook)</h2>
147	<div>The reminder notification time configured in the Calendar Account can be dynamically overridden during the email sending process using the <code>booking_package_override_reminder_notification_time</code> filter hook. This allows you to set custom timing intervals that are not available in the default select box.</div>
148	<strong style="font-size: 1.2em;">Filter Hook Details</strong>
149	<ul><li>Hook Name: <code>booking_package_override_reminder_notification_time</code></li></ul>
150	<strong style="font-size: 1.2em;">Parameters</strong>
151	<ol>
152	<li><b>\$current_reminder_notification_time</b> (int) (Target for modification) The current notification time in minutes retrieved from the calendar settings.</li>
153	<li><b>\$calendar_account_id</b> (int) The ID of the calendar account associated with this reminder.</li>
154	</ol>
155	<div>
156	<strong style="font-size: 1.2em;">Important:</strong> The return value <b>must be an integer (<code>int</code>) of <code>60</code> or greater</b>. It must be specified in minutes and should be provided in 60-minute increments. For example:
157	<ul>
158	<li><code>60</code> (1 hour prior)</li>
159	<li><code>6120</code> (102 hours / 4 days and 6 hours prior)</li>
160	<li><code>10800</code> (180 hours / 7 days and 12 hours prior)</li>
161	</ul>
162	</div>
163
164	<strong style="font-size: 1.2em;">Usage Example</strong>
165	<div>This is a sample code that overrides the default reminder notification time and sets it to be sent 4 days and 6 hours (6120 minutes) before the booking.</div>
166	<br>
167	<textarea class="booking-package-sample-code" style="display:none;">
168	<?php
169	/** Dynamic Override of Reminder Notification Time
170	*
171	* @param int \$current_reminder_notification_time Current time in minutes
172	* @param int \$calendar_account_id Calendar Account ID<br
173	* @return int Modified time in minutes
174	*/
175
176	function my_custom_reminder_time( \$current_reminder_notification_time, \$calendar_account_id ) {
177	if ( \$calendar_account_id === 5 ) {
178	// Override the notification time to 6120 minutes (4 days and 6 hours).
179	// The value must be an integer of 60 or greater.
180	return 6120;
181	}
182	}
183	add_filter( 'booking_package_override_reminder_notification_time', 'my_custom_reminder_time', 10, 1 );
184	?>
185	</textarea>
186
187	</div>
188
189	EOF;
190
191	return $document;
192
193	}
194
195	public function dynamicTextModification() {
196
197	$document = <<<EOF
198
199	<div>
200	<h2>Dynamic Text Translation and Modification (Filter Hook)</h2>
201	<div>The text displayed in the Booking Package plugin can be dynamically modified using the <b><code>booking_package_get_translate_text</code></b> filter hook. Since this hook receives the Calendar Account ID and the site's language locale, it allows for highly flexible customization, such as applying different translations for each calendar and per language.</div>
202	<strong style="font-size: 1.2em;">Filter Hook Details</strong>
203	<ul><li>Hook Name: <code>booking_package_get_translate_text</code></li></ul>
204	<strong style="font-size: 1.2em;">Parameters</strong>
205	<ol>
206	<li><b>\$type</b> (string) An identifier indicating the type of the translation target. It contains one of the following strings:
207	<ul class="booking_package_get_translate_text_type"><li>form_field</li><li>service</li><li>option</li><li>guest</li><li>coupon</li><li>extra_charge</li><li>tax</li><li>notification</li><!-- <li>user_profile</li> --></ul></li>
208	<li><b>\$calendar_account_id</b> (int) The ID of the calendar account associated with this text.</li>
209	<li><b>\$unique_id</b> (string\|int) A unique ID used to identify the specific translation target. (e.g., the form field key '<b>first_name</b>')</li>
210	<li><b>\$locale</b> (string) The locale code of the current site language retrieved via the WordPress <b>get_locale()</b> function. (e.g., 'en_US', 'ja')</li>
211	<li><b>\$string_array</b> (array) (<b>Target for modification</b>) An associative array containing the text to be translated. Modify the values within this array and ensure you return it as an array.
212	<ul><li><b>Important</b>: When translating items where the value is an array, such as the options key (e.g., dropdown choices), you must ensure that the number of elements matches the original array. If the number of elements does not match the original array, the changes will not be reflected.</li></ul></li>
213	</ol>
214	<strong style="font-size: 1.2em;">Usage Example</strong>
215	<div>This is a sample code that changes the label of the <b>first_name</b> field to "Nombre (Solo para ID 5)" only when the site language is Spanish (<b>es_ES</b>) and the Calendar Account ID is <b>5</b>.</div>
216	<br>
217	<textarea class="booking-package-sample-code" style="display:none;">
218	<?php
219	/** Dynamic Text Translation and Modification
220	*
221	* @param string \$type Type of text
222	* @param int \$calendar_account_id Calendar Account ID
223	* @param string\|int \$unique_id Unique ID
224	* @param string \$locale Current site locale
225	* @param array \$string_array Array of text to translate
226	* @return array Modified text array
227	*/
228	function my_advanced_translator( \$type, \$calendar_account_id, \$unique_id, \$locale, \$string_array ) {
229	// Check if specific conditions are met
230	if ( \$type === 'form_field' && \$unique_id === 'first_name' && \$calendar_account_id === 5 && \$locale === 'es_ES' ) {
231	\$string_array['label'] = 'Nombre (Solo para ID 5)';
232	}
233	// Always return the array
234	return \$string_array;
235	}
236	add_filter( 'booking_package_get_translate_text', 'my_advanced_translator', 10, 5 );
237	?>
238	</textarea>
239
240	</div>
241
242	EOF;
243
244	return $document;
245
246	}
247
248	public function displayBookingCalendar() {
249
250	$document = <<<EOF
251
252	<div>
253	<h2>How to Display the Booking Calendar on Your Website</h2>
254	<div>To publish your created calendar to site visitors, you need to paste the "shortcode" onto your page by following these steps:</div>
255	<ol>
256	<li><b>Copy the Shortcode</b> Check the "Shortcode" column on the right side of the "Calendar Settings" list screen. Select and copy the code for the calendar you want to display (e.g.,<code>[booking_package id=4]</code>).
257	<li><b>Edit the Page</b> From the WordPress dashboard, navigate to "Pages" or "Posts" and open the editor for the page where you want to display the calendar (or click "Add New").</li>
258	<li>
259	Paste the Shortcode Paste the copied code into the content area.
260	<ul>
261	<li><b>If using the Block Editor (Gutenberg)</b>: Click the "+" button, search for and add the "Shortcode" block, then paste the code inside it.</li>
262	<li><b>If using the Classic Editor</b>: Simply paste the code directly into the text input field.</li>
263	</ul>
264	</li>
265	<li><b>Publish and Verify</b> Click "Publish" (or "Update"), then view the actual page to confirm that the calendar loads correctly.</li>
266	</ol>
267	</div>
268
269	EOF;
270
271	return $document;
272
273	}
274
275	public function emailSendingSettings() {
276
277	$document = <<<EOF
278
279	<div>
280	<h2>Procedures for Configuring Email Settings in Booking Package</h2>
281	<div>This guide explains how to configure settings to automatically send emails to the administrator and the booker (customer) when a booking is completed using Booking Package.</div>
282	<h3>Step-by-Step Instructions</h3>
283	<ol>
284	<li>
285	<b>Configuring Sender and Administrator Email Settings</b>
286	<div>First, configure the sender information and the administrator email address that will receive booking notifications.</div>
287	<ul>
288	<li><b>Setting Location</b>: Calendar Account > <b>Settings</b> tab</li>
289	<li><b>Relevant Section</b>: <b>Email Address</b> section</li>
290	</ul>
291	<div>The role of each item is as follows:</div>
292	<ul>
293	<li><b>Recipient Email Address</b>: Enter the email address of the administrator (you) who will receive notifications when a booking is made.</li>
294	<li><b>Sender Name</b>: The name displayed as the "Sender" in the emails received by the customer (e.g., XX Salon Reservations, XX Inc.).</li>
295	<li><b>Sending Email Address</b>: The email address that appears as the "From" address in the emails received by the customer.</li>
296	</ul>
297	</li>
298	<li>
299	<b>Linking the Booker's (Customer's) Email Address</b><br>
300	<div>You must configure the plugin so it recognizes "which address to send the customer email to." Please note that if this setting is neglected, emails will not be delivered to the customer.</div>
301	<ul>
302	<li><b>Setting Location</b>: Calendar Account > <b>Form Fields</b> tab</li>
303	<li><b>Relevant Section</b>: <b>Use as Email Field</b> within the advanced settings of the item being edited.</li>
304	</ul>
305	<div>Open the settings for the field where the customer enters their email address (e.g., "Email") and configure the following:</div>
306	<ul>
307	<li><b>Use as Email Field</b>: Make sure to select "<b>Yes</b>". By doing so, the address entered in this input field will be recognized as the destination for the automatic reply email.</li>
308	</ul>
309	</li>
310	<li>
311	<b>Creating the Email Body and Enabling Notifications</b><br>
312	<div>Set the content of the emails to be sent for each booking status.</div>
313	<ul><li><b>Setting Location</b>: Calendar Account > <b>Notifications</b> tab</li></ul>
314	<div>When you open the Notifications tab, a list such as "New," "Pending," and "Approved" will appear. Follow the steps below to configure them:</div>
315	<ul>
316	<li><b>Select Sending Type</b>: Click on the timing of the email you wish to configure to open the edit screen.</li>
317	<li><b>Notifications</b>: Check the box for "<b>Email</b>" within the edit screen. If this is not checked, the email will not be sent.</li>
318	<li><b>Subject</b>: Enter the email subject line (e.g., [Booking Completed] Thank you for your reservation).</li>
319	<li>
320	<b>Message body</b>: Enter the email body text. You can use the shortcodes found in the "Help" section on the right (e.g., <code>[name]</code> or <code>[bookingDate]</code>) to automatically insert the booker's name or booking date/time.
321	<ul>
322	<li><b>For Customer</b>: Enter the content intended for the customer.</li>
323	<li><b>For Administrator</b>: Enter the content intended for the administrator.</li>
324	</ul>
325	</li>
326	</ul>
327	</li>
328	<li>
329	<b>If Emails Are Not Sent</b><br>
330	<div>If emails are still not being sent from the plugin after configuring the settings above, please install a separate plugin that records email sending logs (such as <b>WP Mail Logging</b>) to check the logs. Checking the sending logs makes it easier to identify the cause, such as whether the email generation process is being performed correctly by the plugin or if an error is occurring on the server side.</div>
331	</li>
332	</ol>
333
334	</div>
335	EOF;
336
337	return $document;
338
339	}
340
341	public function weeklyScheduleTemplates() {
342
343	$document = <<<EOF
344
345	<div>
346	<h2>Setting Up Weekly Schedule Templates</h2>
347	<div>In the "<b>Schedules</b>" tab under "Calendar Settings," you can configure the basic schedule pattern (template) that repeats every week.</div>
348	<h3>Step-by-Step Instructions</h3>
349	<ol>
350	<li>
351	<b>Open the Template Editing Screen</b>
352	<div>Click on "<b>Weekly Schedule Templates</b>" in the top menu within the Schedules tab. From the list on the left side of the screen, select the "<b>Day of the Week</b>" you wish to configure.</div>
353
354	</li>
355	<li>
356	<b>How to Add Time Slots</b><br>
357	<div>There are two ways to add time slots:</div>
358	<div><b>A. Adding Time Slots Manually (Individually)</b> This is useful when you want to add specific times only.</div>
359	<ol>
360	<li>Click the "Clock Icon" in the <b>empty row</b> at the bottom of the schedule list.</li>
361	<li>The "<b>Add a Time Slot</b>" screen will appear.</li>
362	<li>Select the desired time (minutes can also be specified) and click "<b>Apply</b>". The new slot will be added to the list.</li>
363	</ol>
364	<div><b>B. Generating Time Slots Automatically in Bulk</b> If no time slots are registered for that day, the "<b>Set Up Time Slots</b>" panel will automatically appear. This is useful for creating a full day's schedule at regular intervals all at once.</div>
365	<ol>
366	<li>
367	Configure the following items in the displayed panel and click "Apply":
368	<ul>
369	<li><b>Time</b>: Specify the start and end times (e.g., 09:00 to 18:00).</li>
370	<li><b>Interval</b>: Specify the gap between time slots (e.g., every 30 mins, every 1 hour).</li>
371	<li><b>Booking Deadline</b>: Set the cut-off time for accepting bookings.</li>
372	<li><b>Available Slots</b>: Set the capacity (stock) for each time slot.</li>
373	</ul>
374	</li>
375	</ol>
376	</li>
377	<li>
378	<b>Saving Settings</b><br>
379	<div>After adding or editing time slots, be sure to click the "<b>Save</b>" button at the bottom right of the screen to apply the settings.</div>
380	</li>
381
382	</ol>
383	<h2>Important Notes: Applying Changes</h2>
384	<ul>
385	<li><b>Scope of Template Changes</b> Revisions made to the template here will <b>only apply to schedules generated after the change</b>. Template changes will not be automatically reflected in past or future time slots that have already been published (generated) on the calendar.</li>
386	<li><b>How to Change Published Schedules</b> If you wish to modify the schedule for a specific day already displayed on the calendar, do not use the template editing screen. Instead, go to the "Schedules" tab, click directly on that <b>specific date</b> within the calendar, and edit the time slots individually.</li>
387	</ul>
388	</div>
389	EOF;
390
391	return $document;
392
393
394	}
395
396	public function bulkScheduleRegistration() {
397
398	$document = <<<EOF
399
400	<div>
401	<h2>How to Select Multiple Dates and Bulk Register Schedules</h2>
402	<div>In the Schedule management section of your Calendar Account, you can select multiple specific dates on the calendar to create and save common time slots at once.</div>
403	<div>This feature is particularly useful when you want to register <b>consecutive dates</b> (such as for an event period) or <b>irregular business days</b> that differ from the patterns defined in your Weekly Schedule Templates.</div>
404	<h3>Step-by-Step Instructions</h3>
405	<ol>
406	<li>
407	<b>Switch to Multiple Day Selection Mode</b><br>
408	<div>Click the "Select Multiple Days" button located at the top of the calendar in the Schedule tab.</div>
409	</li>
410	<li>
411	<b>Select Dates</b><br>
412	<div>Click on the dates on the calendar where you want to register a schedule.</div>
413	<ul>
414	<li><b>Selected dates</b> will change to have a <b>blue background color</b>.</li>
415	<li>If you select a date by mistake, simply click it again to deselect it (the background will return to white).</li>
416	</ul>
417	</li>
418	<li>
419	<b>Add Time Slots</b><br>
420	<div>Once you have selected all the target dates, click the "<b>Add Time Slots</b>" button at the top left of the screen. A settings popup will appear. Configure the following items:</div>
421	<ul>
422	<li><b>Time</b>: Set the start time (From) and end time (To) for accepting bookings.</li>
423	<li><b>Interval</b>: Set the duration for each booking slot (e.g., 30 min, 60 min).</li>
424	<li><b>Booking Deadline</b>: Set the cutoff time for accepting bookings (e.g., 0 min before).</li>
425	<li><b>Available Slots</b>: Set the maximum number of guests/bookings accepted for each time slot.</li>
426	</ul>
427	<div>When you are finished configuring these settings, click "Apply" within the popup.</div>
428	</li>
429	<li>
430	<b>Review the List</b><br>
431	<div>A list of time slots will be automatically generated for all the selected dates. You can review the generated list and individually modify details (such as time or capacity) on this screen if necessary.</div>
432	</li>
433	</ol>
434	<h2>Saving and Publication Settings</h2>
435	<div>There are two methods for saving your schedule: "<b>Immediate Publication</b>" and "<b>Scheduled Publication</b>". Please choose the method that best suits your needs.</div>
436	<b>Pattern A: Start Bookings Immediately (Standard Save)</b><br>
437	<div>If you want the created schedule to appear on your website's calendar immediately, click the "<b>Save</b>" button at the bottom right of the screen. Acceptance of bookings will begin as soon as you save.</div>
438	<b>Pattern B: Start Bookings Later (Set Publication Date)</b><br>
439	<div>If you want to publish the booking slots only after a specific date and time (e.g., for a promotional campaign or when opening bookings for the next month), follow these steps:</div>
440	<ol>
441	<li>Click the "<b>Set the Publication Date</b>" button at the bottom right of the screen.</li>
442	<li>A date selection calendar will appear. Select the <b>date and time you want the schedule to be published</b>.</li>
443	<li>Click "<b>Save</b>" within the settings window.</li>
444	</ol>
445	<div>
446	<b>Note</b>: Schedules saved using this method will not appear on the front-end calendar (the booking screen for customers) until the specified date and time is reached. Once that time passes, the slots will automatically appear and become available for booking.
447	</div>
448	<h2>Supplementary Information</h2>
449	<ul>
450	<li><b>Delete or Pause Schedules</b>: Before saving, you can use the checkboxes on the right side of the generated list to set specific slots to "<b>Delete</b>" or "<b>Paused</b>".</li>
451	</ul>
452	</div>
453	EOF;
454
455	return $document;
456
457
458	}
459
460	public function videos() {
461
462	$document = '<div><h3>' . __('Videos', 'booking-package') . '</h3>';
463	$document .= '<ul>';
464	$document .= '<li><a href="https://booking-package.saasproject.net/how-does-the-booking-calendar-show-on-the-page/" target="_blank">' . __('How do I show the booking calendar on the page?', 'booking-package') . '</a></li>';
465	$document .= '<li><a href="https://booking-package.saasproject.net/how-do-i-send-a-booking-email-with-a-plugin/" target="_blank">' . __('How do I send a booking email?', 'booking-package') . '</a></li>';
466	$document .= '<li><a href="https://booking-package.saasproject.net/how-do-i-create-booking-schedules/" target="_blank">' . __('How do I create booking schedules?', 'booking-package') . '</a></li>';
467	$document .= '</ul></div>';
468	return $document;
469
470	}
471
472	}
473
474
475
476	?>