universal_dockit 1.0.0

A Flutter plugin for viewing PDF, Word, Excel, PowerPoint, EPUB, CBZ, TXT, CSV, RTF, and OpenDocument files on Android and iOS.

Universal Dockit 🗂️

⚠️ Notice: This plugin is currently under Beta version. APIs, UI, and rendering behavior may change as we continue to improve support for various document types.

A powerful, high-performance Flutter plugin for viewing a wide variety of documents natively on Android and iOS.

Universal Dockit leverages the best open-source native SDKs and built-in OS frameworks to render documents quickly and beautifully, keeping the Flutter layer minimal and efficient.

Absolutely no commercial dependencies, no cloud processing, and 100% on-device rendering.

---

✨ Features

• Universal Format Support: Open 15 different document types including PDF, Word, Excel, PowerPoint, EPUB, CBZ, Text, CSV, RTF, and OpenDocument formats.
• Native Performance: Documents are rendered natively using optimized libraries like PdfiumAndroid on Android and PDFKit/QuickLook on iOS.
• Format-Specific Themes: Beautiful, color-coded native headers (e.g., Blue for Word, Green for Excel, Purple for EPUB) provide a cohesive, premium UI out-of-the-box.
• Smart Rendering: Formula evaluation in spreadsheets, native zooming and scrolling for PDFs, and HTML structural extraction for E-Books and Comic Books.
• Fully Offline: Everything is parsed and rendered entirely on the device without cloud APIs or heavy monolithic frameworks.

---

📄 Supported Formats & Native Renderers

The plugin intelligently routes each file type to the most appropriate native renderer:

Format	Extension	Android Engine	iOS Engine
PDF	.pdf	PdfiumAndroid (Hardware accelerated)	PDFKit (Built-in)
Word (doc, docx)	.doc, .docx	Apache POI → Paragraph HTML → WebView	QuickLook (Built-in)
Excel (xls, xlsx)	.xls, .xlsx	Apache POI → HTML Table → WebView	CoreXLSX → HTML Table → WebView
PowerPoint (ppt, pptx)	.ppt, .pptx	Apache POI → Text/HTML Slides → WebView	QuickLook (Built-in)
EPUB E-Book	.epub	Native ZIP → spine/HTML extraction → WebView	ZIPFoundation → spine/HTML → WebView
CBZ Comic Book	.cbz	Native ZIP → Image extraction → WebView	ZIPFoundation → Image extraction → WebView
Text	.txt	Native TextView (Monospace, memory-efficient)	Native UITextView (Monospace)
CSV	.csv	RFC-4180 Parser → HTML Table → WebView	Aligned Plain-text Table → UITextView
Rich Text	.rtf	Native HTML Parser → Html.fromHtml → TextView	NSAttributedString → UITextView
OpenDocument	.odt, .ods, .odp	In-house ZIP/XML Parser → HTML → WebView	QuickLook (Built-in)

---

🛠 Setup & Installation

Requirements:

• Flutter SDK: >=3.10.0
• Dart SDK: >=3.0.0 <4.0.0

Add universal_dockit to your pubspec.yaml:

dependencies:
  universal_dockit: ^1.0.0

🤖 Android Setup

1. Minimum SDK: Ensure your minSdkVersion is at least 24 in android/app/build.gradle.
2. MultiDex: Apache POI is a large library. Ensure multiDexEnabled true is set in your app's build.gradle (usually enabled by default on modern Flutter versions).

Because the plugin handles the heavy lifting with its own build.gradle.kts, you don't need to add any specific repository exclusions manually in your app module.

🍎 iOS Setup

1. Minimum iOS Version: Ensure your iOS deployment target is at least iOS 13.4 in your ios/Podfile:

   platform :ios, '13.4'
   

2. Install Pods: Run the following from your ios directory:

   pod install
   

(Note: The iOS implementation uses pure Swift libraries and built-in Apple frameworks like QuickLook and PDFKit).

---

🚀 Usage

Using the plugin is incredibly simple. Just provide the absolute file path to the document.

import 'package:flutter/material.dart';
import 'package:universal_dockit/universal_dockit.dart';

// ... inside your widget class

final _universalDockitPlugin = UniversalDockit();

Future<void> openMyDocument(String filePath) async {
  try {
    // The plugin will automatically infer the document type from the extension.
    final success = await _universalDockitPlugin.openDocument(filePath);
    
    if (!success) {
      debugPrint("Could not open the document.");
    }
  } catch (e) {
    debugPrint("Error opening document: $e");
  }
}

// Alternatively, you can explicitly provide the document type:
// await _universalDockitPlugin.openDocument(filePath, docType: DocType.pdf);

Explicit Document Types

If your file doesn't have an extension, or you want to force a specific renderer, you can pass the DocType enum explicitly:

await _universalDockitPlugin.openDocument(
  '/path/to/file_without_extension', 
  docType: DocType.docx,
);

Supported DocType values: pdf, doc, docx, xls, xlsx, ppt, pptx, epub, cbz, txt, csv, rtf, odt, ods, odp.

Configuring Document Features

You can configure exactly which features are enabled in the native viewer by passing a DocumentFeatures object. The plugin uses a single unified configuration—any features that are applicable to the document being opened will be applied automatically, while non-applicable features are safely ignored.

await _universalDockitPlugin.openDocument(
  filePath,
  features: const DocumentFeatures(
    openLocalFile: true,
    openFromUrl: true,
    zoomInOut: true,
    search: true,
    shareDocument: true,
    fileInformation: true,
    offlineViewing: true,
    darkMode: true, // Enable native dark mode rendering
    
    // The following features will be applied only if the current 
    // document format supports them natively:
    pageNavigation: true,
    sheetNavigation: true,
    slideNavigation: true,
    thumbnails: true,
    textSelection: true,
    richTextRendering: true,
    renderImages: true,
    renderTables: true,
    renderHyperlinks: true,
    cellFormatting: true,
    freezePanes: true,
    wordWrap: true,
    cssSupport: true,
  ),
);

---

🏗 Architecture Under the Hood

To keep the codebase maintainable and performant, the native code is split using the Strategy Pattern:

• Android: DocumentViewerActivity acts as a host and dispatches rendering to specific consolidated implementations of DocumentRenderer (e.g., WordDocumentRenderer, ExcelDocumentRenderer, EpubDocumentRenderer). Communication is handled via a RenderCallbacks interface.
• iOS: UniversalDockitPlugin.swift routes requests to dedicated UIViewController subclasses (e.g., PDFViewerViewController, XLSXViewerViewController, EpubViewerViewController).

---

🤝 Contributing and Feedback

We welcome contributions and feedback! Here’s how you can help:

🐛 Reporting Bugs

If you find a bug, please open an issue with:

• A clear description of the problem.
• Steps to reproduce the issue.
• The document format (e.g., PDF, DOCX) causing the issue.
• Your Flutter version and the platform (Android/iOS) where the issue occurs.

💡 Requesting Features

Feature requests are always welcome! If there's a specific document format, UI feature, or performance enhancement you'd like to see:

• Open an issue outlining your feature request.
• Describe the use case and why it would be helpful.

🛠️ Contributing Code

We love pull requests! If you'd like to contribute directly to the code:

1. Fork the repository.
2. Create a new branch for your feature or bugfix (git checkout -b feature/my-new-feature).
3. Commit your changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/my-new-feature).
5. Open a Pull Request.

Please ensure your code follows standard Flutter linting rules.

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Open-source libraries used internally:

• PdfiumAndroid (Apache 2.0)
• Apache POI (Apache 2.0)
• CoreXLSX (Apache 2.0)
• ZIPFoundation (MIT)