Viewer
Import and display CSV, XLSX/XLS, and PDF files as interactive tables, charts, calendars, and other visualizations in Drupal.
viewer
Install
composer require 'drupal/viewer:^1.0'
Overview
The Viewer module provides a comprehensive solution for importing, processing, and displaying structured and unstructured file types including CSV, XLSX/XLS, and PDF files. It enables content creators to present data from various sources directly on their Drupal sites without manual data entry.
The module features a flexible plugin architecture supporting multiple visualization types including tables (with Datatables and FooTable integration), various chart types (Chart.js and ApexCharts), calendar views (FullCalendar), and PDF previews (PDF.js). Data can be imported from multiple sources including manual file uploads, remote URLs, FTP/SFTP servers, or local file paths.
Viewers can be embedded into the site via reference fields, blocks, or CKEditor5 integration. The module supports automated data imports via cron with configurable schedules, data filtering with multiple criteria options, cell value converters, and notifications (Email and Slack) for import status updates.
Features
- Import CSV, XLSX/XLS, and PDF files from multiple sources (upload, URL, FTP, SFTP, file path)
- Display data as tables with multiple table library options (basic table, Datatables, FooTable)
- Create various chart types using Chart.js (Line, Bar, Pie/Doughnut, Scatter/Bubble, Mixed)
- Create various chart types using ApexCharts (Line, Bar, Pie/Doughnut, Scatter, Bubble, Treemap, Candlestick, Mixed)
- Calendar view integration with FullCalendar for date-based data
- PDF preview using PDF.js library
- Organize multiple viewers using Tabs, Vertical Tabs, or Accordion layouts
- Spreadsheet view for XLSX files with worksheet tab support
- Filter data using 15+ filter criteria (equals, greater than, contains, date comparisons, regex, etc.)
- Cell value converters (links, money formatting, percentage, images, inline Peity charts)
- Configure column visibility, headers, order via drag-and-drop
- Automated imports via cron with configurable frequencies (hourly, daily, weekly, monthly)
- Import notifications via Email and Slack webhooks
- Viewer reference field type for attaching viewers to content
- Block for placing viewers anywhere on the site
- CKEditor5 integration for embedding viewers in rich text fields
- REST API endpoint for fetching viewer data as JSON
- Drush command for running imports
Use Cases
Display Financial Reports
Import quarterly financial data from XLSX files and display as interactive charts. Use SFTP source to automatically pull reports from a secure server daily. Create multiple ApexCharts viewers (bar chart for revenue, line chart for trends) and organize them in tabs. Configure notifications to alert finance team via Slack when new data is imported.
Product Catalog from CSV
Display a product catalog from a CSV file exported from an ERP system. Use the Datatables viewer for searchable, sortable table with pagination. Configure cell converters to display product images inline and format prices as currency. Set up hourly imports from a URL to keep data current.
Event Calendar
Create an event calendar from CSV data with event titles and dates. Use the FullCalendar viewer to display events in a monthly calendar view. Configure title, start date, and end date column mappings. Import data from a shared Google Sheets CSV export URL.
Embedded Data Visualizations in Articles
Allow content editors to embed data visualizations in article content using CKEditor5. Enable the Viewer text filter and toolbar button. Editors can insert any configured viewer directly into article body text, making data storytelling seamless.
Dashboard with Multiple Data Sources
Create a dashboard page using multiple Viewer blocks. Display sales data as a bar chart, website traffic as a line chart, and inventory levels in a table. Each viewer can have its own data source and refresh schedule, all displayed together on a single page.
PDF Document Preview
Display PDF documents (contracts, reports, manuals) directly on content pages. Upload PDF files and configure the PDF.js viewer for inline preview. Users can view documents without downloading.
Tips
- Use the Tabs or Accordion viewers to organize multiple related visualizations on a single page without overwhelming users
- Configure appropriate cache tags are automatically applied; viewers update when source data changes
- For large datasets, use Datatables with server-side paging enabled for better performance
- Use token replacement in URL/Path sources (e.g., [date:custom:Y-m-d]) for date-based file imports
- Set up Slack notifications for failed imports to catch data pipeline issues early
- Preview viewers using the iframe preview before embedding to verify data display
- Use cell converters to enhance data presentation without modifying source files
- For financial data, combine ApexCharts Candlestick with date filters for time-series analysis
Technical Details
Admin Pages 10
/admin/structure/viewers
Main listing page showing all created Viewer entities. From here you can create new viewers, edit existing ones, configure settings, manage filters, preview viewers, enable/disable viewers, and delete viewers. Each viewer displays its name, status, associated source, and viewer type.
/admin/structure/viewer-source
Manage Viewer Source entities. Sources define where data comes from (upload, URL, FTP, SFTP, file path) and what type of file it is (CSV, XLSX, PDF). Sources can be shared across multiple viewers.
/admin/structure/viewers/{viewer}/edit
Edit basic viewer properties including name, status, and associated source.
/admin/structure/viewers/{viewer}/settings
Configure plugin-specific display settings. Settings vary by viewer type but commonly include title, subtitle, last import display options, pagination, and chart-specific options.
/admin/structure/viewers/{viewer}/configuration
Configure column-level settings including column order (via drag-and-drop), header overrides, visibility, empty column treatment, and cell value converters.
/admin/structure/viewers/{viewer}/filters
Configure data filters to limit which rows are displayed. Supports multiple filter criteria that can be combined.
/admin/structure/viewer-source/{viewer_source}/edit
Edit source properties including name and import frequency (for cron-enabled sources).
/admin/structure/viewer-source/{viewer_source}/schedule
Configure the next scheduled import time for automated imports.
/admin/structure/viewer-source/{viewer_source}/notifications
Configure notifications for import events. Supports both Email and Slack webhook notifications.
/admin/structure/viewer-support
Support page with information about the module, documentation links, and support options.
Permissions 13
Drush Commands 1
drush viewer:import
Run Viewer automated imports via Drush. Processes the queue of scheduled imports.
Troubleshooting 6
Install the required Flysystem SFTP adapter: composer require league/flysystem-sftp-v3
Install PhpSpreadsheet library: composer require phpoffice/phpspreadsheet
Check that the REST API endpoint is accessible. Verify the viewer has data by checking the source. Ensure JavaScript libraries are loading (check browser console for errors).
Verify cron is configured and running. Check the source has a frequency set (not 'Disabled'). Use 'drush viewer:import' to manually trigger imports and check for errors.
Verify notification settings are configured on the source. For email, check mail system is configured (consider using SMTP module). For Slack, verify the webhook URL is correct and the Slack app has proper permissions.
Enable the Viewer filter in your text format settings. Add the Viewer button to the CKEditor5 toolbar configuration. Clear caches after configuration changes.
Security Notes 4
- The 'administer viewer' and 'administer viewer source' permissions are marked as restricted and should only be granted to trusted administrators
- SFTP passwords are encrypted before storage using Drupal's encryption
- The REST API respects user permissions and cache contexts
- File uploads are validated against allowed extensions based on viewer type