Skip to content

Commit c0fcb31

Browse files
thatSFguythatSFguy
authored
Document collaborative editing setup in README
Added collaborative editing feature with PHP backend and setup instructions.
1 parent 1902e0c commit c0fcb31

1 file changed

Lines changed: 119 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,3 +128,122 @@ In the RF Line-of-Sight Tool ([https://thatsfguy.github.io/Line-Of-Sight-Tool/in
128128
- **Limitations**: This is a client-side tool with no cloud sync. Desktop browsers provide the best experience.
129129

130130
For issues or advanced features, check the GitHub repo or page source for updates. Happy RF mapping!
131+
132+
133+
134+
135+
136+
# Line-of-Sight Tool - Collaborative Backend
137+
138+
This adds shared/collaborative editing to the Line-of-Sight Tool using a simple PHP backend with JSON file storage.
139+
140+
## Files
141+
142+
- `api.php` - The PHP backend that handles data storage
143+
- `shared-storage.js` - JavaScript that integrates with the frontend
144+
145+
## Quick Setup
146+
147+
### 1. Server Setup
148+
149+
Upload `api.php` to your web server (any PHP 7.4+ host will work).
150+
151+
Create a `data` directory in the same folder:
152+
```bash
153+
mkdir data
154+
chmod 755 data
155+
```
156+
157+
Create a `.htaccess` file inside the `data` directory to prevent direct access:
158+
```
159+
# data/.htaccess
160+
Deny from all
161+
```
162+
163+
### 2. Frontend Setup
164+
165+
Add the JavaScript to `nodemgr.html`. Open the file and add this line near the top, inside the `<head>` tag, BEFORE any other scripts:
166+
167+
```html
168+
<script src="shared-storage.js"></script>
169+
```
170+
171+
Or if hosting the JS elsewhere, use the full URL:
172+
```html
173+
<script src="https://yourserver.com/path/to/shared-storage.js"></script>
174+
```
175+
176+
That's it! No hardcoded configuration needed.
177+
178+
## Usage
179+
180+
1. Open the Node Manager - you'll see a "Local Only" indicator in the top right
181+
2. Click the indicator to open Collaboration Settings
182+
3. Enter your API URL (where you hosted `api.php`)
183+
4. Click **"Create New Key"** to generate a 16-character workspace key
184+
5. Click **"Connect"** to start using the shared workspace
185+
6. Share the API URL and key with collaborators
186+
7. Changes sync automatically (saves within 1 second, polls for updates every 30 seconds)
187+
188+
Each user configures their own API URL and key through the UI - nothing is hardcoded. Settings are remembered in the browser.
189+
190+
## Configuration Options
191+
192+
Edit the constants at the top of `api.php`:
193+
194+
| Setting | Default | Description |
195+
|---------|---------|-------------|
196+
| `MAX_KEYS` | 50 | Maximum number of workspaces (JSON files) |
197+
| `MAX_NODES` | 400 | Maximum nodes per workspace |
198+
| `MAX_GROUPS` | 100 | Maximum groups per workspace |
199+
| `MAX_JSON_SIZE` | 512KB | Maximum payload size |
200+
| `KEY_LENGTH` | 16 | Length of generated keys |
201+
| `ALLOWED_ORIGINS` | `*` | CORS origins (set to your domain in production) |
202+
203+
## API Endpoints
204+
205+
| Method | URL | Description |
206+
|--------|-----|-------------|
207+
| `POST` | `?action=newkey` | Create a new workspace, returns the key |
208+
| `GET` | `?key=XXXXXXXXXXXXXXXX` | Get all data for a key |
209+
| `POST` | `?key=XXXXXXXXXXXXXXXX` | Save data for a key (JSON body) |
210+
| `GET` | `?action=status` | Get server status and limits |
211+
212+
## Security Features
213+
214+
- **Input validation**: All data is validated for type, range, and length
215+
- **Sanitization**: Strings are HTML-encoded to prevent XSS
216+
- **Path traversal prevention**: Keys are strictly alphanumeric
217+
- **Size limits**: Payload size, node count, and file count are all limited
218+
- **No SQL**: JSON files eliminate SQL injection entirely
219+
- **CORS headers**: Configurable allowed origins
220+
- **File locking**: Uses `LOCK_EX` to prevent race conditions
221+
222+
## Troubleshooting
223+
224+
**"Key not found" error**
225+
- The key doesn't exist. Create a new one or check for typos.
226+
227+
**"Maximum number of shared workspaces reached"**
228+
- Delete old JSON files from the `data` directory, or increase `MAX_KEYS`.
229+
230+
**"Too many nodes"**
231+
- You've hit the 400 node limit. Increase `MAX_NODES` or split into multiple workspaces.
232+
233+
**Changes not syncing**
234+
- Check browser console for network errors
235+
- Verify `API_URL` is correct and accessible
236+
- Check that the `data` directory is writable
237+
238+
**CORS errors**
239+
- Set `ALLOWED_ORIGINS` to your specific domain instead of `*`
240+
241+
## Backup
242+
243+
All data is stored as JSON files in the `data` directory. To backup:
244+
245+
```bash
246+
cp -r data/ backup-$(date +%Y%m%d)/
247+
```
248+
249+
Each file is named `{key}.json` and contains the complete workspace state.

0 commit comments

Comments
 (0)