Overview
The editor's JavaScript talks to a small JSON API under /admin/theme-file-editor/api/. It is an admin route, not part of Omeka's /api REST API: requests must carry a logged-in admin session cookie, and the same site_admin / global_admin ACL rule applies. There is no key-based authentication.
Every response is JSON with Content-Type: application/json and an ok flag:
{ "ok": true, "...": "..." }
{ "ok": false, "error": "Only .phtml files may be edited." }
| HTTP status | Meaning |
|---|---|
| 200 | Success |
| 400 | Invalid request or a runtime failure (file not writable, syntax error, revision not found, and so on) |
| 403 | Access denied or a security violation (bad path, wrong extension, rate limit) |
| 500 | Unexpected error |
POST bodies are form-encoded (multipart/form-data or application/x-www-form-urlencoded). Endpoints marked POST reject GET requests with POST required.
Every POST must also carry a CSRF token, either as a csrf form field or as an X-CSRF-Token header. The token is rendered into the editor page (data-csrf-token on #tfe-app) and into the Revision History page, and is valid for the admin session for 12 hours. Requests without a valid token get HTTP 403 with Invalid or missing CSRF token. This means the POST endpoints cannot be called from outside the module's own pages without first loading one of them.
Endpoints
GET /api/files
List a directory.
| Parameter | Description |
|---|---|
source |
theme (default), module or app |
theme |
Theme directory name (required for theme; used for override detection otherwise) |
module |
Module directory name (required for module) |
path |
Sub-directory relative to the view/ directory, empty for the root |
Returns files: an array of {name, path, type ("dir" or "file"), size, mtime, extension, isOverridden, isEditable, source} sorted directories first, then by name.
GET /api/file
Read a .phtml file.
| Parameter | Description |
|---|---|
source, theme, module |
As for /api/files |
path |
File path relative to the view/ directory |
Returns content, meta (path, absPath, size, mtime, checksum, readable, writable, permissions) and latestRevision (the newest revision without its content, or null; always null for non-theme sources).
POST /api/file/save
Save a theme file and create a revision.
| Field | Description |
|---|---|
theme |
Theme directory name (required) |
path |
File path relative to view/ (required, must exist, .phtml) |
content |
New file content |
summary |
Optional change summary, truncated to 255 characters |
create_backup |
1 to write a .bak copy first |
override_syntax_error |
1 to save even if the syntax check fails |
Returns revision_id.
POST /api/file/rollback
Restore a revision to disk.
| Field | Description |
|---|---|
revision_id |
ID of the revision to restore (required) |
Returns new_revision_id, the revision created by the rollback.
GET /api/file/revisions
List revisions of a file, newest first, without content.
| Parameter | Description |
|---|---|
theme, path |
Identify the file |
limit |
1 to 200, default 50 |
Returns revisions: array of {id, theme, relative_path, user_id, created_at, change_summary, checksum, file_size}.
GET /api/file/diff
Produce a unified diff.
| Parameter | Description |
|---|---|
rev_a |
Revision ID (required) |
rev_b |
Second revision ID. When omitted, rev_a is compared with the file currently on disk |
theme, path |
Used when rev_b is omitted; default to the file recorded in rev_a |
Returns unified (plain unified diff text with three lines of context) and html (the same diff rendered with <ins> and <del> markup).
POST /api/copy-to-theme
Copy a module or application view into a theme.
| Field | Description |
|---|---|
source_type |
module (default) or app |
source_module |
Module name when source_type is module |
theme |
Target theme (required) |
path |
File path relative to the source view/ directory; the target uses the same path (required) |
Returns ok only.
POST /api/copy-theme
Duplicate a whole theme directory.
| Field | Description |
|---|---|
source_theme |
Existing theme directory name (required) |
target_theme |
New directory name, [A-Za-z0-9_-]+, must not exist (required) |
Returns new_theme and files_copied.
GET /api/search
Search .phtml files by name or content.
| Parameter | Description |
|---|---|
q |
Search text, at least two characters |
theme |
Limit to one theme |
module |
Search a module's view/ directory instead of, or as well as, a theme |
With neither theme nor module, all themes are searched. Returns results: array of {source, theme, module, path, nameMatch, snippet, size}, at most 100 entries.
GET and POST /api/settings
GET returns the five module settings under settings. POST accepts the same keys (tfe_max_file_size_kb, tfe_revisions_to_keep, tfe_syntax_check_enabled, tfe_backup_on_save, tfe_rate_limit_per_minute) as form fields and saves them. Numeric values are clamped to a minimum of 1. See Configuration.