[update] draft for inbuilt timeline extra elements guide

Author: mafanya23

data/desktop/baselines.md

@@ -6,6 +6,9 @@ Custom Elements in Timeline Area
 dhtmlxGantt provides the [built-in functionality](desktop/inbuilt_baselines.md) that allows rendering such extra elements as baselines, 
 deadlines and task constraints by default. In case, you need to extend or modify the default features, you can add custom elements into timeline manually as described below.
 
+Displaying additional elements is usually done by creating a displayable layer and placing custom elements there
+(using the absolute positioning to put custom elements next to the related task).
+
 **To add one more layer to the timeline area**, use the api/gantt_addtasklayer.md method. As a parameter, the method takes a function that: 
 
 - Takes a task object;

data/desktop/inbuilt_baselines.md

@@ -9,9 +9,10 @@ By default, dhtmlxGantt renders elements of the timeline area as layers and does
 1. Timeline's grid
 2. Links
 3. Tasks
+4. Additional elements
 
-Displaying additional elements, such as a baseline or deadline marker, is usually done by creating a displayable layer and placing custom elements there
-(using the absolute positioning to put custom elements next to the related task).
+Gantt includes such built-in elements as baselines, deadlines and time constraints. Instead of the default extra elements, 
+you can also [create custom ones as additional layers](desktop/baselines.md). 
 
 Baselines
 ----------------
@@ -21,7 +22,58 @@ Gantt API provides built-in support for baseline entities, greatly simplifying t
 
 ![Inbuilt baselines](desktop/inbuilt_baselines.png)
 
-### Loading Baselines with Tasks
+{{sample 04_customization/15_baselines.html}}
+
+### Customizing baselines
+
+In case, the default baselines functionality doesn't suit your project requirements, you can disable it using the api/gantt_baselines_config.md configuration option.
+
+~~~js
+gantt.config.baselines = false;
+~~~
+
+After that you can customize the display of baselines in one of the following ways:
+
+1\. Using the **gantt.config.baselines** configuration object
+
+The **baselines** configuration option also allows customizing the rendering of baselines in the Gantt chart when set as an object. 
+The object configuration contains the following properties:
+
+- **datastore** (*string*) - the name of the datastore used for storing baseline entries. For related functionality, see the `getDatastore` method.
+- **render_mode** (*boolean | string*) - determines how baselines are displayed:
+	- `false` - baselines are not shown.
+	- `"taskRow"` - baselines are displayed in the same row as the task bar.
+	- `"separateRow"` - baselines are shown in a separate subrow, expanding the task row height.
+	- `"individualRow"` - each baseline is displayed in its own subrow beneath the task.
+- **dataprocessor_baselines** (*boolean*) - specifies whether baseline updates trigger the DataProcessor as individual entries.
+- **row_height** (*number*) - defines the height of the subrow for baselines, applicable only when `render_mode` is set to `"separateRow"` or `"individualRow"`.
+- **bar_height** (*number*) - sets the height of the baseline bar.
+
+For example:
+
+~~~js
+gantt.config.baselines = {
+  datastore: "baselines",
+  render_mode: false,
+  dataprocessor_baselines: false,
+  row_height: 16,
+  bar_height: 8
+};
+gantt.init("gantt_here");
+~~~
+
+If you dynamically modify the display settings of the **gantt.config.baselines** config, you should use the api/gantt_adjusttaskheightforbaselines.md method
+for proper display of baseline elements.
+
+~~~js
+const task = gantt.getTask(taskId);
+gantt.adjustTaskHeightForBaselines(task); /*!*/
+gantt.render();
+~~~
+
+2\. [Creating a custom baseline element](desktop/baselines.md) for adding into the timeline.
+
+### Loading baselines with tasks
 
 Baselines can be loaded directly alongside tasks, streamlining data management and display. Check the example below:
 
@@ -56,11 +108,38 @@ gantt.parse({
 
 Once baselines are loaded, Gantt will automatically display them in the timeline without any additional configuration.
 
-{{sample 04_customization/15_baselines.html}}
+### Getting task baselines
+
+You can get the baselines of a particular task using the api/gantt_gettaskbaselines.md method. 
+
+~~~js
+gantt.getTaskBaselines(5);
+~~~
 
-### Using the lightbox
+The method will return an array of baselines objects of the specified task from the datastore.
 
-You can manage baselines via the lightbox control. Adding, editing and deleting baselines is avalable directly from the task details.
+~~~js
+[
+    {
+        task_id: 5,
+        id: 1, 
+        duration: 2, 
+        start_date: "03-04-2019 00:00", 
+        end_date: "05-04-2019 00:00"
+    },
+    {
+        task_id: 5,
+        id: 2, 
+        duration: 1, 
+        start_date: "06-04-2019 00:00", 
+        end_date: "07-04-2019 00:00"
+    }
+]
+~~~
+
+### Baselines in the lightbox
+
+You can manage baselines via the lightbox control. Adding, editing and deleting baselines is available directly from the task details.
 
 ~~~js
 gantt.config.lightbox.sections = [
@@ -72,7 +151,7 @@ gantt.config.lightbox.sections = [
 
 ![Baseline lightbox](desktop/baselines_lightbox.png)
 
-### Baseline Rendering Modes
+### Baseline rendering modes
 
 Gantt offers three modes for displaying baselines. You can choose the rendering mode that suits best for your needs
 by setting the **gantt.config.baselines.render_mode** configuration option to the corresponding value. There are three modes available:
@@ -107,12 +186,26 @@ gantt.config.baselines.render_mode = "individualRow";
 
 ![Individual row mode](desktop/baselines_individual_row.png)
 
+### Setting baseline text
+
+To specify a text that should be displayed inside the baseline element, use the api/gantt_baseline_text_template.md template:
+
+~~~js
+gantt.templates.baseline_text = function(task, baseline, index) {
+    return "Baseline #" + (index + 1);
+};
+~~~
+
 Deadlines and constraints
 --------------------------
 
 In project management, tracking deadlines and understanding task constraints are vital for timely delivery. 
 DHTMLX Gantt comes with built-in visualization for deadlines and constraints, enhancing the ability to manage project timelines effectively.
 
+![Deadlines](desktop/deadlines.png)
+
+{{sample 04_customization/14_deadline.html}}
+
 ### Deadlines visualization
 
 Gantt supports a numeric **task.deadline** field. When specified, it displays a visual indicator on the chart, thereby simplifying the tracking of task deadlines.
@@ -132,6 +225,19 @@ gantt.parse({
 });
 ~~~
 
-![Deadlines](desktop/deadlines.png)
+### Customizing deadlines
+
+In case, the default deadlines functionality doesn't suit your project requirements, you can disable it using the api/gantt_deadlines_config.md configuration option.
+
+~~~js
+gantt.config.deadlines = false;
+~~~
+
+After that you can customize the display of deadlines by [creating a custom deadline element](desktop/baselines.md) for adding into the timeline.
+
+The **gantt.config.deadlines** config enables or disables the display of deadline elements for tasks. If enabled, Gantt will check the **task.deadline** property, 
+and if it contains a valid date, the deadline element will be displayed in the timeline.
+
+
+
 
-{{sample 04_customization/14_deadline.html}}