Update

Author: clauspruefer

doc/dev-examples.rst

@@ -5,8 +5,7 @@
 25. Developing Examples
 =======================
 
-After module
-
+Building examples is similar to building tests described in the last chapter.
 
 - structure
   - app config (database)

doc/dev-object-modeling.rst

@@ -5,37 +5,133 @@
 26. x0-Object Modeling
 ======================
 
-The following sections explain how to design custom x0 system objects and define
-their specifications for seamless integration into the core system.
+The following sections explain how to design **custom** *x0-system-objects* and
+define their **specifications** for seamless integration into the core system.
 
 26.1. Basic Modeling Rules
 --------------------------
 
-You should have a solid understanding of the following x0 fundamentals before
+You should have a **solid understanding** of the following *x0* fundamentals before
 continuing:
 
 - Base Classes / Inheritance
-- Child Objects
+- Child Objects / Parent Object
 - Event Handler / Callbacks
 - Building Object Structure (DOM)
 - Modifying Runtime Data
-- Object Realtime Updating
+- Object Realtime Updates
+- Object Initialization
+- Adding Context Menu Functionality
 
 26.1.1. Base Classes / Inheritance
 **********************************
 
 You should familiarize yourself with the x0 *Core Base Model*.
 Refer to: :ref:`devoopmodel_base`.
 
-26.1.2. Child Objects
-*********************
+Any **custom** *x0-system-object* must inherit ``sysBaseObject`` in its prototype.
+
+.. code-block:: javascript
+
+    //- inherit sysBaseObject
+    sysObjNewcomer.prototype = new sysBaseObject();
+
+26.1.2. Child Objects / Parent Object
+*************************************
+
+The ``self.ChildObjects[]`` model in ``sysBaseObject.js`` is an array that
+manages the child objects of a ``sysBaseObject`` instance. It functions as a
+recursive container for hierarchical object structures within the
+*x0-framework*.
+
+1. Initialization
+
+In any new modeled Object's constructor, ``this.ChildObjects[]`` must be initialized
+as an empty array:
+
+.. code-block:: javascript
+
+    this.ChildObjects = new Array(); //- Child Objects
+
+2. Child Object Relationships
+
+Each child object in the array is an instance of ``sysBaseObject`` or its derived classes.
+A parent-child relationship is established using the ``ParentObject`` property.
+
+This enables any child object to directly access its parent(s).
+
+.. code-block:: javascript
+
+    //- Do something in the ParentObject
+    this.ParentObject.doSomething();
+
+    //- Do something in the ParentObject.ParentObject
+    this.ParentObject.ParentObject.doSomething();
+
+3. Add Objects
+
+Adding objects to self is done like this:
+
+.. code-block:: javascript
+
+    //- add new sysObjDiv()
+    let Obj1 = new sysObjDiv();
+    Obj1.ObjectID = 'MyDiv1';
+
+    //- add Obj1 to parent
+    this.addObject(Obj1);
+
+see: :ref: sysBaseObject.addObject()
+
+4. Propagate Object(s) to DOM
+
+.. code-block:: javascript
+
+    //- render all ParentObject.ChildObjects[]
+    this.ParentObject.renderObject();
 
 26.1.3. Event Handler / Callbacks
 *********************************
 
+If you want to process native DOM Events (not *x0-events*),
+in any new modeled Object's constructor, ``this.EventListeners[]`` must be
+initialized as an empty array:
+
+.. code-block:: javascript
+
+    this.EventListeners = new Array(); //- Array of EventListener Objects
+
+1. Add Event Listeners
+
+.. code-block:: javascript
+
+    let EventListenerObj = new Object();
+    EventListenerObj['Type'] = 'mousedown'; //- Event Type 'mousedown'
+    EventListenerObj['Element'] = this.EventListenerCallback.bind(this); //- Callback Method
+    this.EventListeners['ListenerID'] = EventListenerObj; //- Add Listener with ListenerID
+
+2. Multiple Event Listeners
+
+When adding multiple Event Listeners, processing order will be preserved.
+
+3. Event Listener Activation
+
+After adding Event Listeners in Realtime Objects, they have to be explicitely
+activated before working.
+
+.. code-block:: javascript
+
+    this.processEventListener();
+
+4. sysButtonCallback Object
+
+The ``sysButtonCallback`` *x0-object* can be used to asbtract ...
+
 26.1.4. Building DOM Object Structure
 *************************************
 
