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, linkTarget, size, mtime, checksum, readable, writable, permissions, override) and latestRevision (the newest revision without its content, or null; always null for non-theme sources). writable is about the file itself. override is null for theme files; for module and application files it says whether /api/copy-to-theme can write the file into theme: {path, exists, linked, writable}, where path is the target relative to the Omeka installation, exists means a file or link is there already, and linked means that file, or a folder on its path, links out of the theme's view/ directory, so the copy is refused.
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. An existing theme file at the target path is replaced, unless it, or a folder on its path, is a link out of the theme's view/ directory: then the request fails with HTTP 403.
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) |
Symbolic links are replaced by copies of their targets when these lie inside the source theme or the Omeka installation; other links are left out. Returns new_theme, files_copied and skipped_links, an array of {path, target, reason} for the links left out, where reason is outside, broken or loop. The result is also shown as a message on the next admin page, which is the editor when the request comes from it. A copy over 20,000 files or 256 MB fails with HTTP 400 and writes nothing. A copy that fails part-way (a file that cannot be read or written) also fails with HTTP 400 and leaves nothing behind: the copy is written to a temporary folder and renamed to target_theme only once complete.
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.