Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 09

Backend e sezioni

Il pezzo del framework che fa risparmiare più tempo: griglie e form generati dal database. Una sezione di amministrazione completa — elenco, ricerca, ordinamento, paginazione, form di modifica, dettagli in relazione — sono due file PHP dichiarativi.

1. Come è instradato

/restricted/<sezione>
   └─ regola in conf/modules/auth/routing_table.xml  (profili: admin, data-entry)
        └─ conf/gallery/manage/<sezione>/index.php    → elenco   (ffGrid)
           conf/gallery/manage/<sezione>/modify.php   → scheda   (ffRecord)

L'autenticazione è una regola sola che protegge tutto ciò che sta sotto: i controller non devono ricontrollare l'accesso, solo i permessi fini (vedi 08 §4).

Le sotto-sezioni sono sottocartelle: manage/tags/categories/{index,modify}.php → /restricted/tags/categories.

2. Le sezioni presenti

SezioneGestisce
vgalleryi contenuti (nodi, campi, relazioni)
vgallery-nextla nuova area contenuti (VGALLERY_NEXT_PIANO.md)
section, block, staticsezioni, blocchi di layout, pagine statiche
resourcesrisorse e media
tags, placetassonomie e luoghi
internationalil dizionario multilingua (ff_international)
themes, jstemi e script
routingregole di routing
seometadati SEO
emailtemplate e configurazione email
notifynotifiche
publishing, draftpubblicazione e bozze
extrascampi extra
users, groupsaccount e gruppi
updateraggiornamenti, modalità manutenzione e migrazioni DB (14 §5bis)

3. ffGrid: l'elenco

$oGrid = ffGrid::factory($cm->oPage);
$oGrid->full_ajax    = true;                 // paginazione/ordinamento senza ricaricare la pagina
$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);   // filtri
$oField = ff_field(...);  $oGrid->addKeyField($oField);      // chiave (ID)
$oField = ff_field(...);  $oGrid->addContent($oField);       // colonne
$oGrid->addGridButton($oButton);                             // azioni massive

$oGrid->addEvent("on_before_parse_row", "mie_voci_on_before_parse_row");

I segnaposto [AND] [WHERE] [HAVING] [ORDER] nella source_SQL non sono decorativi: sono i punti dove la griglia inietta filtri, ricerca e ordinamento. Senza, ricerca e ordinamento non funzionano e non lo dice nessuno.

ProprietàA cosa serve
full_ajaxinterazione senza ricaricare
use_searchbarra di ricerca costruita dai addSearchField
order_defaultordinamento iniziale: l'id di un campo della griglia, non un pezzo di SQL. "level DESC" dà "Cannot determine order field!"; la direzione va nel campo, $oField->order_dir = "DESC" (conf/gallery/manage/groups/index.php)
record_url / record_iddove apre la scheda e con che id (serve per i popup)
resources[]dichiara le risorse (JS/CSS/widget) da caricare
widget_deps[]dipendenze da widget del framework
evention_before_parse_row, on_before_parse_data, … per decorare righe e celle

4. ffRecord: la scheda

$oRecord = ffRecord::factory($cm->oPage);
$oRecord->id        = "MieVociModify";
$oRecord->resources[] = $oRecord->id;
$oRecord->src_table = "mia_tabella";                       // il form conosce la tabella
$oRecord->insert_additional_fields["ID_lang"] = new ffData("1", "Number");   // valori impliciti
$oRecord->addEvent("on_done_action", "mie_voci_on_done_action");             // dopo il salvataggio

$oField = ff_field(...);  $oRecord->addKeyField($oField);
$oField = ff_field(...);  $oRecord->addContent($oField);
$oRecord->addContent($oDetail, "relazione");               // dettaglio in relazione (master-detail)

ffRecord genera il form, valida, scrive e ricarica da solo: in un caso semplice non c'è una riga di SQL di scrittura. Gli agganci applicativi si fanno con gli eventi (on_before_action, on_done_action, on_load_data, …), non riscrivendo il salvataggio.

Esempio reale con sincronizzazione su una seconda tabella: conf/gallery/manage/users/modify.php (allinea access_users e anagraph).

5. Aggiungere una sezione nuova: ricetta

  1. mkdir conf/gallery/manage/<sezione>/
  2. index.php — la ffGrid (copiare da una sezione vicina: tags per il caso semplice, users per il caso con sincronizzazione)
  3. modify.php — la ffRecord
  4. aggiungere la voce nel menu del backend (library/gallery/process/admin_menu.php e la configurazione del modulo restricted)
  5. se serve un permesso dedicato: una costante AREA_<SEZIONE>_SHOW_* letta con Auth::env()
  6. provare da utente data-entry, non solo da admin: è lì che si scoprono i permessi mancanti

6. L'interfaccia: cosa sapere prima di metterci mano

  • Il tema attivo è "gallery" (Foundation). Lo skin degli interventi è themes/admin/css/ff-skin.css. I widget HTML sono generati da themes/responsive/ff/.
  • Il tema base di jQuery UI è in 404 per un record DB con path sbagliato: dialog, slider e spinner sono stilati a mano. È un motivo, non una capriccio: rimettere il tema base cambia l'aspetto di tutto il backend.
  • I popup sono jQuery UI dialog con modal:false: il backdrop è .ff-modal, il box è .ui-dialog.ff-modal-dialog. Il contenuto arriva via AJAX come frammento con solo .ffRecord (nessun #frmMain).

    Conseguenza: gli hook JS e le regole CSS devono essere delegati (jQuery(document).on("click", ".tabs A", …)) e scopati a .ffRecord. Un handler inline non aggancia mai il contenuto di un dialog.

  • La dialogClass va ripulita dai token puramente visivi: il wrapper del dialog ereditava la classe hidden del bottone che lo apre, e il dialog nasceva invisibile.
  • Admin toolbar (barra di modifica in hover sul frontend): nascosta di default (ADMIN_TOOLBAR_HIDDEN = true in conf/gallery/config.php); si riattiva definendola false nel config.remote.php del progetto. Il contenuto arriva dal bus dei servizi, voce admin (vedi 03 §3).
  • Verifica dell'interfaccia senza login: un mock HTML che linka i CSS live più il DOM del componente, e screenshot con Chrome headless. Per i dialog serve una width in px inline su .ui-dialog-content.

Lo storico degli interventi sul backend sta in FIX_FUNZIONAMENTO.md (comportamento) e MIGLIORIE_ESTETICHE.md (solo CSS/UI). Gli interventi CSS si marcano con /* INTERVENTO CSS - GP AAAA-MM */.

7. Il resto del backend

Oltre a manage/, conf/gallery/ contiene aree funzionali ereditate dall'upstream:

CartellaArea
api/REST interna (04)
backup/, import/, updater/, checker/manutenzione, import/export, aggiornamento, verifiche
job/job di sistema (05 §3)
install/installer legacy: su un sito installato si apre solo da /admin/configuration/install (dietro login); la /install pubblica risponde 404 (vedi 01 §2)
mc/mail center
modules/moduli funzionali (10)
search/ricerca
services/servizi di terze parti (10 §3)
sitemap/sitemap legacy (JoeCMS usa modules/cms-common/models/Sitemap.php)
sys/servizi di sistema e bus (03 §3)