+See :ref:`devporting`.
+
 26.1.5. Modifying Runtime Data
 ******************************
 
@@ -44,34 +140,59 @@ Refer to: :ref:`devoopmodel_base`.
 - RuntimeAppend(Data)
 - XML-RPC Async Data
 
-26.1.6. Modifying Runtime Data
-******************************
+26.1.6. Updating Realtime Objects
+*********************************
+
+1. remove()
+2. removeParent()
+3. RTfunctions
+4. Examples
+
+26.1.7. Object Loading / Initialization
+***************************************
+
+1. init()
+
+26.1.8.Adding Context Menu Functionality
+****************************************
+
+1. Add Event Listener init()
+2. Setup Context Menu
+3. Eventually extend
 
-- Different approaches remove() and removeParent() + RTfunctions
 
 26.2. Building an Object Like sysObjDynRadioList.js
 ---------------------------------------------------
 
 This section explains how to create a dynamic system object similar to
-`sysObjDynRadioList.js` in the x0 framework. It focuses on the structure,
-methods, and key principles used in `sysObjDynRadioList`.
+``sysObjDynRadioList.js`` in the *x0-framework*. It focuses on the structure,
+methods, and key principles used in ``sysObjDynRadioList``.
+
+26.2.1. Overview
+****************
 
-- Overview
+The ``sysObjDynRadioList`` is a **dynamic object** designed to manage a list of
+**radio buttons**, with rows that can be added or removed at runtime. Each row
+includes a **radio button**, an **input field**, and **associated controls**.
 
-The sysObjDynRadioList is a dynamic object designed to manage a list of radio
-buttons, with rows that can be added or removed at runtime. Each row includes a
-radio button, an input field, and associated controls.
+26.2.2. Key Components
+**********************
 
-- Key Components:
+    1. Base Object Inheritance:
+        Inherits from ``sysBaseObject`` for core functionality.
+    2. Dynamic Rows:
+        Rows are represented by ``sysObjDynRadioListRow``, which also inherits from ``sysBaseObject``.
+    3. Callbacks and Events:
+        Used for adding/removing rows and handling user interactions.
+    4. JSON Configuration:
+        Utilized for defining object attributes and styles.
 
-    1. Base Object Inheritance: Inherits from sysBaseObject for core functionality.
-    2. Dynamic Rows: Rows are represented by sysObjDynRadioListRow, which also inherits from sysBaseObject.
-    3. Callbacks and Events: Used for adding/removing rows and handling user interactions.
-    4. JSON Configuration: Utilized for defining object attributes and styles.
+26.2.3. Step-by-Step Guide
+**************************
 
-- Step-by-Step Guide
+Following, a Step-by-Step Guide, guiding you through the creation process.
 
-26.2.1. Create the Base Class
+26.2.2. Create the Base Class
 *****************************
 
 Start by defining your main object, inheriting from sysBaseObject:
@@ -88,7 +209,7 @@ Start by defining your main object, inheriting from sysBaseObject:
     // Inherit from sysBaseObject
     sysObjDynRadioList.prototype = new sysBaseObject();
 
-26.2.2. Initialize the Object
+26.2.3. Initialize the Object
 *****************************
 
 Define the init method to set up the object structure and default components:
@@ -120,10 +241,11 @@ Define the init method to set up the object structure and default components:
         );
     };
 
-26.2.3. Define the Row Class
+26.2.4. Define the Row Class
 ****************************
 
