add file browser component and widget
This commit is contained in:
Timur Gordon
273
examples/file_browser_demo/README.md
Normal file
273
examples/file_browser_demo/README.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# File Browser Demo
|
||||
|
||||
A comprehensive file browser component built with Yew (Rust) and compiled to WebAssembly, featuring Uppy.js integration for resumable file uploads via the TUS protocol.
|
||||
|
||||
## Features
|
||||
|
||||
- 📁 **File System Browser**: Navigate directories, view files with metadata
|
||||
- ⬆️ **Resumable Uploads**: TUS protocol support via Uppy.js for reliable file uploads
|
||||
- ⬇️ **File Downloads**: Direct download with progress tracking
|
||||
- 🗂️ **Directory Management**: Create and delete directories
|
||||
- 🗑️ **File Management**: Delete files with confirmation
|
||||
- 📊 **Progress Tracking**: Real-time upload progress with visual indicators
|
||||
- 🎨 **Modern UI**: Bootstrap-styled responsive interface
|
||||
- 🚀 **WebAssembly**: High-performance Rust code compiled to WASM
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Structure
|
||||
|
||||
```
|
||||
FileBrowser
|
||||
├── FileBrowserConfig (Properties)
|
||||
├── FileBrowserMsg (Messages)
|
||||
├── API Functions (HTTP calls to backend)
|
||||
└── Uppy.js Integration (JavaScript interop)
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **FileBrowser**: Main Yew component with file listing, navigation, and upload UI
|
||||
2. **FileBrowserConfig**: Configuration struct for customizing the widget
|
||||
3. **API Layer**: Async functions for backend communication using web_sys::fetch
|
||||
4. **Uppy Integration**: JavaScript interop for TUS resumable uploads
|
||||
|
||||
## Configuration Options
|
||||
|
||||
The `FileBrowserConfig` struct allows extensive customization:
|
||||
|
||||
```rust
|
||||
FileBrowserConfig {
|
||||
base_endpoint: "/files".to_string(), // Backend API endpoint
|
||||
max_file_size: 100 * 1024 * 1024, // Max file size (100MB)
|
||||
chunk_size: 1024 * 1024, // Download chunk size (1MB)
|
||||
initial_path: "".to_string(), // Starting directory
|
||||
show_upload: true, // Enable upload functionality
|
||||
show_download: true, // Enable download functionality
|
||||
show_delete: true, // Enable delete functionality
|
||||
show_create_dir: true, // Enable directory creation
|
||||
css_classes: "container-fluid".to_string(), // Custom CSS classes
|
||||
theme: "light".to_string(), // Uppy theme (light/dark)
|
||||
}
|
||||
```
|
||||
|
||||
## Backend Compatibility
|
||||
|
||||
The file browser component is designed to work with the Python Flask backend from `src/files.py`. It expects the following API endpoints:
|
||||
|
||||
- `GET /files/list/{path}` - List directory contents
|
||||
- `POST /files/upload` - TUS resumable upload endpoint
|
||||
- `GET /files/download/{path}` - Download files
|
||||
- `POST /files/dirs/{path}` - Create directories
|
||||
- `DELETE /files/delete/{path}` - Delete files/directories
|
||||
|
||||
### Mock Server
|
||||
|
||||
For testing and development, this demo includes a Rust-based mock server that implements the same API as the Python backend:
|
||||
|
||||
**Location:** `mock-server/`
|
||||
|
||||
**Features:**
|
||||
- Full API compatibility with `src/files.py`
|
||||
- Sample files and directories for testing
|
||||
- CORS enabled for frontend development
|
||||
- Lightweight and fast
|
||||
- No external dependencies beyond Rust
|
||||
|
||||
**Manual Usage:**
|
||||
```bash
|
||||
# Start just the mock server
|
||||
./run-mock-server.sh
|
||||
|
||||
# Or run manually
|
||||
cd mock-server
|
||||
cargo run --release
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Rust (latest stable version)
|
||||
- `trunk` for building and serving WASM applications:
|
||||
```bash
|
||||
cargo install trunk
|
||||
```
|
||||
- `wasm32-unknown-unknown` target:
|
||||
```bash
|
||||
rustup target add wasm32-unknown-unknown
|
||||
```
|
||||
|
||||
### Easy Demo Launch
|
||||
|
||||
The quickest way to see the file browser in action:
|
||||
|
||||
```bash
|
||||
./run-demo.sh
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. Build and start the Rust mock server on `http://localhost:3001`
|
||||
2. Build and serve the WASM demo on `http://localhost:8080`
|
||||
3. Automatically open your browser to the demo
|
||||
4. Handle cleanup when you press Ctrl+C
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Rust and Trunk**:
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
cargo install trunk
|
||||
```
|
||||
|
||||
2. **Backend Server**: The Python Flask backend from the knowledgecenter project
|
||||
|
||||
## Building and Running
|
||||
|
||||
### 1. Build the WASM Application
|
||||
|
||||
```bash
|
||||
# From the file_browser_demo directory
|
||||
./build.sh
|
||||
```
|
||||
|
||||
This will:
|
||||
- Build the Rust code to WebAssembly using Trunk
|
||||
- Generate optimized WASM and JavaScript files
|
||||
- Output files to the `dist/` directory
|
||||
|
||||
### 2. Start the Backend Server
|
||||
|
||||
```bash
|
||||
# From the knowledgecenter directory
|
||||
cd /path/to/knowledgecenter
|
||||
python -m flask run
|
||||
```
|
||||
|
||||
Make sure CORS is configured to allow requests from your frontend origin.
|
||||
|
||||
### 3. Serve the Frontend
|
||||
|
||||
**Development Mode:**
|
||||
```bash
|
||||
# From the file_browser_demo directory
|
||||
trunk serve
|
||||
```
|
||||
|
||||
**Production Mode:**
|
||||
```bash
|
||||
# From the file_browser_demo directory
|
||||
./serve.sh
|
||||
```
|
||||
|
||||
### 4. Open in Browser
|
||||
|
||||
Trunk will automatically open `http://127.0.0.1:8080` in your web browser.
|
||||
|
||||
## Usage as a Widget
|
||||
|
||||
The file browser can be used as a reusable widget in other Yew applications:
|
||||
|
||||
```rust
|
||||
use framework::components::{FileBrowser, FileBrowserConfig};
|
||||
|
||||
#[function_component(MyApp)]
|
||||
fn my_app() -> Html {
|
||||
let config = FileBrowserConfig {
|
||||
base_endpoint: "/api/files".to_string(),
|
||||
initial_path: "documents".to_string(),
|
||||
theme: "dark".to_string(),
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
html! {
|
||||
<div class="my-app">
|
||||
<FileBrowser ..config />
|
||||
</div>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Styling
|
||||
|
||||
The component uses Bootstrap classes and can be customized via:
|
||||
|
||||
1. **CSS Classes**: Pass custom classes via `css_classes` in config
|
||||
2. **Theme**: Set Uppy theme to "light" or "dark"
|
||||
3. **Custom CSS**: Override the default styles in your application
|
||||
|
||||
### Functionality
|
||||
|
||||
Enable/disable features via configuration:
|
||||
|
||||
```rust
|
||||
FileBrowserConfig {
|
||||
show_upload: false, // Hide upload functionality
|
||||
show_delete: false, // Hide delete buttons
|
||||
show_create_dir: false, // Hide directory creation
|
||||
// ... other options
|
||||
}
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
file_browser_demo/
|
||||
├── Cargo.toml # Rust dependencies
|
||||
├── build.sh # Build script
|
||||
├── index.html # HTML template with Uppy.js
|
||||
├── src/
|
||||
│ └── main.rs # Main Yew application
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Key Dependencies
|
||||
|
||||
- **yew**: Rust web framework
|
||||
- **wasm-bindgen**: Rust/JavaScript interop
|
||||
- **web-sys**: Web API bindings
|
||||
- **serde**: Serialization for API communication
|
||||
- **js-sys**: JavaScript value manipulation
|
||||
|
||||
### JavaScript Dependencies
|
||||
|
||||
- **Uppy.js**: File upload library with TUS support
|
||||
- **Bootstrap**: UI framework
|
||||
- **Bootstrap Icons**: Icon set
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### WASM Module Loading Issues
|
||||
|
||||
1. Ensure files are served over HTTP (not file://)
|
||||
2. Check browser console for detailed error messages
|
||||
3. Verify WASM files are generated in `pkg/` directory
|
||||
|
||||
### Upload Issues
|
||||
|
||||
1. Check backend server is running and accessible
|
||||
2. Verify CORS configuration allows your frontend origin
|
||||
3. Ensure TUS endpoints are properly implemented in backend
|
||||
|
||||
### Build Issues
|
||||
|
||||
1. Update Rust toolchain: `rustup update`
|
||||
2. Clear cargo cache: `cargo clean`
|
||||
3. Reinstall wasm-pack if needed
|
||||
|
||||
## Browser Support
|
||||
|
||||
- Chrome/Chromium 80+
|
||||
- Firefox 72+
|
||||
- Safari 13.1+
|
||||
- Edge 80+
|
||||
|
||||
WebAssembly and modern JavaScript features are required.
|
||||
|
||||
## License
|
||||
|
||||
This demo is part of the Hero Framework project. See the main project for licensing information.
|
||||
Reference in New Issue
Block a user