luxtools-plugin/README.md

# luxtools (DokuWiki plugin)

luxtools is a suite of tools designed to integrate the host file system with
DokuWiki, intentionally sidestepping the built-in MediaManager for specific
workflows.

This is a personal project that models my specific workflows and preferences.
It is likely unsuited for wider adoption without modification.


## Related projects

- luxtools-client: https://git.luxick.de/luxick/luxtools-client
  A client application for direct integration with the client machine
  (e.g. opening folders/paths from within the browser).
- luxtools-template: https://git.luxick.de/luxick/luxtools-template
  A DokuWiki template designed to complement the features of this plugin.


## What this plugin does

luxtools provides DokuWiki syntax that:

- Lists files from configured host filesystem roots (glob pattern)
- Lists a directory's direct children (files + folders)
- Renders an image thumbnail gallery (with lightbox)
- Provides "open this folder/path" links for local workflows
- Embeds file-backed scratchpads with a minimal inline editor (no wiki revisions)

It also ships a small file-serving endpoint (`lib/plugins/luxtools/file.php`) used
to deliver files and generate cached thumbnails.


##  Note on security

The file-serving endpoint (`lib/plugins/luxtools/file.php`) runs inside DokuWiki
and enforces access via per-page ACL: the requester must have at least read
access to the wiki page that rendered the link.

## Installation

Install like any other DokuWiki plugin.

If you install this plugin manually, make sure it is installed in:

`lib/plugins/luxtools/`

If the folder is called differently, DokuWiki will not load it.


## Project structure (developer notes)

This repository follows DokuWiki's plugin conventions at the top level (e.g. `syntax.php`, `conf/`, `lang/`, endpoints like `file.php`).

Reusable PHP code lives in `src/` and is loaded via `autoload.php`.
When adding new internal classes under the `dokuwiki\plugin\luxtools\` namespace, place them in `src/<ClassName>.php`.

JavaScript is split into small modules under `js/` and registered via `action.php` so DokuWiki loads them in order.


## IDE support (developer notes)

This plugin extends and uses DokuWiki core classes (for example `dokuwiki\Extension\ActionPlugin`, `dokuwiki\Extension\SyntaxPlugin`, renderers, handlers). If you only open the plugin folder in your IDE, those types may show as “unknown”.

DokuWiki does not currently ship an official PHP “SDK”/stub package for IDEs. The most reliable way to get full type navigation and autocomplete is to have the DokuWiki sources available in your workspace.

Two recommended setups:

### Option A: Add DokuWiki as a git submodule (recommended for a single-folder workspace)

From the plugin root:

```bash
git submodule add https://github.com/dokuwiki/dokuwiki.git _dokuwiki
git submodule update --init --recursive
```

The repository includes a VS Code config in `.vscode/settings.json` that points Intelephense at `./_dokuwiki/*` so the classes resolve.

`deploy.sh` excludes `_dokuwiki/` to avoid deploying the dev-only checkout.

### Option B: Use a separate DokuWiki checkout next to the plugin (recommended if you don’t want submodules)

- Clone DokuWiki into a sibling folder (outside this repo)
- Open a multi-root VS Code workspace with both folders

This avoids changing the git state of the plugin repo, but still gives the IDE access to DokuWiki’s class definitions.


## Configuration

luxtools is configured via its dedicated admin page:

`Admin -> Additional Plugins -> luxtools`

Key settings:

- **paths**
  Allowed base filesystem roots (one per line). Each root can be followed by:
  - `A> /Alias/` (optional) alias used in wiki syntax and open links

  Example:

  ```
  /srv/share/Datascape/
  A> /Scape/
  ```

  luxtools links use the plugin endpoint:

  `lib/plugins/luxtools/file.php?root=...&file=...`

  The generated URLs also include the current wiki page id (`id=...`) so
  `file.php` can enforce ACLs for the host page.



- **scratchpad_paths**
  Scratchpad file map (one file path per line, followed by an `A>` alias line).

  Example:
  ```
  /var/lib/dokuwiki-scratchpads/startpad.txt
  A> start
  ```

- **defaults**
  Default inline options appended to each listing call.

- **extensions**
  Comma-separated list of file extensions allowed in listings.
  Leave empty to allow all.

- **thumb_placeholder**
  MediaManager ID used as a placeholder image in the gallery (optional).

- **gallery_thumb_scale**
  Multiplier for generated thumbnails (1 = 150x150, 2 = 300x300), while still
  displaying them as 150x150. Useful for HiDPI screens.

- **open_service_url**
  URL of a local client service used by `{{open>...}}` and directory links.
  See luxtools-client.


## Features and usage

### 1) List files by glob pattern

```
{{files>/Scape/projects/*&style=list}}
{{files>/Scape/projects/*&style=table&tableheader=1&showsize=1&showdate=1}}
{{files>/Scape/projects/*&recursive=1&sort=mtime&order=desc}}
```

Notes:
- Pattern matching is performed per-directory (safe glob via fnmatch).
- A directory can have a title file (default: `_title.txt`) to override the displayed folder name.

### 2) List a directory (folders + files) as a table

```
{{directory>/Scape/projects/&tableheader=1&foldersfirst=1&sort=name}}
```

This always renders as a table. It includes an "Open Location" link above the table when rendered as XHTML.

### 3) Image gallery with thumbnails + lightbox

```
{{images>/Scape/photos/2025/*}}
{{images>/Scape/photos/2025/*&recursive=1}}
```

Clicking a thumbnail opens a lightbox viewer. Thumbnails are generated and cached via the plugin endpoint.

### 4) Open a local path/folder (best-effort)

```
{{open>/Scape/projects|Open projects folder}}
{{open>/home/me/notes|Open local folder}}
{{open>file:///home/me/notes|Open via file://}}
```

Behaviour:
- Prefer calling the configured local client service (open_service_url).
- Fall back to opening a file:// URL in a new tab (often blocked by browsers).

### 5) Scratchpads (shared, file-backed, no page revisions)

```
{{scratchpad>start}}
```

Scratchpads render the referenced file as wikitext and (when you have edit rights on the host page) provide an inline editor that saves directly to the backing file.


## Inline options reference (files/images/directory)

The listing syntaxes accept options appended with &key=value:

| Option | Values | Notes |
|---|---|---|
| recursive | 0\|1 | Recurse into subdirectories. |
| sort | name\|iname\|ctime\|mtime\|size | Sort key. |
| order | asc\|desc | Sort order. |
| foldersfirst | 0\|1 | Group folders before files (useful for tables). |
| titlefile | _title.txt | Directory title override file name. |
| cache | 0\|1 | 0 disables page caching (default). |
| randlinks | 0\|1 | Adds a cache-busting query parameter based on mtime. |
| showsize | 0\|1 | Show file size (where supported). |
| showdate | 0\|1 | Show last modified date (where supported). |
| listsep | ", " | Separator used in list-style rendering for extra fields. |
| maxheight | 500 | Container max-height in pixels; -1 disables scroll container. |

Additionally for `{{files>...}}`:

| Option | Values | Notes |
|---|---|---|
| style | list\|olist\|table | Output style. |
| tableheader | 0\|1 | Render table header row. |


## Credits / upstream

luxtools is a fork of the [DokuWiki Filelist plugin](https://www.dokuwiki.org/plugin:filelist).

Upstream authors and contributors include Gina Häußge and the DokuWiki
community (Dokufreaks).

This fork keeps the original license (GPL-2) and retains the relevant copyright
notices in the source.


## Development helpers

- Linux/macOS: ./deploy.sh

## License

GPL-2. See COPYING / LICENSE.