Viewer Component in CargoXplorer TMS

Introduction

The Viewer Component is a specialized display component in CargoXplorer TMS designed for viewing documents and images directly within the application. It supports PDF files and various image formats, providing a seamless document viewing experience without requiring external applications or downloads. The component includes optional download functionality for enhanced user control.

YAML Structure

component: viewer
permission: "TMS/Documents/View" # optional
isVisible: true # optional
isHidden: false # optional
props:
  url: "{{ documentUrl }}"
  type: "pdf" # optional, auto-detected if omitted
  options:
    enableDownload: true
    fileName: "document.pdf"
    title: "Document Viewer"

Attribute Description

Props

url (string, required):

The URL of the document or image to be displayed. Supports template expressions for dynamic content.
```
url: "https://example.com/documents/invoice.pdf"
# or with variable
url: "{{ myForm.documentUrl }}"
```
type (string, optional):

Specifies the type of content to display. If not provided, the type is automatically detected from the file extension.

Supported values:
- pdf - For PDF documents
- image - For image files
```
type: "pdf"
```
options (object, optional):

Additional configuration options for the viewer behavior and appearance.
- enableDownload (boolean): When set to true, displays a download button in the viewer toolbar. Defaults to false.
```
enableDownload: true
```
- fileName (string): The name to use when downloading the file. If not provided, the filename is extracted from the URL.
```
fileName: "Invoice_2024_001.pdf"
```
- title (string or object): Title displayed in the viewer header. Supports localization.
```
title: "Document Preview"
# or localized
title:
  en-US: "Document Preview"
  es-ES: "Vista previa del documento"
```
- height (string): CSS height value for the viewer. Defaults to "600px".
```
height: "100vh"
```
- width (string): CSS width value for the viewer. Defaults to "100%".
```
width: "800px"
```

Common Attributes

permission (string, optional):

Specifies the permission required to view the document. If the user lacks the necessary permission, the viewer will not be rendered.
```
permission: "TMS/Documents/View"
```
isVisible (boolean, optional):

Controls the visibility of the viewer. When set to false, the viewer is not rendered.
```
isVisible: "{{ eval documentUrl !== null }}"
```
isHidden (boolean, optional):

Hides the viewer from the UI without removing it from the DOM.
```
isHidden: false
```

Supported File Types

PDF Documents

.pdf - Portable Document Format

The PDF viewer provides native rendering capabilities with zoom controls, page navigation, and optional download functionality.

Image Formats

.jpg, .jpeg - JPEG images
.png - Portable Network Graphics
.gif - Graphics Interchange Format
.bmp - Bitmap images
.svg - Scalable Vector Graphics
.webp - WebP images

Images are displayed with responsive sizing and optional download capability.

Examples

Basic PDF Viewer

A simple PDF viewer displaying a document from a URL.

component: viewer
props:
  url: "https://example.com/documents/invoice.pdf"
  type: "pdf"

PDF Viewer with Download Option

A PDF viewer with download functionality enabled and a custom filename.

component: viewer
props:
  url: "{{ store.currentInvoiceUrl }}"
  type: "pdf"
  options:
    enableDownload: true
    fileName: "Invoice_{{ store.invoiceNumber }}.pdf"
    title: "Invoice Document"
    height: "800px"

Image Viewer

Display an image with download option.

component: viewer
props:
  url: "{{ myForm.shipmentPhotoUrl }}"
  type: "image"
  options:
    enableDownload: true
    fileName: "Shipment_Photo_{{ myForm.shipmentId }}.jpg"
    title: "Shipment Documentation Photo"

Dynamic Type Detection

Let the viewer automatically detect the file type from the URL extension.

component: viewer
props:
  url: "{{ document.url }}"
  options:
    enableDownload: true
    fileName: "{{ document.fileName }}"
    title: "{{ document.title }}"

Conditional Viewer Display

Show the viewer only when a document URL is available.

component: viewer
isVisible: "{{ eval myForm.attachmentUrl !== null && myForm.attachmentUrl !== '' }}"
props:
  url: "{{ myForm.attachmentUrl }}"
  options:
    enableDownload: true
    title: "Attachment Preview"

Full-Screen Document Viewer

Display a document in full viewport height.

