Adapted Documentation

Author: cuioss

modules/cui-jsf-api/doc/components-decorator.adoc

@@ -73,115 +73,91 @@ Decorators are typically placed inside the component they should decorate:
 
 [source,xml]
 ----
-<h:panelGroup>
-    <cui:styleClassDecorator styleClass="panel panel-default"/>
-    Panel content here...
-</h:panelGroup>
+<h:commandButton value="Click Me">
+    <cui:tooltip title="Click this button to submit the form" placement="top"/>
+</h:commandButton>
 ----
 
-When the view is rendered, the decorator modifies its parent component (in this case, adding CSS classes to the `panelGroup`).
+When the view is rendered, the decorator modifies its parent component (in this case, adding tooltip functionality to the `commandButton`).
 
 == Common Decorator Types
 
-=== Style Class Decorators
+=== Tooltip Decorators
 
-Add CSS classes to the parent component:
+Add tooltip functionality to the parent component:
 
 [source,java]
 ----
-public class StyleClassDecorator extends AbstractParentDecorator {
+public class TooltipComponent extends AbstractParentDecorator {
 
-    private String styleClass;
+    private String placement;
+    private String trigger;
+    private Integer delay;
+    private String content;
 
     @Override
-    protected void decorate(UIComponent parent) {
-        ComponentModifier modifier = ComponentModifierFactory.findFittingWrapper(parent);
-        if (null != modifier) {
-            modifier.addStyleClass(parent, styleClass);
+    public void decorate(final ComponentModifier parent) {
+        parent.addPassThrough("data-placement", getPlacement())
+                .addPassThrough("data-toggle", "tooltip")
+                .addPassThrough("data-trigger", getTrigger())
+                .addPassThrough("data-delay", getDelay());
+
+        if (null != content) {
+            if (parent.isSupportsTitle()) {
+                parent.setTitle(content);
+            } else {
+                parent.addPassThrough("title", content);
+            }
         }
     }
 
     // Getters and setters...
 }
 ----
 
-=== Attribute Decorators
+=== Modal Control Decorators
 
-Set attributes on the parent component:
+Add modal dialog control functionality to the parent component:
 
 [source,java]
 ----
-public class AttributeDecorator extends AbstractParentDecorator {
+public class ModalControl extends AbstractParentDecorator {
 
-    private String name;
-    private Object value;
+    private String forId;
+    private String event;
+    private String action;
 
     @Override
-    protected void decorate(UIComponent parent) {
-        parent.getAttributes().put(name, value);
+    public void decorate(final ComponentModifier parent) {
+        parent.addPassThrough("data-modal-for", getFor())
+              .addPassThrough("data-modal-action", getAction())
+              .addPassThrough("data-modal-event", getEvent());
     }
 
     // Getters and setters...
 }
 ----
 
-=== Behavior Decorators
+=== Block Element Decorators
 
-Add behaviors to the parent component:
+Add block element functionality to the parent component:
 
 [source,java]
 ----
-public class AjaxDecorator extends AbstractParentDecorator {
-
-    private String event;
-    private String execute;
-    private String render;
+public class BlockElementDecorator extends AbstractParentDecorator {
 
     @Override
-    protected void decorate(UIComponent parent) {
-        if (parent instanceof ClientBehaviorHolder) {
-            ClientBehaviorHolder behaviorHolder = (ClientBehaviorHolder) parent;
-            AjaxBehavior behavior = createAjaxBehavior();
-            behaviorHolder.addClientBehavior(event, behavior);
-        }
+    public void decorate(ComponentModifier parent) {
+        parent.addPassThrough("data-cui-block-element", "data-cui-block-element");
     }
-
-    private AjaxBehavior createAjaxBehavior() {
-        // Create and configure the behavior
-        // ...
-    }
-
-    // Getters and setters...
 }
 ----
 
 == Examples from the Framework
 
 === TooltipComponent (Bootstrap Module)
 
-The link:https://github.com/cuioss/cui-jsf-components/blob/main/modules/cui-jsf-bootstrap/src/main/java/de/cuioss/jsf/bootstrap/tooltip/TooltipComponent.java[TooltipComponent] in the Bootstrap module is an example of a decorator that adds tooltip functionality to its parent component:
-
-[source,java]
-----
-public class TooltipComponent extends AbstractParentDecorator {
-
-    // Tooltip configuration properties...
-
-    @Override
-    protected void decorate(UIComponent parent) {
-        // Add tooltip-related attributes and behaviors to the parent
-        parent.getAttributes().put("data-toggle", "tooltip");
-        parent.getAttributes().put("data-placement", getPlacement());
-        parent.getAttributes().put("title", getTitle());
-
-        // Add necessary CSS classes
-        ComponentModifier modifier = ComponentModifierFactory.findFittingWrapper(parent);
-        if (null != modifier) {
-            modifier.addStyleClass(parent, "tooltip-enabled");
-        }
-    }
-}
-----
+The link:https://github.com/cuioss/cui-jsf-components/blob/main/modules/cui-jsf-bootstrap/src/main/java/de/cuioss/jsf/bootstrap/tooltip/TooltipComponent.java[TooltipComponent] in the Bootstrap module is a decorator that adds tooltip functionality to its parent component.
 
 Usage:
 
@@ -194,30 +170,42 @@ Usage:
 
 === ModalControl (Bootstrap Module)
 
-The link:https://github.com/cuioss/cui-jsf-components/blob/main/modules/cui-jsf-bootstrap/src/main/java/de/cuioss/jsf/bootstrap/modal/ModalControl.java[ModalControl] decorator adds modal dialog control functionality to buttons:
+The link:https://github.com/cuioss/cui-jsf-components/blob/main/modules/cui-jsf-bootstrap/src/main/java/de/cuioss/jsf/bootstrap/modal/ModalControl.java[ModalControl] decorator adds modal dialog control functionality to buttons.
 
-[source,java]
+Usage:
+
+[source,xml]
+----
+<h:commandButton value="Open Modal">
+    <cui:modalControl target="myModalId"/>
+</h:commandButton>
 ----
-public class ModalControl extends AbstractParentDecorator {
 
-    private String target;
+=== BlockElementDecorator (Core Components Module)
 
-    @Override
-    protected void decorate(UIComponent parent) {
-        // Add modal control attributes
-        parent.getAttributes().put("data-toggle", "modal");
-        parent.getAttributes().put("data-target", "#" + target);
-    }
-}
+The link:https://github.com/cuioss/cui-jsf-components/blob/main/modules/cui-jsf-core-components/src/main/java/de/cuioss/jsf/components/blockelement/BlockElementDecorator.java[BlockElementDecorator] adds functionality to disable a component and show a loading spinner during Ajax operations.
+
+Usage:
+
+[source,xml]
+----
+<boot:commandButton value="Submit">
+    <f:ajax render="@this"/>
+    <cui:blockElement/>
+</boot:commandButton>
 ----
 
+=== TypewatchComponent (Core Components Module)
+
+The link:https://github.com/cuioss/cui-jsf-components/blob/main/modules/cui-jsf-core-components/src/main/java/de/cuioss/jsf/components/typewatch/TypewatchComponent.java[TypewatchComponent] monitors user input and triggers an action after the user stops typing for a specified period.
+
 Usage:
 
 [source,xml]
 ----
-<h:commandButton value="Open Modal">
-    <cui:modalControl target="myModalId"/>
-</h:commandButton>
+<h:inputText value="#{bean.searchTerm}">
+    <cui:typewatch wait="500" listener="#{bean.search}"/>
+</h:inputText>
 ----
 
 == Implementation Guidelines

modules/cui-jsf-api/doc/components-partial.adoc

@@ -13,6 +13,7 @@ toc::[]
 == Overview
 
 The partial implementation pattern is a design approach that follows the composite pattern to create flexible and reusable JSF components. Instead of relying heavily on inheritance, which can lead to complex class hierarchies, this pattern uses composition to combine specific behaviors into complete components.
+Another commonly used Anti-Pattern for component design is copy-pasting.
 
 The `de.cuioss.jsf.api.components.partial` package contains provider interfaces and their implementations for common component attributes and behaviors. Many component implementations in the CUI JSF framework use these partial implementations to reduce code duplication and maintain consistency across the component library.
 
@@ -25,6 +26,7 @@ Provider interfaces define contracts for specific component behaviors. Each inte
 === Implementations
 
 Concrete implementations of these interfaces provide the actual behavior. These implementations typically use the `CuiState` helper to manage component state in a JSF-friendly way.
+`CuiState` extends OmniFaces's `StateHelper` and provides additional convenience methods for using component state.
 
 === Component Bridges
 

modules/cui-jsf-api/doc/components-renderer.adoc

@@ -189,7 +189,7 @@ public class ElementReplacingResponseWriter extends ResponseWriterBase {
 }
 ----
 
-This writer is often used to adapt standard JSF components to Bootstrap or other CSS frameworks that require specific HTML structures.
+This writer is used to adapt standard JSF components to Bootstrap or other CSS frameworks that require specific HTML structures.
 
 === ResponseWriterBase
 

modules/cui-jsf-api/doc/security-sanitization.adoc

@@ -14,6 +14,16 @@ toc::[]
 
 Web applications are vulnerable to Cross-Site Scripting (XSS) attacks when they display user-provided content without proper sanitization. The CUI JSF API provides a comprehensive set of tools to sanitize HTML content, preventing XSS vulnerabilities while allowing legitimate HTML formatting when needed.
 
+== JSF Default Escaping
+
+It's important to note that JSF, by design, provides default escaping for output, which helps prevent XSS attacks. However, it is still sensible to add sanitization as another line of defense, especially in the following scenarios:
+
+1. When other clients are working on the same data that might not have the same built-in protections
+2. When a developer explicitly sets `escape="false"` on JSF components
+3. As part of a defense-in-depth security strategy
+
+This multi-layered approach to security ensures that your application remains protected even if one layer is bypassed or disabled.
+
 == CuiSanitizer
 
 The `CuiSanitizer` enum is the core component of the security framework. It provides predefined sanitization policies based on the OWASP HTML Sanitizer library, offering different levels of HTML element and attribute filtering.
@@ -265,6 +275,7 @@ Some sanitizers preserve HTML entities, which can be useful for displaying speci
 
 Sanitization adds some processing overhead. For high-performance applications, consider caching sanitized content when appropriate.
 
+
 == Conclusion
 
 The CUI JSF API provides a comprehensive framework for HTML sanitization through the `CuiSanitizer` enum and corresponding converters. By using these tools consistently, you can protect your application from XSS attacks while still allowing rich HTML content when needed.