Skip to content
JoeCMS Download 3.1.5
Manual · 02

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, and contents/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() does strpos($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 -l

Known 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 itWhere 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 scriptthe same code in the attribute (data-err-…="{_svc_…}"): the text must not contain "
a message from Auth or from an account widgetAuth::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:

AppletRole
applets/headerlogo, navigation, [LANGUAGE_SWITCHER]
applets/footerlegal links, copyright
applets/homepagehero + features of the default home page
applets/meta-custom-pageper-page title/description/social, managed from the backend
applets/servicesnot 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

TableRole
layoutthe available blocks
layout_pathwhich block on which path, with visible as the switch
layout_locationthe 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() in library/gallery/system/set_js.php
  • CSS — system_set_css_level() in library/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:

WhatWhere
page controllercontents/<name>.php
page templatethemes/<theme>/contents/<name>/index.html
page JSthemes/<theme>/javascript/<name>.js — loaded automatically
page CSSthemes/<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

ThemeUse
themes/sitepublic front end
themes/gallery/restricted backend (Foundation)
themes/adminskin for the backend changes (css/ff-skin.css)
themes/responsiveforms framework widgets (ff/)
themes/vgnextnew content management area
themes/libraryJS/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.