component: viewer
props:
  url: "{{ shipment.bolUrl }}"
  type: "pdf"
  options:
    enableDownload: true
    fileName: "BOL_{{ shipment.number }}.pdf"
    title:
      en-US: "Bill of Lading"
      es-ES: "Conocimiento de Embarque"
    height: "100vh"
    width: "100%"

Viewer with Permissions

Restrict document viewing based on user permissions.

component: viewer
permission: "TMS/Documents/ViewConfidential"
props:
  url: "{{ confidentialDoc.url }}"
  type: "pdf"
  options:
    enableDownload: false
    title: "Confidential Document"

Data Grid Integration

Use the viewer component within a data grid to display documents inline or in a dialog.

component: dataGrid
props:
  columns:
    - field: documentName
      headerName: "Document"
    - field: documentUrl
      headerName: "Preview"
      renderCell:
        component: button
        props:
          text: "View"
          onClick:
            - dialog:
                name: documentViewer
                props:
                  title: "{{ row.documentName }}"
                component:
                  component: viewer
                  props:
                    url: "{{ row.documentUrl }}"
                    options:
                      enableDownload: true
                      fileName: "{{ row.documentName }}"

Multiple Document Types

Handle different document types dynamically based on file extension.

component: layout
props:
  children:
    - component: text
      props:
        type: "h3"
        value: "Document Preview"
    - component: viewer
      props:
        url: "{{ documentLibrary.selectedDocument.url }}"
        options:
          enableDownload: true
          fileName: "{{ documentLibrary.selectedDocument.name }}"
          title: "{{ documentLibrary.selectedDocument.description }}"
          height: "700px"

Viewer with Loading State

Display a viewer with conditional rendering based on data availability.

component: layout
props:
  children:
    - component: text
      isVisible: "{{ eval !store.documentLoaded }}"
      props:
        value: "Loading document..."
    - component: viewer
      isVisible: "{{ eval store.documentLoaded }}"
      props:
        url: "{{ store.documentUrl }}"
        options:
          enableDownload: true
          title: "Loaded Document"

Best Practices

File Type Handling

Always ensure the URL points to a valid and accessible document or image file.
Use the type attribute explicitly when the file extension might be ambiguous or when dealing with dynamically generated content.
Implement error handling in your workflows to gracefully manage cases where documents are unavailable.

Download Functionality

Enable downloads (enableDownload: true) for documents that users may need to save locally or share externally.
Provide meaningful filenames using the fileName option to improve user experience and document organization.
Consider disabling downloads for sensitive or confidential documents to maintain security.

Performance Considerations

For large PDF files, consider providing a loading indicator or message to users.
Optimize images before uploading to ensure fast loading times in the viewer.
Use CDN-hosted URLs when possible to improve document loading performance across different geographic locations.

User Experience

Set appropriate height and width values based on the viewing context (inline vs. dialog vs. full-screen).
Use localized titles to support multi-language environments.
Provide clear context about what document is being displayed, especially when multiple documents are available.

Security

Always use HTTPS URLs for documents to ensure secure transmission.
Implement proper permission checks using the permission attribute to control access to sensitive documents.
Validate document URLs on the backend to prevent unauthorized access or injection attacks.
Consider implementing document access logging for compliance and audit purposes.

Responsive Design

Use relative units (e.g., 100vh, 100%) for height and width when displaying viewers in different screen sizes.
Test the viewer component on various devices to ensure proper rendering and usability.
Consider providing different viewing options for mobile vs. desktop users.

Integration Patterns

Combine the viewer with other components like buttons, forms, and data grids for comprehensive document management workflows.
Use dialogs to display documents without navigating away from the current screen.
Implement document selection interfaces that allow users to choose from multiple documents before viewing.

Introduction​

YAML Structure​

Attribute Description​

Props​

Common Attributes​

Supported File Types​

PDF Documents​

Image Formats​

Examples​

Basic PDF Viewer​

PDF Viewer with Download Option​

Image Viewer​

Dynamic Type Detection​

Conditional Viewer Display​

Full-Screen Document Viewer​

Viewer with Permissions​

Data Grid Integration​

Multiple Document Types​

Viewer with Loading State​

Best Practices​

File Type Handling​

Download Functionality​

Performance Considerations​

User Experience​

Security​

Responsive Design​

Integration Patterns​