## Overview

Allows you to upload files to the page and lists all attachments in a table.

The Files widget provides file attachment and management functionality for any cplace page. It enables users to upload, view, and manage files associated with a page through a simple list interface.

**Use when**: You need to let users attach, view, or manage files on a page. This is the standard approach for any file handling needs.

**Alternatives**: For visual presentation of documents with thumbnails and preview capabilities, consider the Image Gallery widget, which displays the same files in a more visual format.

## Use Cases

### Document Collection
Pages that serve as repositories for related documents benefit from a files widget. Examples include project documentation pages, meeting minutes with supporting materials, or specification pages with technical attachments.

### Supporting Materials
When the primary content is something other than files (like a description, table, or diagram), but users still need to attach supporting materials, the files widget provides this capability without dominating the layout.

### Upload Entry Point
In layouts where users primarily interact with files through a visual gallery, the files widget often serves as the upload mechanism, with the gallery providing the viewing experience.

## Behavior and Capabilities

The Files widget operates on the page's built-in attachment system. Unlike table widgets that require data source configuration, the files widget automatically displays all files attached to the page where it's placed.

**Automatic Scoping**: The widget is inherently scoped to its embedding page. There's no need to configure filters or references - it simply shows the current page's files.

**List-Based Display**: Files appear in a list format showing filename and relevant metadata. This is efficient for many files but doesn't provide visual previews.

**Upload Capability**: Users with write permission can upload files directly through the widget. This is always available and doesn't require configuration.

**Immediate Synchronization**: When files are uploaded or removed, changes reflect immediately across any widgets displaying the same files (such as a paired gallery widget).

## Design Considerations

### When Files Widget Works Well

- Pages where file management is a supporting feature rather than the primary focus
- Situations requiring straightforward upload and list functionality
- Layouts where space is limited and a compact file list is preferable to visual thumbnails

### When to Consider Alternatives

- When visual document preview is important (pair with or use gallery widget)
- When files need to be categorized or filtered by type (consider separate pages or structured attributes)
- When files relate to multiple items and need relationship tracking (consider a document management type with proper references)

### Layout Positioning

The files widget doesn't require full width since it displays a simple list. Half-width or narrower placements work well, leaving room for other content. Common patterns include:

- Pairing with comments in a utilities section at page bottom
- Placing alongside a document gallery (smaller widget for upload, larger gallery for viewing)
- Using in a dedicated attachments tab for pages with many files

### Single Instance Principle

One files widget per layout is sufficient. Multiple instances would show the same files, creating redundancy without adding value.

### Permission Dependency

Upload functionality depends on the user having write permission on the page. Read-only users can view and download files but cannot add or remove them.

## Related Widgets

### Image Gallery
The gallery widget displays the same page attachments with visual thumbnails and preview capabilities. Files and gallery widgets are complementary:
- Files widget: List format, upload functionality, compact
- Gallery widget: Visual format, preview capability, requires more space

Many layouts pair both widgets, using the files widget for upload and management while the gallery provides the visual browsing experience.

### Comments Widget
Files and comments are often paired in a utilities section. Both represent page-level features (attachments and discussion) that support the main content. An equal-width split is common, though layouts may favor one or the other based on relative importance.