#atom

Subtitle:

Core methods and event listeners available for custom plugin development

Core Idea:

React PDF Viewer offers a comprehensive set of lifecycle methods and event listeners that plugins can implement to hook into different stages of the PDF rendering process, allowing developers to extend functionality at specific points in the document's lifecycle.

Key Principles:

1. Plugin Registration:
   • Plugins are registered through the install method when the viewer initializes
2. Event-Based Architecture:
   • Uses event listeners to respond to specific actions in the rendering pipeline
3. Layer-Specific Interactions:
   • Provides separate hooks for different PDF layers (canvas, text, annotation)

Why It Matters:

• Precision Control:
  • Enables interaction with specific parts of the PDF document at exact moments
• Performance Management:
  • Allows optimization by hooking into only necessary rendering events
• Extended Functionality:
  • Creates pathways for adding capabilities beyond the core viewer functionality

How to Implement:

1. Setup Method:
   • Implement install to access core functionality when plugin is registered
2. Choose Appropriate Listeners:
   • Select event listeners relevant to the plugin's purpose
3. Return Plugin Object:
   • Create a plugin object containing the implemented methods

Core Plugin Methods and Listeners:

1. Plugin Registration:

   • install(pluginFunctions: PluginFunctions): void
     • Called when the plugin is registered with the Viewer
     • Provides access to core viewer functions
     • Example parameters include getPagesContainer, getPageElement, jumpToPage, zoom

2. Viewer Rendering:

   • renderViewer(props: RenderViewer): Slot
     • Called when the viewer is about to be rendered
     • Allows modification of the viewer's structure
     • Parameters include current rendering slot information

3. Document Events:

   • onDocumentLoad(e: DocumentLoadEvent): void
     • Called when the document is fully loaded
     • Provides document object and file information
   • onPassword(props: PasswordProps): void
     • Called when a password-protected document is opened
     • Provides methods to verify and handle password entry

4. Page Events:

   • onPageChange(e: PageChangeEvent): void
     • Called when the current page changes
     • Provides current page index and document
   • onPageRender(e: PluginOnPageRender): void
     • Called when a page is rendered
     • Parameters include page index, dimensions, and rendering status

5. Layer Rendering Events:

   • onTextLayerRender(e: PluginOnTextLayerRender): void
     • Called when the text layer of a page is rendered
     • Provides page index, container element, and layer status
   • onCanvasLayerRender(e: PluginOnCanvasLayerRender): void
     • Called when the canvas layer is rendered
     • Parameters include canvas element, page index, scale, and status
   • onAnnotationLayerRender(e: PluginOnAnnotationLayerRender): void
     • Called when the annotation layer is rendered
     • Provides annotation data, container element, and status

6. User Interaction Events:

   • onRotate(e: RotateEvent): void
     • Called when the document is rotated
     • Provides rotation direction and value
   • onRotatePage(e: RotatePageEvent): void
     • Called when a specific page is rotated
     • Includes page index and rotation information
   • onZoom(e: ZoomEvent): void
     • Called when document zoom level changes
     • Provides new scale value

7. Custom Renderers:

   • renderProtectedView(props: RenderProtectedViewProps): React.ReactElement
     • Customizes the view for password-protected documents
   • renderError(error: Error): React.ReactElement
     • Customizes error display
   • renderLoader(percentages: number): React.ReactElement
     • Customizes the loading indicator
   • renderPage(props: RenderPageProps): React.ReactElement
     • Customizes how each page is rendered

Example:

• Scenario:
  • Creating a plugin that adds watermarks to each page and tracks viewing time
• Application:

const trackingWatermarkPlugin = (): Plugin => {
  // Track viewing time
  let startTime = new Date();
  
  return {
    install: (pluginFunctions) => {
      console.log('Plugin installed at', startTime);
    },
    
    onDocumentLoad: (e) => {
      console.log(`Document loaded: ${e.doc.numPages} pages`);
    },
    
    onCanvasLayerRender: (e) => {
      if (e.status === LayerRenderStatus.DidRender) {
        const canvas = e.ele;
        const ctx = canvas.getContext('2d');
        
        // Add watermark
        ctx.font = '20px Arial';
        ctx.fillStyle = 'rgba(200, 200, 200, 0.5)';
        ctx.fillText('CONFIDENTIAL', canvas.width / 2 - 60, canvas.height / 2);
      }
    },
    
    onPageChange: (e) => {
      const now = new Date();
      const timeSpent = (now.getTime() - startTime.getTime()) / 1000;
      console.log(`Viewed page ${e.currentPage} for ${timeSpent} seconds`);
      startTime = now;
    }
  };
};

• Result:
  • A plugin that adds watermarks to each page and logs the time spent on each page

Connections:

• Related Concepts:
  • 05 - Permanent/Atoms/React PDF Viewer Core: The foundation framework providing these hooks
  • React PDF Viewer Custom Plugins: Implementation patterns using these lifecycle methods
  • PDF.js Integration: Underlying technology that these methods interact with
• Broader Concepts:
  • Event-Driven Architecture: Pattern of responding to specific system events
  • React Component Lifecycle: Similar concept in React component development

References:

1. Primary Source:
   • React PDF Viewer Plugin Documentation
2. Additional Resources:
   • PDF.js Documentation: Layer rendering process
   • React Event Handling Documentation

Tags:

#react #pdf #plugin #lifecycle #events #hooks #rendering #custom-development

Connections:

Sources:

• From: Version1