Pages, templates and applets
How HTML is built: where a page controller goes, how the template engine works, what an applet is and how CSS and JS are attached.
1. A page is a file
Creating contents/<name>.php is enough for /<name> to exist. No registration, no database row, no routing entry: the BOTTOM rule in cm/conf/routing_table.xml ((.*) → /contents$0) takes care of it.
Canonical anatomy:
<?php
use_cache(false); // dynamic page: never from the page cache
$db = ffDB_Sql::factory();
$filename = FF_DISK_PATH . "/themes/site/contents/elenco/index.html";
$tpl = ffTemplate::factory(ffCommon_dirname($filename));
$tpl->load_file(basename($filename), "main");
// ... queries, set_var, block parsing ...
$cm->oPage->addContent($tpl->rpparse("main", false));
$cm->oPage->addContent()inserts the HTML into the layout (header, footer and blocks come from the layout configured on the CMS side, not from the page file);- a page that must go outside the layout (self-contained legal page, preview, export) prints directly and calls
exit; - subfolders work:
contents/area/section.php→/area/section, andcontents/area/index.php→/area. The path residue arrives in$cm->real_path_info(see 01 §4).
Examples in the repo: contents/md/index.php (Markdown version of content), contents/i18n.php (slug map per language), contents/restricted/, contents/emailpreviewer/.
2. ffTemplate: the template engine
Two constructs, and nothing else.
2.1 {name} placeholders
$tpl->set_var("titolo", "Hello"); // {titolo} in the HTML file
A placeholder without a value stays raw on the page: {titolo} visible on screen is the typical symptom of an unparsed block or a file loaded under the wrong name.
2.2 <!--BeginName--> … <!--EndName--> blocks
<ul>
<!--BeginRiga-->
<li><a href="{url}">{etichetta}</a></li>
<!--EndRiga-->
</ul>
while ($db->nextRecord()) {
$tpl->set_var("url", ...);
$tpl->set_var("etichetta", ...);
$tpl->parse("SectRiga", true); // true = append (loop); false = replace
}
⚠️ Markers are NOT HTML comments
<!--BeginRiga-->looks like a comment but it's a template engine directive.ffTemplate::getBlock()doesstrpos($sTemplate, "<!--Begin" . $sName . "-->"): a literal string comparison, with no tolerance for spaces.So, in any reformatting or mass clean-up:
- don't remove them;
- don't add spaces:
<!-- BeginRiga -->is broken;- don't reformat the surrounding comments in a way that swallows them;
- don't reorder or move them: Begin/End delimit a block and must stay paired and nested as before.
If a marker breaks,
getBlock()returns an empty string,replaceBlock()leaves the template untouched and the{placeholders}stay raw. If the marker is in a shell (guscio.html,guscio-pubblico.html), CSS, JS and menus of every page break. It's not an error lint catches: the PHP compiles, the HTML is valid, you only find out in the browser.Check after a mass change to templates (must print
0):grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \ --include='*.html' --include='*.php' . | grep -v '/docs/' | wc -lKnown false positive:
themes/library/plugins/jquery.dynatree/doc/, where they're real comments.
2.3 Translations: {_word_code}
A placeholder starting with _ is resolved by ffTranslator against the ff_international table (joined on ff_languages, fallback to ITA). It's the multilingual engine: one template, N languages.
<h1>{_home_title}</h1>
The dictionary is managed from the backend in /restricted/international. See 08 — Auth, users and permissions for access, and the multilingual section of PANORAMICA_JOECMS.md for the overall strategy (dictionary for the interface, one file per language for legal pages, where long prose with interpolated data would make the dictionary fragile).
A text the visitor sees is never written in a single language. Where it goes, depending on what prints it:
| What prints it | Where the text lives |
|---|---|
a template (.html processed by ffTemplate, emails included) | a {_svc_…} dictionary code, in the installer's four languages |
| a template attribute read by a script | the same code in the attribute (data-err-…="{_svc_…}"): the text must not contain " |
a message from Auth or from an account widget | Auth::text() (vendor/wolfgan/auth/Auth.php), see 08 §1 |
| a script that writes by itself (popups, labels) | a per-language table in the script, chosen from <html lang> (themes/site/javascript/root.js) |
| a page that runs without the database (error, maintenance) | the tables in cm/errori.php, see 13 §1bis |
A new code goes into database.sql and into a migration, which fills the placeholders instead of inserting with fixed IDs (migrations/README.md). Whether the code exists in all four languages is checked on the dump: a missing code shows up on the page as it is (FF_TRANSLATOR_HIDE_CODE), and with a default language other than Italian there is not even the fallback to Italian.
2.4 The duplicate class
⚠️ The autoloader resolves ffTemplate to vendor/phpformsframework/ffTemplate.php, not ff/classes/ffTemplate.php: there are two copies of the same class. The loaded copy emits a Warning: Undefined variable $res on every parse(). In the web flow display_errors = 0 hides it, but it lands in the logs — and from the command line you see it. It's a pre-existing framework defect, not a symptom of a project problem.
3. Applets: reusable blocks
An applet is an applets/<name>/ folder with index.php (logic) and template.html (view). There's only one contract: the output goes into $out_buffer.
<?php
// applets/header/index.php
$filename = FF_DISK_PATH . "/applets/header/template.html";
$tpl = ffTemplate::factory(ffCommon_dirname($filename));
$tpl->load_file(basename($filename), "main");
$arrPath = explode("/", trim($cm->path_info, "/")); // the page context is available
$out_buffer = $tpl->rpparse("main", false);
Applets in the repo:
| Applet | Role |
|---|---|
applets/header | logo, navigation, [LANGUAGE_SWITCHER] |
applets/footer | legal links, copyright |
applets/homepage | hero + features of the default home page |
applets/meta-custom-page | per-page title/description/social, managed from the backend |
applets/services | not a layout applet: it's the folder of HTTP endpoints, see 03 |
Applets are wired in the seed and switched on/off by the wizard or by layout_path.visible (header = ID 2, footer = ID 3).
4. Layout: how blocks end up on the page
| Table | Role |
|---|---|
layout | the available blocks |
layout_path | which block on which path, with visible as the switch |
layout_location | the position in the shell (header, column, footer…) |
The layout is managed from /restricted/block and /restricted/themes. A project that doesn't want the CMS layout on a given page prints directly and calls exit (§1).
5. CSS and JS: what's automatic and what isn't
Two system functions decide the assets:
- JS —
system_set_js_level()inlibrary/gallery/system/set_js.php - CSS —
system_set_css_level()inlibrary/gallery/system/set_css.php
The mechanism works by naming convention: a file matching the page path is loaded by itself. In the ecosystem's projects the convention is:
| What | Where |
|---|---|
| page controller | contents/<name>.php |
| page template | themes/<theme>/contents/<name>/index.html |
| page JS | themes/<theme>/javascript/<name>.js — loaded automatically |
| page CSS | themes/<theme>/css/<name>.css — loaded automatically |
To add an asset by hand, use $cm->oPage->addJs(...) / addCss(...) from the controller.
⚠️ In JSON endpoints (/srv) the system bus clears $cm->oPage->page_js and page_css and logs those found in request_error_js / request_error_css: if there are any, something tried to decorate a response that isn't a page.
JoeCMS front end: modular SCSS
The site theme's CSS is written as modular SCSS in themes/site/css/root/ (_color, _sizes, _font, _typography, _base, _components) and compiled into root.css; brand tokens live in themes/site/css/joecms-brand.css. A new project changes palette and typography by touching two partials, not a monolithic CSS.
6. Available themes
| Theme | Use |
|---|---|
themes/site | public front end |
themes/gallery | /restricted backend (Foundation) |
themes/admin | skin for the backend changes (css/ff-skin.css) |
themes/responsive | forms framework widgets (ff/) |
themes/vgnext | new content management area |
themes/library | JS/CSS vendors |
Theme environment config: themes/site/conf/config.local.php (development) and config.remote.php (production, written by the installer with chmod 0640). HTTP_HOST decides which of the two is loaded — a detail that matters a lot from the command line, see 13 — Observability and CLI.