Merge branch 'master' into GS-2863

Author: mafanya23

data/api/gantt_addcalendar.md

@@ -14,18 +14,49 @@ addCalendar
 @example:
 
 // adding a previously created calendar
-var calendarId = gantt.addCalendar(calendar);
-
-// adding a calendar with a new config
-var calendarId = gantt.addCalendar({
-	id:"custom", // optional
-	worktime: {
-		hours: ["8:00-17:00"],
-		days: [ 1, 1, 1, 1, 1, 1 ,1]
-	}
+const calendarId = gantt.addCalendar(calendar);
+
+// adding a calendar with a new config (the "days" property is set as array)
+const calendarId = gantt.addCalendar({
+    id: "custom", // optional
+    worktime: {
+        hours: ["8:00-17:00"],
+        days: [1, 1, 1, 1, 1, 1, 1]
+    }
 });
 
-var calendar = gantt.getCalendar(calendarId);
+// adding a calendar with a new config (the "days" property is set as object)
+const calendarId = gantt.addCalendar({
+    id: "global", // the calendar id is optional
+    worktime: {
+      hours: ["8:00-12:00", "13:00-17:00"], // global work hours for weekdays
+      days: {
+        weekdays: [0, 1, 1, 1, 1, 1, 0],
+        dates: {
+          "2025-04-06": true,  // override work hours for a specific date
+          "2025-04-08": false,
+          "2025-04-09":  ["9:00-15:00"]
+        }
+      },
+      customWeeks: {
+        lastMonthOfTheYear: {
+          from: new Date(2025, 11, 1),
+          to: new Date(2026, 0, 1),
+          hours: ["9:00-13:00"],
+          days: {
+            weekdays: [0, 1, 1, 1, 1, 0, 0],
+            dates: {
+              "2025-12-08": true,
+              "2025-12-09":  false,
+              "2025-12-10":  ["9:00-15:00"]
+            }
+          }
+        }
+      }
+    }
+});
+
+const calendar = gantt.getCalendar(calendarId);
 
 @template:	api_method
 @descr:
@@ -34,59 +65,96 @@ The calendar configuration object can contain the following attributes:
 - <span class=subproperty>**id?**</span> - (*string | number*) - optional, the calendar id
 - <span class=subproperty>**worktime?**</span> - (*object*) - an object that sets the worktime in days and hours. It can include:
     - **_hours?_** - (*string[] | number[] | boolean*) - optional, an array with global working hours, sets the start and end hours of the task
-    - **_days?_** - (*WorkDaysTuple*) - optional, an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day
+    - **_days?_** - (*WorkDaysTuple* | *object*) - optional, it can be:
+        -  either an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day
+        - or an object that contains weekdays and dates. It can include:
+            - **_weekdays?_** - (*WorkDaysTuple*) optional, an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day
+            - **_dates?_** - (*object*) optional, an object with working time settings for specified dates. The object can contain a number of key: value pairs where:
+                - key is a date set as a string 
+                - value is either an array of working hours as 'from'-'to' pairs or a boolean ('false' value sets a day-off, 'true' applies the default hours (["8:00-17:00"]))
     - **_customWeeks?_** - (*object*) - optional, an object with different working-time rules for different periods of time. The object can contain a set of key:value pairs where key is the name of a time span and value is an object with a list of attributes.
         - **_[timespan: string]_** - (*object*) - the time span with the working time settings. The name of that object is used as the name of the time span
             - **_from_** - (*Date*) - the date when the time span is scheduled to begin
             - **_to_** - (*Date*) - the date when the time span is scheduled to be completed
             - **_hours?_** - (*Array&lt;string | number&gt;*) - optional, an array of working hours as 'from'-'to' pairs.'false' value sets a day-off, 'true' (default value) applies the default hours (["8:00-17:00"])
-            - **_days?_** - (*WorkDaysTuple | boolean*) - optional, an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day.
-
+            - **_days?_** - (*WorkDaysTuple* | *object*) - optional, it can be:
+        		-  either an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day
+        		- or an object that contains weekdays and dates. It can include:
+            		- **_weekdays?_** - (*WorkDaysTuple*) optional, an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day
+            		- **_dates?_** - (*object*) optional, an object with working time settings for specified dates. The object can contain a number of key: value pairs where:
+                		- key is a date set as a string 
+                		- value is either an array of working hours as 'from'-'to' pairs or a boolean ('false' value sets a day-off, 'true' applies the default hours (["8:00-17:00"]))
 
 
-###Setting individual working hours for a day
+### Setting individual working hours for a day
 
-Instead of the number of a week day, you can also set custom working hours for this day.<br>
-For example:  
+Instead of the number of a week day, you can also set custom working hours for this day.
+For example:
 
 ~~~js
-var calendar = {
-    id:"calendar1", // optional
+const calendar = {
+    id: "calendar1", // optional
     worktime: {
         hours: ["8:00-17:00"],
-        days: [ 0, 1, 1, 1, ["12:00-17:00"], 1, 0]
+        days: [0, 1, 1, 1, ["12:00-17:00"], 1, 0] /*!*/
     }
 }
 ~~~
 
 where ["12:00-17:00"] are working hours from 12 pm to 17 pm for Thursday.
 
-
 ### Setting worktime for different time intervals
 
-There is the ability to configure different working time rules for different periods of time by using the **customWeeks** attribute:
+There is a possibility to configure different working time rules for different periods of time by using the **customWeeks** attribute:
 
 ~~~js
-// adding a calendar with a new config
 gantt.addCalendar({
-	id:"default", // optional
-	worktime: {
-		hours: ["8:00-17:00"],
-		days: [ 1, 1, 1, 1, 1, 1 ,1],
-		customWeeks: {
-			winter: {
-				from: new Date(2020, 11, 1),// December 1st, 2020
-				to: new Date(2021, 2, 1),// March 1st 00:00, 2021
-				hours: ["9:00-13:00", "14:00-16:00"],
-				days: [ 1, 1, 1, 1, 0, 0, 0]
-			}
-		}
-	}
+    id: "global", // optional
+    worktime: {
+        hours: ["8:00-17:00"],
+        days: [1, 1, 1, 1, 1, 1, 1],
+        customWeeks: {
+            winter: {
+                from: new Date(2025, 11, 1), // December 1st, 2025
+                to: new Date(2026, 2, 1), // March 1st, 00:00, 2026
+                hours: ["9:00-13:00", "14:00-16:00"],
+                days: [1, 1, 1, 1, 0, 0, 0]
+            }
+        }
+    }
 });
+~~~
+### Setting worktime for certain dates
 
+You can also specify working hours for certain dates by setting them in the **_dates_** property of the **_days_** object (both for the **worktime** attribute and the **customWeeks** property). For example:  
 
+~~~js
+const calendar = {
+    id: "calendar1", // optional
+    worktime: {
+        hours: ["8:00-17:00"],
+        days: { 
+        	dates: { 
+          		"2025-04-09":  ["9:00-15:00"] 
+        	} 
+    	},
+        customWeeks: {
+            winter: {
+                from: new Date(2025, 11, 1), // December 1st, 2025
+                to: new Date(2026, 2, 1), // March 1st, 00:00, 2026
+                hours: ["9:00-13:00", "14:00-16:00"],
+                days: { 
+                    dates: { 
+                        "2026-01-02":  ["9:00-15:00"] 
+                    } 
+                }
+            }
+        }
+    }
+}
 ~~~
-    
+
+
 @relatedsample:
 
 09_worktime/06_task_calendars.html
@@ -103,5 +171,6 @@ api/gantt_calendar_other.md
 desktop/working_time.md#multipleworktimecalendars
 
 @changelog:
-- the **customWeeks** property is added in v7.1;
+- the possibility to specify the **_days_** property as *object* with weekdays and dates is added in v9.1
+- the **customWeeks** property is added in v7.1
 - added in version 4.2

data/api/gantt_addtasklayer.md

@@ -13,22 +13,24 @@ addTaskLayer
 
 @example:
 gantt.init("gantt_here");
-gantt.addTaskLayer(function draw_deadline(task) {
+
+gantt.addTaskLayer((task) => {
 	if (task.deadline) {
-		var el = document.createElement('div');
-		el.className = 'deadline';
-		var sizes = gantt.getTaskPosition(task, task.deadline);
+		const el = document.createElement("div");
+		el.className = "deadline";
 
-		el.style.left = sizes.left + 'px';
-		el.style.top = sizes.top + 'px';
+		const sizes = gantt.getTaskPosition(task, task.deadline);
+		el.style.left = `${sizes.left}px`;
+		el.style.top = `${sizes.top}px`;
 
-		el.setAttribute('title', gantt.templates.task_date(task.deadline));
+		el.setAttribute("title", gantt.templates.task_date(task.deadline));
 		return el;
 	}
 	return false;
 });
 
 
+
 @related:
 desktop/baselines.md
 desktop/how_to.md#howtoverticallyreordertasksinthetimeline (read how to vertically reorder tasks in the timeline)
@@ -119,16 +121,16 @@ To do that, you need to use the *object* parameter of the *addTaskLayer()* metho
 
 ~~~js
 gantt.addTaskLayer({
-    renderer: {
-        render: function(task, timeline, viewport){
-            ...
-            return  HTMLElement
-        },
-        getRectangle: function(task, view){
-            ....
-            return {left, top, height, width};
-        }
-    }
+	renderer: {
+		render: (task, timeline, viewport) => {
+			// ...
+			return /* HTMLElement */;
+		},
+		getRectangle: (task, view) => {
+			// ...
+			return { left, top, height, width };
+		}
+	}
 });
 ~~~
 
@@ -141,24 +143,31 @@ The logic of rendering custom elements is the following:
 
 ~~~js
 gantt.addTaskLayer({
-    renderer: {
-      render: function draw_planned(task) {
-        if (task.planned_start && task.planned_end) {
-          var sizes = gantt.getTaskPosition(task,task.planned_start,task.planned_end);
-          var el = document.createElement('div');
-          el.className = 'baseline';
-          el.style.left = sizes.left + 'px';
-          el.style.width = sizes.width + 'px';
-          el.style.top = sizes.top + gantt.config.task_height + 13 + 'px';
-          return el;
-        }
-        return false;
-      },
-      // define getRectangle in order to hook layer with the smart rendering
-      getRectangle: function(task, view){
-        return gantt.getTaskPosition(task, task.planned_start, task.planned_end);
-      }
-    }
+	renderer: {
+		render: (task) => {
+			if (task.planned_start && task.planned_end) {
+				const sizes = gantt.getTaskPosition(
+					task,
+					task.planned_start,
+					task.planned_end
+				);
+				const el = document.createElement('div');
+				el.className = 'baseline';
+				el.style.left = sizes.left + 'px';
+				el.style.width = sizes.width + 'px';
+				el.style.top = (sizes.top + gantt.config.task_height + 13) + 'px';
+				return el;
+			}
+			return false;
+		},
+		// define getRectangle in order to hook layer with the smart rendering
+		getRectangle: (task, view) =>
+			gantt.getTaskPosition(
+				task,
+				task.planned_start,
+				task.planned_end
+			)
+	}
 });
 ~~~
 
@@ -168,20 +177,20 @@ The **renderer** object of the *addTaskLayer()* method provides a possibility to
 
 ~~~js
 gantt.addTaskLayer({
-    renderer: {
-        render: function(task, timeline, viewport){
-            ...
-            return  HTMLElement
-        },
-        update: function(task, node, timeline, viewport){
-            ...
-            // put the currently visible part of the element into node inner html
-        },
-        getRectangle: function(task, view){
-            ....
-            return {left, top, height, width};
-        }
-    }
+	renderer: {
+		render: (task, timeline, viewport) => {
+			// ...
+			return /* HTMLElement */;
+		},
+		update: (task, node, timeline, viewport) => {
+			// ...
+			// put the currently visible part of the element into node inner html
+		},
+		getRectangle: (task, view) => {
+			// ...
+			return { left, top, height, width };
+		}
+	}
 });
 ~~~
 
@@ -195,20 +204,20 @@ Since v7.1.8 the **renderer** object of the *addTaskLayer()* method allows getti
 
 ~~~js
 gantt.addTaskLayer({
-    renderer: {
-        render: function(task, timeline, viewport){
-            ...
-            return  HTMLElement
-        },
-        getVisibleRange: function(){
-        	...
-            return { 
-  				start: indexStart,
-  				end: indexEnd
-			}
-        }
+	renderer: {
+		render: (task, timeline, viewport) => {
+			// ...
+			return /* HTMLElement */;
+		},
+		getVisibleRange: () => {
+			// ...
+			return {
+				start: indexStart,
+				end: indexEnd
+			};
+		}
 	}
-});     
+});
 ~~~
 
 - **getVisibleRange** - a function that returns an object with the start and end indexes of visible tasks rows. 
@@ -222,15 +231,15 @@ The **renderer** object of the *addTaskLayer()* method provides the **onrender**
 
 ~~~js
 gantt.addTaskLayer({
-    renderer: {
-        render: function(task, timeline, viewport){
-            ...
-            return  HTMLElement
-        },
-        onrender: function(item, node, view){
-            console.log("render", item, node)
-        }
-    }
+	renderer: {
+		render: (task, timeline, viewport) => {
+			// ...
+			return /* HTMLElement */;
+		},
+		onrender: (item, node, view) => {
+			console.log("render", item, node);
+		}
+	}
 });
 ~~~