userDefinedResponse

instance.on('userDefinedResponse', (event, instance) => {
    // Log the received event for debugging purposes
    console.log('User-defined response received:', event.contentItem);
    
    // Render a custom HTML card with header, body, and footer sections
    // This approach is useful for displaying structured content like alerts, notifications, or custom cards
    // The event.hostElement is the DOM container where the custom content will be injected
    event.hostElement.innerHTML = `
        <div class="custom-response">
            <div class="custom-header">
                <h3>Custom Content</h3>
            </div>
            <div class="custom-body">
                <!-- Extract text from contentItem with fallback to default message if not present -->
                <p>${event.contentItem?.text || 'No content available'}</p>
            </div>
            <div class="custom-footer">
                <!-- Add interactive button that calls a custom handler function -->
                <button onclick="handleCustomAction()">Take Action</button>
            </div>
        </div>
    `;
});

/**
 * Handler for custom user-defined response types in the webchat.
 * This function processes widget data from tool responses and renders custom HTML.
 *
 * @param {Object} event - The userDefinedResponse event object containing message and content data
 * @param {Object} instance - The webchat instance for accessing chat functionality
 */
function userDefinedResponseHandler(event, instance) {
    console.log('userDefinedResponse event', event);
    
    // Extract widget data from multiple possible locations in the event object
    // The widget data can be stored in different places depending on how it was sent:
    // 1. event.contentItem.user_defined - Direct content item property
    // 2. event.message._meta['com.ibm.orchestrate/widget'].user_defined - Metadata property
    // 3. event.message._meta['com.ibm.orchestrate/widget'] - Root metadata if response_type is 'user_defined'
    const widgetMeta = event.message?._meta?.['com.ibm.orchestrate/widget'];
    const widgetData =
        event.contentItem?.user_defined ||
        widgetMeta?.user_defined ||
        (widgetMeta?.response_type === 'user_defined' ? widgetMeta : null);
    
    // Check if widget data was found in any of the possible locations
    if (widgetData) {
        console.log('Rendering widget from tool data:', widgetData);
        
        // Extract and normalize widget properties with fallback values
        // Each property checks the widget data and provides a sensible default if not present
        const title = widgetData.title || 'Default Custom Widget';
        const message = widgetData.text || widgetData.description || 'No content available';
        const widgetType = widgetData.user_defined_type || 'custom_component';
        
        // Convert timestamp to human-readable format if present, otherwise set to null
        const timestamp = widgetData.timestamp
            ? new Date(widgetData.timestamp).toLocaleString()
            : null;
        
        // Extract optional custom fields from the widget data
        const customField = widgetData.custom_field || null;
        
        // Determine if the widget should be interactive (strict boolean check)
        const interactive = widgetData.interactive === true;
        
        // Get the action URL for the button, defaulting to '#' if not provided
        const actionUrl = widgetData.action_url || '#';
        
        // Render the custom widget HTML with inline styles
        // This creates a styled card with gradient background, title, message content,
        // metadata display, and an interactive button
        event.hostElement.innerHTML = `
            <div style="border: 2px solid #667eea; border-radius: 8px; padding: 16px; background: linear-gradient(135deg, #667eea15 0%, #764ba215 100%);">
                <h3 style="color: #667eea; margin: 0 0 12px 0; font-size: 18px;">
                    🎨 ${title}
                </h3>
                <div style="background-color: #f0f4ff; color: #333; padding: 12px; border-radius: 6px; margin-bottom: 12px;">
                    <p style="margin: 0; font-weight: 600;">Message Content:</p>
                    <p style="margin: 8px 0 0 0;">${message}</p>
                </div>
                <div style="background-color: #fff; padding: 12px; border-radius: 6px; border-left: 4px solid #667eea;">
                    <p style="margin: 0 0 8px 0; font-size: 14px; color: #666;">
                        This widget is rendered in the browser from tool-provided structured data.
                    </p>
                    <p style="margin: 0; font-size: 12px; color: #666;">
                        <strong>Type:</strong> ${widgetType}
                        ${timestamp ? `<br><strong>Timestamp:</strong> ${timestamp}` : ''}
                        ${customField ? `<br><strong>Custom field:</strong> ${customField}` : ''}
                        <br><strong>Interactive:</strong> ${interactive ? 'Yes' : 'No'}
                    </p>
                </div>
                <button
                    type="button"
                    data-widget-link="${actionUrl}"
                    style="display: block; width: 100%; margin-top: 12px; padding: 10px; background: #764ba2; color: white; border: none; border-radius: 6px; cursor: pointer; font-size: 14px; font-weight: 600;"
                >
                    ✨ Fully Customizable Content ✨
                </button>
            </div>
        `;
        
        // Add event listeners for interactive button behavior
        // Query the DOM for the button element using its data attribute
        const actionButton = event.hostElement.querySelector('[data-widget-link]');
        if (actionButton) {
            // Click handler: Opens the action URL in a new tab if it's not the default '#'
            actionButton.addEventListener('click', () => {
                if (actionButton.dataset.widgetLink && actionButton.dataset.widgetLink !== '#') {
                    window.open(actionButton.dataset.widgetLink, '_blank');
                }
            });
            
            // Hover effect: Darken the button background on mouseover
            actionButton.addEventListener('mouseover', () => {
                actionButton.style.background = '#5a3a82';
            });
            
            // Hover effect: Restore original button background on mouseout
            actionButton.addEventListener('mouseout', () => {
                actionButton.style.background = '#764ba2';
            });
        }
        
        // Exit early since we successfully rendered the widget
        return;
    }
    
    // Fallback rendering when no widget data is found
    // This displays a simple orange box with any available text content
    console.log('No widget data found, using fallback rendering');
    event.hostElement.innerHTML = `
        <div style="background-color:orange;color:white;padding:10px;">
            <p>${event.contentItem?.text || '[No message content]'}</p>
        </div>
    `;
}

// Register the event handler with the webchat instance
// This tells the webchat to call userDefinedResponseHandler whenever a userDefinedResponse event occurs
instance.on('userDefinedResponse', userDefinedResponseHandler);