@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/examples/integration-examples/custom-pcf-wrapper.tsx

@@ -0,0 +1,722 @@
+/**
+ * Example: Creating a custom PCF wrapper
+ *
+ * This example demonstrates how to create a sophisticated PCF wrapper
+ * that can be used in various Dynamics 365 contexts, with smart API
+ * service detection and comprehensive error handling.
+ *
+ * @example
+ * ```typescript
+ * // Use in your PCF component's init method
+ * export class CustomPCFControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
+ *   public init(context: ComponentFramework.Context<IInputs>): void {
+ *     ReactDOM.render(
+ *       React.createElement(CustomPCFWrapper, {
+ *         context,
+ *         entityType: 'contact',
+ *         enableLogging: true
+ *       }),
+ *       this.container
+ *     );
+ *   }
+ * }
+ * ```
+ */
+
+import React, { useState, useCallback, useEffect, useMemo } from 'react';
+import { ContactManagement } from '../../components/ContactManagement';
+import { AccountManagement } from '../../components/AccountManagement';
+import { DynamicsProvider } from '../../providers/DynamicsProvider';
+import { ServiceFactory } from '../../services/ServiceFactory';
+import { Logger } from '../../components/Logging/logger';
+import { LoggingProvider } from '../../components/Logging/LoggingProvider';
+
+/**
+ * PCF Context interface that matches ComponentFramework.Context
+ */
+interface PCFContextType {
+  /** PCF WebAPI object for Dynamics 365 operations */
+  webAPI: {
+    createRecord: (entityName: string, data: any) => Promise<any>;
+    retrieveRecord: (
+      entityName: string,
+      id: string,
+      select?: string
+    ) => Promise<any>;
+    updateRecord: (entityName: string, id: string, data: any) => Promise<any>;
+    deleteRecord: (entityName: string, id: string) => Promise<void>;
+    retrieveMultipleRecords: (
+      entityName: string,
+      query?: string
+    ) => Promise<any>;
+  };
+  /** PCF utility functions */
+  utils: {
+    lookupObjects: (lookupOptions: any) => Promise<any>;
+    openAlertDialog: (
+      alertStrings: any,
+      useShowModal?: boolean
+    ) => Promise<any>;
+    openConfirmDialog: (
+      confirmStrings: any,
+      useShowModal?: boolean
+    ) => Promise<any>;
+    openErrorDialog: (errorOptions: any) => Promise<any>;
+    openFileDialog: (fileOptions: any) => Promise<any>;
+    openUrl: (url: string, options?: any) => void;
+  };
+  /** PCF parameters */
+  parameters: {
+    [key: string]: any;
+  };
+  /** PCF mode information */
+  mode: {
+    isControlDisabled: boolean;
+    isVisible: boolean;
+    label: string;
+  };
+  /** PCF resources */
+  resources: {
+    getString: (id: string) => string;
+    getResource: (
+      id: string,
+      success: (data: string) => void,
+      failure?: () => void
+    ) => void;
+  };
+}
+
+/**
+ * Props for the CustomPCFWrapper component
+ */
+interface CustomPCFWrapperProps {
+  /** PCF context from the framework */
+  context: PCFContextType;
+  /** Entity type to manage ('contact' | 'account' | 'auto') */
+  entityType?: 'contact' | 'account' | 'auto';
+  /** Whether to enable comprehensive logging */
+  enableLogging?: boolean;
+  /** Whether to show tabs for multi-entity support */
+  showTabs?: boolean;
+  /** Custom title for the component */
+  title?: string;
+  /** Whether to enable debug mode */
+  debugMode?: boolean;
+}
+
+/**
+ * Custom PCF Wrapper Component
+ *
+ * A sophisticated wrapper that provides:
+ * - Smart API service creation with fallback handling
+ * - Environment detection and logging integration
+ * - Multi-entity support with dynamic switching
+ * - Error boundary and recovery mechanisms
+ * - Performance monitoring and optimization
+ *
+ * @param props - Component properties
+ * @returns JSX.Element
+ */
+export const CustomPCFWrapper: React.FC<CustomPCFWrapperProps> = ({
+  context,
+  entityType = 'auto',
+  enableLogging = true,
+  showTabs = true,
+  title,
+  debugMode = false,
+}) => {
+  const [selectedEntity, setSelectedEntity] = useState<'contact' | 'account'>(
+    'contact'
+  );
+  const [apiServiceReady, setApiServiceReady] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Initialize logging if enabled
+   */
+  useEffect(() => {
+    if (enableLogging) {
+      Logger.log('CustomPCFWrapper initialized', 'CustomPCFWrapper');
+      Logger.userAction(
+        'PCF component loaded',
+        {
+          entityType,
+          showTabs,
+          debugMode,
+          hasWebAPI: !!context.webAPI,
+        },
+        'CustomPCFWrapper'
+      );
+    }
+  }, [enableLogging, entityType, showTabs, debugMode, context.webAPI]);
+
+  /**
+   * Create API service with comprehensive error handling and fallbacks
+   */
+  const apiService = useMemo(() => {
+    try {
+      // Check if we're in PCF context with webAPI available
+      if (context.webAPI) {
+        if (enableLogging) {
+          Logger.log(
+            'PCF WebAPI available, creating custom PCF API service',
+            'CustomPCFWrapper'
+          );
+        }
+
+        // Create a comprehensive API service that uses PCF's webAPI
+        return {
+          /**
+           * Create a new record using PCF WebAPI
+           */
+          createRecord: async (entityName: string, data: any) => {
+            try {
+              if (enableLogging) {
+                Logger.apiOperation(
+                  'CREATE',
+                  entityName,
+                  data,
+                  'CustomPCFWrapper.createRecord'
+                );
+              }
+              const result = await context.webAPI.createRecord(
+                entityName,
+                data
+              );
+              if (enableLogging) {
+                Logger.log(
+                  `Successfully created ${entityName} record`,
+                  'CustomPCFWrapper.createRecord'
+                );
+              }
+              return result;
+            } catch (error) {
+              if (enableLogging) {
+                Logger.error(
+                  `Failed to create ${entityName} record`,
+                  'CustomPCFWrapper.createRecord',
+                  error
+                );
+              }
+              throw error;
+            }
+          },
+
+          /**
+           * Retrieve a single record by ID
+           */
+          retrieveRecord: async (
+            entityName: string,
+            id: string,
+            select?: string
+          ) => {
+            try {
+              if (enableLogging) {
+                Logger.apiOperation(
+                  'READ',
+                  entityName,
+                  { id, select },
+                  'CustomPCFWrapper.retrieveRecord'
+                );
+              }
+              const result = await context.webAPI.retrieveRecord(
+                entityName,
+                id,
+                select
+              );
+              if (enableLogging) {
+                Logger.log(
+                  `Successfully retrieved ${entityName} record`,
+                  'CustomPCFWrapper.retrieveRecord'
+                );
+              }
+              return result;
+            } catch (error) {
+              if (enableLogging) {
+                Logger.error(
+                  `Failed to retrieve ${entityName} record`,
+                  'CustomPCFWrapper.retrieveRecord',
+                  error
+                );
+              }
+              throw error;
+            }
+          },
+
+          /**
+           * Update an existing record
+           */
+          updateRecord: async (entityName: string, id: string, data: any) => {
+            try {
+              if (enableLogging) {
+                Logger.apiOperation(
+                  'UPDATE',
+                  entityName,
+                  { id, data },
+                  'CustomPCFWrapper.updateRecord'
+                );
+              }
+              const result = await context.webAPI.updateRecord(
+                entityName,
+                id,
+                data
+              );
+              if (enableLogging) {
+                Logger.log(
+                  `Successfully updated ${entityName} record`,
+                  'CustomPCFWrapper.updateRecord'
+                );
+              }
+              return result;
+            } catch (error) {
+              if (enableLogging) {
+                Logger.error(
+                  `Failed to update ${entityName} record`,
+                  'CustomPCFWrapper.updateRecord',
+                  error
+                );
+              }
+              throw error;
+            }
+          },
+
+          /**
+           * Delete a record
+           */
+          deleteRecord: async (entityName: string, id: string) => {
+            try {
+              if (enableLogging) {
+                Logger.apiOperation(
+                  'DELETE',
+                  entityName,
+                  { id },
+                  'CustomPCFWrapper.deleteRecord'
+                );
+              }
+              await context.webAPI.deleteRecord(entityName, id);
+              if (enableLogging) {
+                Logger.log(
+                  `Successfully deleted ${entityName} record`,
+                  'CustomPCFWrapper.deleteRecord'
+                );
+              }
+            } catch (error) {
+              if (enableLogging) {
+                Logger.error(
+                  `Failed to delete ${entityName} record`,
+                  'CustomPCFWrapper.deleteRecord',
+                  error
+                );
+              }
+              throw error;
+            }
+          },
+
+          /**
+           * Retrieve multiple records using FetchXML
+           */
+          retrieveMultipleRecords: async (
+            entityName: string,
+            fetchXml: string
+          ) => {
+            try {
+              if (enableLogging) {
+                Logger.fetchXml(
+                  fetchXml,
+                  'CustomPCFWrapper.retrieveMultipleRecords'
+                );
+              }
+              const encodedFetchXml = encodeURIComponent(fetchXml);
+              const result = await context.webAPI.retrieveMultipleRecords(
+                entityName,
+                `?fetchXml=${encodedFetchXml}`
+              );
+              if (enableLogging) {
+                Logger.log(
+                  `Successfully retrieved ${result.entities?.length || 0} ${entityName} records`,
+                  'CustomPCFWrapper.retrieveMultipleRecords'
+                );
+              }
+              return result;
+            } catch (error) {
+              if (enableLogging) {
+                Logger.error(
+                  `Failed to retrieve ${entityName} records`,
+                  'CustomPCFWrapper.retrieveMultipleRecords',
+                  error
+                );
+              }
+              throw error;
+            }
+          },
+
+          /**
+           * Execute custom request (not supported in PCF WebAPI)
+           */
+          executeRequest: async (requestName: string, requestData: any) => {
+            const errorMessage = `Custom requests not supported in PCF WebAPI: ${requestName}`;
+            if (enableLogging) {
+              Logger.warn(errorMessage, 'CustomPCFWrapper.executeRequest');
+            }
+            throw new Error(errorMessage);
+          },
+
+          /**
+           * Upload file (not supported in PCF WebAPI)
+           */
+          uploadFile: async (file: File) => {
+            const errorMessage = 'File upload not supported in PCF WebAPI';
+            if (enableLogging) {
+              Logger.warn(errorMessage, 'CustomPCFWrapper.uploadFile');
+            }
+            throw new Error(errorMessage);
+          },
+        };
+      }
+
+      // Fallback to ServiceFactory for environment detection
+      if (enableLogging) {
+        Logger.log(
+          'PCF WebAPI not available, falling back to ServiceFactory',
+          'CustomPCFWrapper'
+        );
+      }
+
+      const xrmGlobal = ServiceFactory.isDynamics365Context()
+        ? (window as any).Xrm
+        : undefined;
+      return ServiceFactory.createApiService(xrmGlobal);
+    } catch (error) {
+      const errorMessage = 'Failed to create API service in PCF context';
+      if (enableLogging) {
+        Logger.error(errorMessage, 'CustomPCFWrapper', error);
+      }
+      setError(errorMessage);
+      return null;
+    }
+  }, [context.webAPI, enableLogging]);
+
+  /**
+   * Set API service ready state
+   */
+  useEffect(() => {
+    setApiServiceReady(!!apiService);
+  }, [apiService]);
+
+  /**
+   * Determine which entity to show based on entityType prop
+   */
+  useEffect(() => {
+    if (entityType === 'auto') {
+      // Auto-detect based on form context if available
+      // This is a simplified example - in practice, you'd check context.parameters
+      setSelectedEntity('contact');
+    } else {
+      setSelectedEntity(entityType);
+    }
+  }, [entityType]);
+
+  /**
+   * Handle entity tab change
+   */
+  const handleEntityChange = useCallback(
+    (newEntity: 'contact' | 'account') => {
+      if (enableLogging) {
+        Logger.userAction(
+          'Entity tab changed in PCF wrapper',
+          { from: selectedEntity, to: newEntity },
+          'CustomPCFWrapper.handleEntityChange'
+        );
+      }
+      setSelectedEntity(newEntity);
+    },
+    [selectedEntity, enableLogging]
+  );
+
+  /**
+   * Render the appropriate management component
+   */
+  const renderManagementComponent = () => {
+    if (!apiServiceReady) {
+      return (
+        <div style={{ padding: '20px', textAlign: 'center' }}>
+          <div>Loading...</div>
+          {debugMode && (
+            <div style={{ marginTop: '10px', fontSize: '12px', color: '#666' }}>
+              Initializing API service...
+            </div>
+          )}
+        </div>
+      );
+    }
+
+    switch (selectedEntity) {
+      case 'contact':
+        return <ContactManagement />;
+      case 'account':
+        return <AccountManagement />;
+      default:
+        return <ContactManagement />;
+    }
+  };
+
+  /**
+   * Render error boundary
+   */
+  if (error) {
+    return (
+      <div
+        style={{
+          padding: '20px',
+          border: '1px solid #d13438',
+          borderRadius: '4px',
+          backgroundColor: '#fef7f1',
+          color: '#d13438',
+        }}
+      >
+        <h3>PCF Integration Error</h3>
+        <p>{error}</p>
+        {debugMode && (
+          <details style={{ marginTop: '10px' }}>
+            <summary>Debug Information</summary>
+            <pre style={{ fontSize: '12px', marginTop: '10px' }}>
+              {JSON.stringify(
+                {
+                  hasWebAPI: !!context.webAPI,
+                  hasUtils: !!context.utils,
+                  hasParameters: !!context.parameters,
+                  entityType,
+                  enableLogging,
+                  showTabs,
+                },
+                null,
+                2
+              )}
+            </pre>
+          </details>
+        )}
+      </div>
+    );
+  }
+
+  /**
+   * Container styles
+   */
+  const containerStyle: React.CSSProperties = {
+    width: '100%',
+    height: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: '"Segoe UI", Tahoma, Arial, sans-serif',
+  };
+
+  const tabContainerStyle: React.CSSProperties = {
+    borderBottom: '1px solid #edebe9',
+    backgroundColor: '#faf9f8',
+  };
+
+  const tabStyle: React.CSSProperties = {
+    display: 'inline-block',
+    padding: '8px 16px',
+    cursor: 'pointer',
+    borderBottom: '2px solid transparent',
+    fontSize: '14px',
+  };
+
+  const activeTabStyle: React.CSSProperties = {
+    ...tabStyle,
+    borderBottomColor: '#0078d4',
+    backgroundColor: 'white',
+    fontWeight: '600',
+  };
+
+  const contentStyle: React.CSSProperties = {
+    flex: 1,
+    overflow: 'auto',
+    backgroundColor: 'white',
+  };
+
+  return (
+    <DynamicsProvider customApiService={apiService || undefined}>
+      {enableLogging ? (
+        <LoggingProvider>
+          <div style={containerStyle}>
+            {/* Title */}
+            {title && (
+              <div
+                style={{
+                  padding: '12px 16px',
+                  borderBottom: '1px solid #edebe9',
+                }}
+              >
+                <h3 style={{ margin: 0, fontSize: '16px', fontWeight: '600' }}>
+                  {title}
+                </h3>
+              </div>
+            )}
+
+            {/* Tabs */}
+            {showTabs && (entityType === 'auto' || showTabs) && (
+              <div style={tabContainerStyle}>
+                <div
+                  style={
+                    selectedEntity === 'contact' ? activeTabStyle : tabStyle
+                  }
+                  onClick={() => handleEntityChange('contact')}
+                >
+                  Contacts
+                </div>
+                <div
+                  style={
+                    selectedEntity === 'account' ? activeTabStyle : tabStyle
+                  }
+                  onClick={() => handleEntityChange('account')}
+                >
+                  Accounts
+                </div>
+              </div>
+            )}
+
+            {/* Content */}
+            <div style={contentStyle}>{renderManagementComponent()}</div>
+
+            {/* Debug Info */}
+            {debugMode && (
+              <div
+                style={{
+                  padding: '8px',
+                  borderTop: '1px solid #edebe9',
+                  backgroundColor: '#f3f2f1',
+                  fontSize: '11px',
+                  color: '#666',
+                }}
+              >
+                Debug: {ServiceFactory.getEnvironmentType()} | API Ready:{' '}
+                {apiServiceReady ? 'Yes' : 'No'}
+              </div>
+            )}
+          </div>
+        </LoggingProvider>
+      ) : (
+        <div style={containerStyle}>
+          {/* Same structure but without LoggingProvider */}
+          {title && (
+            <div
+              style={{
+                padding: '12px 16px',
+                borderBottom: '1px solid #edebe9',
+              }}
+            >
+              <h3 style={{ margin: 0, fontSize: '16px', fontWeight: '600' }}>
+                {title}
+              </h3>
+            </div>
+          )}
+
+          {showTabs && (
+            <div style={tabContainerStyle}>
+              <div
+                style={selectedEntity === 'contact' ? activeTabStyle : tabStyle}
+                onClick={() => handleEntityChange('contact')}
+              >
+                Contacts
+              </div>
+              <div
+                style={selectedEntity === 'account' ? activeTabStyle : tabStyle}
+                onClick={() => handleEntityChange('account')}
+              >
+                Accounts
+              </div>
+            </div>
+          )}
+
+          <div style={contentStyle}>{renderManagementComponent()}</div>
+
+          {debugMode && (
+            <div
+              style={{
+                padding: '8px',
+                borderTop: '1px solid #edebe9',
+                backgroundColor: '#f3f2f1',
+                fontSize: '11px',
+                color: '#666',
+              }}
+            >
+              Debug: {ServiceFactory.getEnvironmentType()} | API Ready:{' '}
+              {apiServiceReady ? 'Yes' : 'No'}
+            </div>
+          )}
+        </div>
+      )}
+    </DynamicsProvider>
+  );
+};
+
+/**
+ * Export for PCF integration
+ * This is the main export that should be used in PCF components
+ */
+export default CustomPCFWrapper;
+
+/**
+ * Example PCF Control Implementation
+ *
+ * This shows how to use the CustomPCFWrapper in a real PCF component.
+ * Copy this pattern to your PCF project's index.ts file.
+ */
+export const examplePCFImplementation = `
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import { CustomPCFWrapper } from './CustomPCFWrapper';
+
+export class CustomPCFControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
+  private container: HTMLDivElement;
+  private notifyOutputChanged: () => void;
+
+  public init(
+    context: ComponentFramework.Context<IInputs>,
+    notifyOutputChanged: () => void,
+    state: ComponentFramework.Dictionary,
+    container: HTMLDivElement
+  ): void {
+    this.container = container;
+    this.notifyOutputChanged = notifyOutputChanged;
+
+    // Render the CustomPCFWrapper
+    ReactDOM.render(
+      React.createElement(CustomPCFWrapper, {
+        context,
+        entityType: 'auto', // or 'contact', 'account'
+        enableLogging: true,
+        showTabs: true,
+        title: 'Customer Management',
+        debugMode: false // Set to true for development
+      }),
+      this.container
+    );
+  }
+
+  public updateView(context: ComponentFramework.Context<IInputs>): void {
+    // Re-render if needed
+    ReactDOM.render(
+      React.createElement(CustomPCFWrapper, {
+        context,
+        entityType: 'auto',
+        enableLogging: true,
+        showTabs: true,
+        title: 'Customer Management',
+        debugMode: false
+      }),
+      this.container
+    );
+  }
+
+  public getOutputs(): IOutputs {
+    return {};
+  }
+
+  public destroy(): void {
+    ReactDOM.unmountComponentAtNode(this.container);
+  }
+}
+`;