document usage of events

docs/react-api/connection.md → docs/react-api/base.md

@@ -4,9 +4,13 @@ SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum hereon GmbH
 SPDX-License-Identifier: CC-BY-4.0
 -->
 
+(base-api)=
+
+# Basic interfaces
+
 (connection-api)=
 
-# Connection parameters
+## Connection parameters
 
 ```{eval-rst}
 .. autoclass:: ConnectionOptions
@@ -14,3 +18,12 @@ SPDX-License-Identifier: CC-BY-4.0
 
 .. autofunction:: getConnection
 ```
+
+(container-base-options-api)=
+
+## Container Base Options
+
+```{eval-rst}
+.. autoclass:: ContainerBaseOptions
+    :members:
+```

docs/react-api/index.md

@@ -21,7 +21,7 @@ This package exports three components:
 maxdepth: 1
 ---
 
-connection
+base
 module
 class
 function

docs/web-components/index.md

@@ -51,25 +51,40 @@ Here the {ref}`dasf-module` custom web component is used with a `websocket-url`
 and a `topic` that are used to create the connection to the message broker.
 Furthermore we have to load this libary in a `script` tag.
 
+### Custom response, error and progress handlers
+
 If we want to handle the response ourselve using the
-{attr}`~ModuleContainerOptions.onResponse` option, we have to create a global
-function and pass this to the `dasf-module` tag:
+{attr}`~ModuleContainerOptions.onResponse` option, we to listen to the
+`response` event of the custom web component. The response data can then be
+accessed via the `event.detail` attribute:
 
 ```html
 <script>
-  function showResponseInLog(response) {
-    console.log(response);
-    return true;
-  }
+  setTimeout(() => {
+    const element = document.querySelector('dasf-module');
+    element.addEventListener('response', (event) => {
+      console.log('received response', event.detail);
+    });
+  });
 </script>
 <dasf-module
   websocket-url="ws://<someserver>/ws"
   topic="sometopic"
-  onResponse="showResponseInLog"
 ></dasf-module>
 <script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
 ```
 
+The same works for the errors via the `error` event, and progress reports via
+the `progress` event.
+
+If we want to skip the default handling of response, error or progress reports,
+we can set the corresponding attribute out of `skip-default-response-handler`,
+`skip-default-error-handler` and `skip-default-progress-handler` or use the
+corresponding `...-check` functions for this. See the
+:class:`ContainerBaseOptions` for more information on these arguments..
+
+### Creating the connection via function
+
 When we want to create the connection ourselve as we may want to use it in
 several places, we have to create a function that returns the connection
 we created

src/resources/ContainerBaseOptions.ts

@@ -6,6 +6,15 @@ import { DASFProgressReport } from '@dasf/dasf-messaging';
 
 import { ConnectionOptions } from './connection';
 
+/** Base options for creating a container for a DASF module, class or function
+ *
+ * This interface holds the options for handling responses, errors and progress
+ * reports of the DASF backend module and serves as a basis for the
+ * :class:`FunctionContainerOptions`, :class:`ClassContainerOptions` and
+ * :class:`ModuleContainerOptions`.
+ *
+ * See also :class:`ConnectionOptions` for further options.
+ */
 export interface ContainerBaseOptions extends ConnectionOptions {
   /** Response handler for requests from the backend module.
    *