Backend and sections
The part of the framework that saves the most time: grids and forms generated from the database. A complete admin section — list, search, sorting, pagination, edit form, related details — is two declarative PHP files.
1. How it's routed
/restricted/<section>
└─ rule in conf/modules/auth/routing_table.xml (profiles: admin, data-entry)
└─ conf/gallery/manage/<section>/index.php → list (ffGrid)
conf/gallery/manage/<section>/modify.php → record (ffRecord)
Authentication is a single rule protecting everything below it: controllers don't need to re-check access, only fine-grained permissions (see 08 §4).
Sub-sections are subfolders: manage/tags/categories/{index,modify}.php → /restricted/tags/categories.
2. Existing sections
| Section | Manages |
|---|---|
vgallery | content (nodes, fields, relations) |
vgallery-next | the new content area (VGALLERY_NEXT_PIANO.md) |
section, block, static | sections, layout blocks, static pages |
resources | resources and media |
tags, place | taxonomies and places |
international | the multilingual dictionary (ff_international) |
themes, js | themes and scripts |
routing | routing rules |
seo | SEO metadata |
email | email templates and configuration |
notify | notifications |
publishing, draft | publishing and drafts |
extras | extra fields |
users, groups | accounts and groups |
updater | updates, maintenance mode and DB migrations (14 §5bis) |
3. ffGrid: the list
$oGrid = ffGrid::factory($cm->oPage);
$oGrid->full_ajax = true; // paging/sorting without reloading the page
$oGrid->id = "MieVoci";
$oGrid->source_SQL = "SELECT ID, nome, creato_il
FROM mia_tabella
WHERE 1 [AND] [WHERE] [HAVING] [ORDER]";
$oGrid->order_default = "nome";
$oGrid->use_search = true;
$oGrid->record_url = $cm->oPage->site_path . $cm->oPage->page_path . "/modify";
$oGrid->record_id = "MieVociModify";
$oGrid->resources[] = $oGrid->record_id;
$oField = ff_field(...); $oGrid->addSearchField($oField); // filters
$oField = ff_field(...); $oGrid->addKeyField($oField); // key (ID)
$oField = ff_field(...); $oGrid->addContent($oField); // columns
$oGrid->addGridButton($oButton); // bulk actions
$oGrid->addEvent("on_before_parse_row", "mie_voci_on_before_parse_row");
The [AND] [WHERE] [HAVING] [ORDER] placeholders in source_SQL aren't decorative: they're where the grid injects filters, search and sorting. Without them, search and sorting don't work and nobody tells you.
| Property | Purpose |
|---|---|
full_ajax | interaction without reloading |
use_search | search bar built from the addSearchField calls |
order_default | initial sorting: the id of a field of the grid, not a piece of SQL. "level DESC" gives "Cannot determine order field!"; the direction goes on the field, $oField->order_dir = "DESC" (conf/gallery/manage/groups/index.php) |
record_url / record_id | where the record opens and with which id (needed for popups) |
resources[] | declares the resources (JS/CSS/widgets) to load |
widget_deps[] | dependencies on framework widgets |
| events | on_before_parse_row, on_before_parse_data, … to decorate rows and cells |
4. ffRecord: the record form
$oRecord = ffRecord::factory($cm->oPage);
$oRecord->id = "MieVociModify";
$oRecord->resources[] = $oRecord->id;
$oRecord->src_table = "mia_tabella"; // the form knows the table
$oRecord->insert_additional_fields["ID_lang"] = new ffData("1", "Number"); // implicit values
$oRecord->addEvent("on_done_action", "mie_voci_on_done_action"); // after saving
$oField = ff_field(...); $oRecord->addKeyField($oField);
$oField = ff_field(...); $oRecord->addContent($oField);
$oRecord->addContent($oDetail, "relazione"); // related detail (master-detail)
ffRecord generates the form, validates, writes and reloads by itself: in a simple case there's not a single line of write SQL. Application hooks go through events (on_before_action, on_done_action, on_load_data, …), not by rewriting the save.
A real example with syncing to a second table: conf/gallery/manage/users/modify.php (aligns access_users and anagraph).
5. Adding a new section: recipe
mkdir conf/gallery/manage/<section>/index.php— theffGrid(copy from a nearby section:tagsfor the simple case,usersfor the case with syncing)modify.php— theffRecord- add the entry to the backend menu (
library/gallery/process/admin_menu.phpand therestrictedmodule configuration) - if a dedicated permission is needed: an
AREA_<SECTION>_SHOW_*constant read withAuth::env() - test as a
data-entryuser, not just as admin: that's where missing permissions show up
6. The interface: what to know before touching it
- The active theme is "gallery" (Foundation). The skin for the changes is
themes/admin/css/ff-skin.css. HTML widgets are generated bythemes/responsive/ff/. - The jQuery UI base theme returns 404 because of a DB record with a wrong path: dialogs, sliders and spinners are styled by hand. It's a reason, not a whim: restoring the base theme changes the look of the whole backend.
- Popups are jQuery UI dialogs with
modal:false: the backdrop is.ff-modal, the box is.ui-dialog.ff-modal-dialog. Content arrives via AJAX as a fragment with only.ffRecord(no#frmMain).Consequence: JS hooks and CSS rules must be delegated (
jQuery(document).on("click", ".tabs A", …)) and scoped to.ffRecord. An inline handler never catches a dialog's content. dialogClassmust be stripped of purely visual tokens: the dialog wrapper inherited thehiddenclass of the button that opens it, and the dialog was born invisible.- Admin toolbar (hover edit bar on the front end): hidden by default (
ADMIN_TOOLBAR_HIDDEN = trueinconf/gallery/config.php); re-enable it by defining itfalsein the project'sconfig.remote.php. Its content comes from the service bus,adminentry (see 03 §3). - Checking the interface without logging in: an HTML mock linking the live CSS plus the component's DOM, and screenshots with headless Chrome. For dialogs you need an inline px width on
.ui-dialog-content.
The history of backend changes is in FIX_FUNZIONAMENTO.md (behaviour) and MIGLIORIE_ESTETICHE.md (CSS/UI only). CSS changes are marked with /* INTERVENTO CSS - GP YYYY-MM */.
7. The rest of the backend
Besides manage/, conf/gallery/ contains functional areas inherited from upstream:
| Folder | Area |
|---|---|
api/ | internal REST (04) |
backup/, import/, updater/, checker/ | maintenance, import/export, updating, checks |
job/ | system jobs (05 §3) |
install/ | legacy installer: on an installed site it only opens from /admin/configuration/install (behind login); the public /install answers 404 (see 01 §2) |
mc/ | mail center |
modules/ | functional modules (10) |
search/ | search |
services/ | third-party services (10 §3) |
sitemap/ | legacy sitemap (JoeCMS uses modules/cms-common/models/Sitemap.php) |
sys/ | system services and bus (03 §3) |