Skip to content
JoeCMS Download 3.1.5
Manual · 09

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

SectionManages
vgallerycontent (nodes, fields, relations)
vgallery-nextthe new content area (VGALLERY_NEXT_PIANO.md)
section, block, staticsections, layout blocks, static pages
resourcesresources and media
tags, placetaxonomies and places
internationalthe multilingual dictionary (ff_international)
themes, jsthemes and scripts
routingrouting rules
seoSEO metadata
emailemail templates and configuration
notifynotifications
publishing, draftpublishing and drafts
extrasextra fields
users, groupsaccounts and groups
updaterupdates, 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.

PropertyPurpose
full_ajaxinteraction without reloading
use_searchsearch bar built from the addSearchField calls
order_defaultinitial 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_idwhere 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
eventson_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

  1. mkdir conf/gallery/manage/<section>/
  2. index.php — the ffGrid (copy from a nearby section: tags for the simple case, users for the case with syncing)
  3. modify.php — the ffRecord
  4. add the entry to the backend menu (library/gallery/process/admin_menu.php and the restricted module configuration)
  5. if a dedicated permission is needed: an AREA_<SECTION>_SHOW_* constant read with Auth::env()
  6. test as a data-entry user, 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 by themes/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.

  • dialogClass must be stripped of purely visual tokens: the dialog wrapper inherited the hidden class 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 = true in conf/gallery/config.php); re-enable it by defining it false in the project's config.remote.php. Its content comes from the service bus, admin entry (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:

FolderArea
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)