Frontend Development

This section tells you how the Festi Framework makes the pages that a user sees, and how you change them.

The framework renders HTML on the server. The browser gets a complete page. JavaScript then adds behavior to the page.

The parts of the frontend

Part What it is Where it is
Theme The page layout: <head>, header, menu, footer, CSS, JS. A directory in the project: themes/<name>/
Theme package The PHP classes of the theme system, the HUI components, and the default DGS templates. Composer package festi-team/festi-framework-theme
ThemeAssets Shared JS and CSS files, with jimbo.js. The assets directory of a theme
Plugin templates The HTML of the page content. plugins/<Name>/templates/
Plugin static files The JS and CSS files of a plugin. plugins/<Name>/static/
HUI components PHP objects that render forms, buttons, dialogs, and other elements. $this->ui in a plugin and in a template
DGS Lists and forms that the framework makes from a schema. plugins/<Name>/tblDefs/
Jimbo.js The JavaScript library that handles server responses, dialogs, forms, and events. assets/js/jimbo.js in the theme

How the framework renders a page

sequenceDiagram participant B as Browser participant S as System plugin (Jimbo) participant P as Plugin method participant R as Response participant D as DisplayPlugin participant T as Theme B->>S: GET /users/ S->>P: onDisplayUsers($response) P->>P: includeStatic(), assign(), fetch('users.phtml') P->>R: $response->content = HTML of the content S->>R: send() R->>D: display($content) D->>D: Event EVENT_THEME_BEFORE_FETCH_MAIN D->>T: fetchMain($content) T->>T: Render main.phtml, head.phtml, menu T-->>B: Complete HTML page
  1. The system plugin finds the plugin method for the URL.
  2. The plugin method registers its static files, assigns data, and renders its template. The result is the HTML of the page content.
  3. The plugin method puts the content into the Response object.
  4. The Response object gives the content to the theme.
  5. The theme renders the layout template main.phtml and puts the content in it.
  6. The browser gets the complete page.

For an AJAX request or a dialog, steps 4 and 5 are different. The Response object sends only the content or a JSON object, and the theme does not render the layout. Jimbo.js in the browser then handles the result. See Response.

Pages of this section

You want to Read
Write a plugin template, give data to it, find which template file the framework uses Templates
Add JavaScript and CSS files to a page Static files
Make a theme, or learn how a theme works Theme package
Use and adjust the admin theme SmartAdmin theme
Use the shared JS and CSS files ThemeAssets
Send a result from a plugin method to the browser Response
Send events between the browser and the server Frontend and backend events
Use the JavaScript library of the framework Jimbo.js reference
Use the PHP UI components HUI guide
Make a dashboard page from blocks StageBuilder
Make lists and forms from a schema Data Grid Store
Replace a DGS template DGS templates
Add your own DGS field Custom DGS fields
Add a React application to a plugin ReactJS in a plugin
Test templates, components, and themes Frontend tests
Learn the rules and the restrictions Best practices and restrictions

jQuery

The frontend of the framework uses jQuery. The theme loads it. jimbo.js, the DGS, and the theme components need it.

jQuery is an old library, but it is simple and each browser supports it. The framework makes business applications, where a short development time is more important than a modern JavaScript framework. The server renders most of the interface, thus the scripts stay small.

  • Use jQuery, not $.
  • Use const and let, not var.
  • Do not start a variable name with $.
// Not correct
var $form = $('.f-db-form');

// Correct
const form = jQuery('.f-db-form');

All the rules are in Best practices and restrictions.

Jimbo.js

jimbo.js is the JavaScript library of the framework. It is in the ThemeAssets package, and the theme loads it and starts it.

jimbo.js does these things:

  • It processes each reply of the server (Jimbo.response()).
  • It opens the DGS forms in dialogs and shows the form errors.
  • It has an event bus for the scripts of the plugins.
  • It shows notifications, message boxes, and loading indicators.

See the Jimbo.js reference, Response, and Frontend and backend events.

Note: jimbo.js does not submit a form with the class f-form. To submit a form without a page reload, use the HUI form or the HUI dialog. They submit into a hidden <iframe>, and an onAjax method replies. See Response.

HUI components

HUI (HTML UI) is the PHP component library of the framework. A component is a PHP object that renders HTML from a template. The server renders the components.

echo $this->ui->button()
    ->setCaption(__('Save'))
    ->setCSS('btn btn-primary')
    ->fetch();

Use HUI components in templates. Do not write the HTML of forms, inputs, buttons, dialogs, and messages again.

See the HUI guide and the UI components reference.

CSS

The CSS of the interface comes from the theme. A project adds its rules in static/css/styles.css. A plugin adds its rules in its static/css directory.

Class names have a prefix for their role: b- (block), e- (element), m- (modifier).

<div class="b-login">
    <div class="e-row">
        <label class="e-label m-required"></label>
        <input class="e-input e-login" name="login" />
    </div>
</div>

See Static files and Best practices and restrictions.

ReactJS

Use ReactJS only for a page with much state in the browser. The Festi CLI makes a starter React application, and the build of the application writes its files into a plugin. The framework has no microfrontend runtime.

See ReactJS in a plugin.