-Each row in the list is represented by sysObjDynRadioListRow. This class manages its elements (radio button, input field, and optional remove button):
+Each row in the list is represented by ``sysObjDynRadioListRow``. This class manages its
+elements (radio button, input field, and optional remove button):
 
 .. code-block:: javascript
 
@@ -169,10 +291,10 @@ Each row in the list is represented by sysObjDynRadioListRow. This class manages
         }
     };
 
-26.2.4. Add Rows Dynamically
+26.2.5. Add Rows Dynamically
 ****************************
 
-The add method in sysObjDynRadioList creates new rows dynamically:
+The add method in ``sysObjDynRadioList`` creates new rows dynamically:
 
 .. code-block:: javascript
 
@@ -201,7 +323,7 @@ The add method in sysObjDynRadioList creates new rows dynamically:
         this.renderObject(this.DOMParentID);
     };
 
-26.2.5. Handle Row Removal
+26.2.6. Handle Row Removal
 **************************
 
 The remove method in sysObjDynRadioListRow is used to remove a row:
@@ -220,10 +342,10 @@ In the parent object, the remove method manages the array of rows:
         this.RowItems[RowIndex].remove();
     };
 
-26.2.6. Define Object Structure
+26.2.7. Define Object Structure
 *******************************
 
-Use the addObjects method to define the DOM structure for each row:
+Use the ``addObjects`` method to define the DOM structure for each row:
 
 .. code-block:: javascript
 
@@ -269,7 +391,7 @@ Use the addObjects method to define the DOM structure for each row:
         sysFactory.setupObjectRefsRecursive(ObjDefs, this);
     };
 
-26.2.7. Conclusion
+26.2.8. Conclusion
 ******************
 
 By following this guide, you can create dynamic objects similar to sysObjDynRadioList.js.

doc/dev-oop-classes.rst

@@ -8,19 +8,22 @@
 22.1. sysBaseObject.removeParent
 --------------------------------
 
-- Purpose
+22.1.1. Purpose
+***************
 
 The removeParent() method is used to remove an object's parent relationship and its
 associated DOM elements. This ensures that the object is detached from its parent both
 logically (in the object hierarchy) and visually (in the DOM).
 
-- Method Signature
+22.1.2. Method Signature
+************************
 
 .. code-block:: javascript
 
     sysBaseObject.prototype.removeParent = function()
 
-- How It Works
+22.1.3. How It Works
+********************
 
     * DOM Element Removal:
         Checks if the DOM element associated with the object exists.
@@ -33,7 +36,8 @@ logically (in the object hierarchy) and visually (in the DOM).
     * Error Handling:
         Catches and logs any errors that occur during the removal process.
 
-- Usage Example
+22.1.4. Usage Example
+*********************
 
 Suppose you have a hierarchical structure of objects (e.g., a parent object with multiple children).
 If you need to remove a parent object along with its DOM representation, you can call the removeParent() method.
@@ -44,7 +48,8 @@ If you need to remove a parent object along with its DOM representation, you can
     const parentObject = sysFactory.getObjectByID('parent-id');
     parentObject.removeParent();
 
-- Code Walkthrough
+22.1.5. Code Walkthrough
+************************
 
 .. code-block:: javascript
 
@@ -65,7 +70,8 @@ If you need to remove a parent object along with its DOM representation, you can
         }
     };
 
-- Key Points
+22.1.6. Key Points
+******************
 
     1. DOM Management:
         Ensures that any associated DOM elements are properly removed to avoid memory leaks.
@@ -76,7 +82,8 @@ If you need to remove a parent object along with its DOM representation, you can
     3. Error Resilience:
         Handles potential errors gracefully, ensuring that the application remains stable.
 
-- When to Use
+22.1.7. When to Use
+*******************
 
     - Use removeParent() when you need to:
         Detach an object and its associated DOM element from the object hierarchy.