332 lines
7.8 KiB
Markdown
332 lines
7.8 KiB
Markdown
# FileBrowser Widget
|
|
|
|
A powerful WebAssembly-based file browser widget that can be embedded in any web application. Built with Rust and Yew, compiled to WASM for maximum performance.
|
|
|
|
## Features
|
|
|
|
- 📁 **File & Directory Management**: Browse, create, delete files and directories
|
|
- 📤 **Resumable Uploads**: Upload files with progress tracking using TUS protocol
|
|
- 📥 **File Downloads**: Download files with proper MIME type handling
|
|
- ✏️ **File Editing**: Built-in editors for text files and markdown with live preview
|
|
- 🎨 **Modern UI**: Responsive Bootstrap-based interface with light/dark themes
|
|
- 🔧 **Highly Configurable**: Extensive JavaScript API for customization
|
|
- 🚀 **High Performance**: Compiled to WebAssembly for native-like performance
|
|
- 🌐 **Cross-Browser**: Works in all modern browsers
|
|
|
|
## Quick Start
|
|
|
|
### 1. Installation
|
|
|
|
#### Via npm (recommended)
|
|
```bash
|
|
npm install @herocode/file-browser-widget
|
|
```
|
|
|
|
#### Manual Download
|
|
Download the latest release files:
|
|
- `file_browser_widget.js`
|
|
- `file_browser_widget_bg.wasm`
|
|
|
|
### 2. Include Dependencies
|
|
|
|
Add Bootstrap CSS and Icons to your HTML:
|
|
```html
|
|
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
|
|
<link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/font/bootstrap-icons.css" rel="stylesheet">
|
|
```
|
|
|
|
### 3. Create Container
|
|
|
|
Add a container element to your HTML:
|
|
```html
|
|
<div id="file-browser-container"></div>
|
|
```
|
|
|
|
### 4. Initialize Widget
|
|
|
|
```javascript
|
|
import init, {
|
|
create_file_browser_widget,
|
|
create_default_config
|
|
} from '@herocode/file-browser-widget';
|
|
|
|
async function initFileBrowser() {
|
|
// Initialize the WASM module
|
|
await init();
|
|
|
|
// Create configuration
|
|
const config = create_default_config('http://localhost:3001/files');
|
|
config.set_theme('light');
|
|
config.set_show_upload(true);
|
|
config.set_show_download(true);
|
|
config.set_show_delete(true);
|
|
config.set_max_file_size(100 * 1024 * 1024); // 100MB
|
|
|
|
// Create and mount the widget
|
|
const widget = create_file_browser_widget('file-browser-container', config);
|
|
|
|
console.log('FileBrowser widget initialized successfully!');
|
|
}
|
|
|
|
// Initialize when page loads
|
|
initFileBrowser().catch(console.error);
|
|
```
|
|
|
|
## Configuration API
|
|
|
|
### WidgetConfig
|
|
|
|
The main configuration object for customizing the widget behavior:
|
|
|
|
```javascript
|
|
const config = create_default_config('http://localhost:3001/files');
|
|
|
|
// File size limit (in bytes)
|
|
config.set_max_file_size(50 * 1024 * 1024); // 50MB
|
|
|
|
// Feature toggles
|
|
config.set_show_upload(true);
|
|
config.set_show_download(true);
|
|
config.set_show_delete(true);
|
|
|
|
// UI customization
|
|
config.set_theme('dark'); // 'light' or 'dark'
|
|
config.set_css_classes('my-custom-class');
|
|
config.set_initial_path('documents/');
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `base_endpoint` | string | required | Backend API endpoint for file operations |
|
|
| `max_file_size` | number | 104857600 | Maximum file size for uploads (bytes) |
|
|
| `show_upload` | boolean | true | Enable/disable upload functionality |
|
|
| `show_download` | boolean | true | Enable/disable download functionality |
|
|
| `show_delete` | boolean | true | Enable/disable delete functionality |
|
|
| `theme` | string | 'light' | UI theme ('light' or 'dark') |
|
|
| `css_classes` | string | '' | Additional CSS classes for root element |
|
|
| `initial_path` | string | '' | Initial directory path to display |
|
|
|
|
## JavaScript API
|
|
|
|
### Functions
|
|
|
|
#### `init()`
|
|
Initialize the WASM module. Must be called before using other functions.
|
|
|
|
```javascript
|
|
await init();
|
|
```
|
|
|
|
#### `create_default_config(base_endpoint)`
|
|
Create a default configuration object.
|
|
|
|
```javascript
|
|
const config = create_default_config('http://localhost:3001/files');
|
|
```
|
|
|
|
#### `create_file_browser_widget(container_id, config)`
|
|
Create and mount a widget to a DOM element by ID.
|
|
|
|
```javascript
|
|
const widget = create_file_browser_widget('my-container', config);
|
|
```
|
|
|
|
#### `create_file_browser_widget_on_element(element, config)`
|
|
Create and mount a widget to a specific DOM element.
|
|
|
|
```javascript
|
|
const element = document.getElementById('my-container');
|
|
const widget = create_file_browser_widget_on_element(element, config);
|
|
```
|
|
|
|
#### `check_browser_compatibility()`
|
|
Check if the current browser supports the widget.
|
|
|
|
```javascript
|
|
if (!check_browser_compatibility()) {
|
|
console.error('Browser not supported');
|
|
}
|
|
```
|
|
|
|
#### `get_version()`
|
|
Get the widget version.
|
|
|
|
```javascript
|
|
console.log('Widget version:', get_version());
|
|
```
|
|
|
|
### Widget Handle
|
|
|
|
The widget functions return a handle that can be used to manage the widget:
|
|
|
|
```javascript
|
|
const widget = create_file_browser_widget('container', config);
|
|
|
|
// Destroy the widget
|
|
widget.destroy();
|
|
```
|
|
|
|
## Backend Requirements
|
|
|
|
The widget expects a REST API compatible with the following endpoints:
|
|
|
|
### File Listing
|
|
```
|
|
GET /files/list/<path>
|
|
Response: JSON array of file/directory objects
|
|
```
|
|
|
|
### Directory Creation
|
|
```
|
|
POST /files/dirs/<path>
|
|
Creates a new directory at the specified path
|
|
```
|
|
|
|
### File/Directory Deletion
|
|
```
|
|
DELETE /files/delete/<path>
|
|
Deletes the file or directory at the specified path
|
|
```
|
|
|
|
### File Upload (TUS Protocol)
|
|
```
|
|
POST /files/upload
|
|
Handles resumable file uploads using TUS protocol
|
|
```
|
|
|
|
### File Download
|
|
```
|
|
GET /files/download/<path>
|
|
Returns the file content with appropriate headers
|
|
```
|
|
|
|
### Example Backend Response Format
|
|
|
|
File listing response:
|
|
```json
|
|
[
|
|
{
|
|
"name": "document.pdf",
|
|
"path": "documents/document.pdf",
|
|
"size": 1024000,
|
|
"is_directory": false,
|
|
"modified": "2023-12-01T10:30:00Z"
|
|
},
|
|
{
|
|
"name": "images",
|
|
"path": "documents/images",
|
|
"size": 0,
|
|
"is_directory": true,
|
|
"modified": "2023-12-01T09:15:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Custom Styling
|
|
|
|
Add custom CSS to style the widget:
|
|
|
|
```css
|
|
.file-browser-widget {
|
|
border: 1px solid #ddd;
|
|
border-radius: 8px;
|
|
overflow: hidden;
|
|
}
|
|
|
|
.file-browser-widget .card {
|
|
border: none;
|
|
}
|
|
```
|
|
|
|
### Multiple Widgets
|
|
|
|
You can create multiple widget instances on the same page:
|
|
|
|
```javascript
|
|
// Widget 1
|
|
const config1 = create_default_config('http://api1.example.com/files');
|
|
const widget1 = create_file_browser_widget('container1', config1);
|
|
|
|
// Widget 2
|
|
const config2 = create_default_config('http://api2.example.com/files');
|
|
config2.set_theme('dark');
|
|
const widget2 = create_file_browser_widget('container2', config2);
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
```javascript
|
|
try {
|
|
const widget = create_file_browser_widget('container', config);
|
|
} catch (error) {
|
|
console.error('Failed to create widget:', error);
|
|
// Show fallback UI
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
### Building from Source
|
|
|
|
1. Install Rust and wasm-pack:
|
|
```bash
|
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
cargo install wasm-pack
|
|
```
|
|
|
|
2. Build the widget:
|
|
```bash
|
|
./build.sh
|
|
```
|
|
|
|
3. Test locally:
|
|
```bash
|
|
npm run dev
|
|
# Open http://localhost:8000/example.html
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
widgets/file_browser_widget/
|
|
├── src/
|
|
│ └── lib.rs # Main widget implementation
|
|
├── dist/ # Built distribution files
|
|
├── pkg/ # wasm-pack output
|
|
├── Cargo.toml # Rust dependencies
|
|
├── package.json # npm package config
|
|
├── build.sh # Build script
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Browser Support
|
|
|
|
- Chrome 57+
|
|
- Firefox 52+
|
|
- Safari 11+
|
|
- Edge 16+
|
|
|
|
The widget requires WebAssembly support and modern JavaScript features.
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests if applicable
|
|
5. Submit a pull request
|
|
|
|
## Support
|
|
|
|
- 📖 [Documentation](https://github.com/herocode/framework)
|
|
- 🐛 [Issue Tracker](https://github.com/herocode/framework/issues)
|
|
- 💬 [Discussions](https://github.com/herocode/framework/discussions)
|