Overview
The editor's pages talk to a small JSON API under /admin/theme-file-editor/api/. It is an admin route, not part of Omeka's REST API (/api): requests need a signed-in Super User's admin session cookie and pass the same ACL rule as the pages. There are no API keys.
Every response is JSON with an ok flag:
{ "ok": true, "...": "..." }
{ "ok": false, "error": "Only templates (.php), stylesheets (.css) and scripts (.js) can be edited." }
| Status | Meaning |
|---|---|
| 200 | Done |
| 400 | A bad request, or something that failed: a syntax error, a file that cannot be written, a revision that does not exist |
| 403 | Refused: a read-only theme, a path outside the allowed folders, a wrong kind of file, the rate limit, a missing CSRF token. Users without access get Omeka's Forbidden page instead, and visitors who are not signed in the login page |
| 409 | Copy to Theme: the theme already has the file (send replace to replace it) |
| 500 | An unexpected error (also written to Omeka's log) |
POST requests send a JSON object (Content-Type: application/json) and the session's CSRF token, in the X-CSRF-Token header or a csrf field of the object. The token is in the editor's page (data-csrf on #tfe-app) and the Revision History page; it is Omeka's session token, the one its own forms use. GET on a POST endpoint answers 400.
Paths are relative to the source folder (items/show.php). A source is theme (with theme=<folder>), app (Omeka's views) or plugin:<Plugin>/public / plugin:<Plugin>/shared.
Endpoints
GET files
A folder's entries, folders first.
| Parameter | |
|---|---|
source |
theme (default), app, plugin:<Plugin>/<part> |
theme |
The theme (for theme; for the others, the theme whose copies are marked) |
path |
The folder, empty for the top |
Returns files: {name, path, type ("dir"|"file"), kind ("dir"|"editable"|"viewable"|"backup"|"other"), size, mtime, extension, linkTarget, openable, overrides, overridden}. linkTarget is set when the entry is a link out of the source folder; overrides lists what a theme file overrides ("Omeka" or plugin folders); overridden, for a view, where the theme has its own copy ("plugin", "root").
GET file
A file's content and details.
| Parameter | |
|---|---|
source, theme, path |
As above |
Returns content, meta (path, displayPath, kind, language, linkTarget, size, mtime, checksum, writable, overrides, targets), latestRevision (without content, or null) and theme (the theme's status: title, current, copy, ticked, linked, writable, editable, reason, deletable, exhibits). targets, for a core or plugin view, are the places Copy to Theme can write: {key, rel, path, exists, linked, writable}.
POST save
| Field | |
|---|---|
theme, path |
The file (required; it must exist) |
content |
The new content (required) |
summary |
What changed, up to 255 characters |
create_backup |
true to write a backup file first |
override_syntax_error |
true to save despite a syntax error |
Returns revision_id, revisions (the file's count), backup (the backup's file name or null) and syntax ("parser", "php -l" or ""); or unchanged: true when the content is the file's. A syntax error answers 400 with an error starting Syntax error: .
POST rollback
| Field | |
|---|---|
revision_id |
The revision to restore (required) |
Returns new_revision_id.
GET revisions
A file's revisions, newest first, without content.
| Parameter | |
|---|---|
theme, path |
The file |
limit |
1 to 200, default 50 |
Returns revisions: {id, theme, relative_path, user_id, created_at (UTC), date (in the site's time zone), change_summary, checksum, file_size}.
GET diff
| Parameters | Compares |
|---|---|
rev_a, rev_b |
Two revisions of the same file, the older first |
rev_a, rev_b=current (or no rev_b) |
A revision and its file as it is now |
original=<source>, theme, path |
The core or plugin view a theme file overrides (app or plugin:<Plugin>/<part>) and the theme file |
Returns unified (a unified diff with three lines of context, empty when they are the same) and html (the same, marked up).
POST copy-to-theme
| Field | |
|---|---|
source |
app or plugin:<Plugin>/<part> (required) |
theme |
The theme (required, editable) |
path |
The view (required) |
where |
root (themes/<theme>/<path>) or, for a plugin view, plugin (themes/<theme>/<plugin-folder>/<path>) |
replace |
true to replace a file the theme has |
Returns theme and path, the new file's path in the theme.
POST copy-theme
| Field | |
|---|---|
source_theme |
The theme to copy (required) |
target_theme |
The new folder name, ^[A-Za-z0-9_-]{1,30}$, not a theme's name in any case (required) |
title |
The copy's title (default: the folder name in title case) |
copy_options |
true to copy the theme's configuration |
Returns new_theme, title, files_copied, bytes, skipped_links ({path, target, reason}) and options_copied.
POST delete-theme
| Field | |
|---|---|
theme |
A theme made with Copy Theme, not the public theme, used by no exhibit |
Returns deleted.
POST delete-backup
| Field | |
|---|---|
theme, path |
A backup the editor wrote (<file>.<YYYYMMDDHHMMSS>.bak) |
Returns deleted.
GET search
| Parameter | |
|---|---|
q |
At least two characters |
scope |
Empty (every theme), theme:<folder>, app or plugin:<Plugin>/<part> |
Returns results: {source, theme, path, nameMatch, snippet, line, size}, at most 100.