Festi ThemeAssets

ThemeAssets (also named ThemeKit) is the set of shared JavaScript and CSS files for the themes of the Festi Framework.

A theme contains this repository as its assets directory. The theme templates load the files. The package has no PHP code.

Its most important file is js/jimbo.js, the JavaScript library of the framework.

Read these pages:

Jimbo.js Reference: the functions and the events of Jimbo
Theme package: how a theme works and how it loads these files
Response: From the Backend to the Browser: how the server controls jimbo.js

Purpose

Each theme needs the same JavaScript for the Data Grid Store (DGS), the HUI components, and the replies of the server. ThemeAssets keeps these files in one repository. Thus:

Each theme uses the same version of jimbo.js.
A plugin works with each theme, because Jimbo has the same functions in each theme.
A theme contains only its own design: layout templates, CSS, and images.

Package	Content
Theme package	PHP: the theme classes, the HUI components, the default templates.
ThemeAssets (this repository)	JavaScript and CSS that the default templates need in the browser.
A theme (for example SmartAdmin)	The layout templates and the design. It includes ThemeAssets as `assets`.

Content

ThemeAssets/
|-- js/
|   |-- jimbo.js                    the JavaScript library of the framework
|   |-- jquery.min.js               jQuery
|   |-- ui/                         jQuery UI
|   |-- qtip2/                      qTip2: tooltips for form errors
|   |-- notification/               SmartNotification: message boxes and notifications
|   |-- jquery.inputmask.min.js     input masks
|   |-- jquery.infinitescroll.js    infinite scroll
|   |-- jquery.combobox.js          combobox input
|   |-- tags/                       tags input
|   |-- calendar/                   date picker
|   |-- navbar/                     script of the default navigation bar
|   `-- MobileMenuGestures.js       gestures for the mobile menu
|-- bootstrap/                      Bootstrap: css, fonts, js
|-- styles/                         shared CSS, Font Awesome
`-- images/

Install

A theme adds this repository as a git submodule with the name assets:

git submodule add [email protected]:FestiCore/FestiFramework_ThemeKit.git assets
git submodule update --init --recursive

The URL of a file is then <theme_url>assets/<path>.

The SmartAdmin theme already contains this submodule. A project that uses SmartAdmin does not install ThemeAssets.

Load the files in a theme

Load the libraries in the head.phtml template of the theme. Load jQuery first. Load jimbo.js after the libraries that it uses.

<?php
/**
 * @var array $info
 */
$assetsUrl = $info['theme_url'].'assets/';
?>
<script src="<?php echo $assetsUrl; ?>js/jquery.min.js"></script>
<script src="<?php echo $assetsUrl; ?>js/ui/jquery-ui.min.js"></script>
<script src="<?php echo $assetsUrl; ?>bootstrap/js/bootstrap.min.js"></script>

<script src="<?php echo $assetsUrl; ?>js/qtip2/jquery.qtip.min.js"></script>
<link rel="stylesheet" href="<?php echo $assetsUrl; ?>js/qtip2/jquery.qtip.min.css">

<script src="<?php echo $assetsUrl; ?>js/notification/SmartNotification.js"></script>
<link rel="stylesheet" href="<?php echo $assetsUrl; ?>js/notification/notifications.css">

<script src="<?php echo $assetsUrl; ?>js/jimbo.js"></script>

Then start Jimbo one time in a script of the theme:

jQuery(document).ready(function () {
    Jimbo.init();
});

See What jimbo.js needs for the list of libraries.

Jimbo.js

jimbo.js defines the global object Jimbo. It does these things:

Area	What `Jimbo` does
Replies of the server	`Jimbo.response(data)` reads the action of a reply and does it: message, notification, redirect, reload, form errors, callback, content.
Events	An event bus: `Jimbo.addListener()` and `Jimbo.fireEvent()`.
DGS	Opens the forms of a list in dialogs, sends group actions, sends events to the store on the server.
Forms	Validates each form with the class `f-db-form`. Shows the errors of the server at the fields. It does not submit a form with the class `f-form`; see Submit without a page reload.
Messages	Message boxes, notifications, confirmation boxes, loading indicators.

Example: a script of a plugin sends a request and lets Jimbo process the reply.

const Orders = {
    done: function (id) {
        Jimbo.loadJson('/orders/' + id + '/done/');
    }
};

// Start the fields of a DGS form when the form shows.
Jimbo.addListener(Jimbo.EVENT_ON_DISPLAY_STORE_FORM, function (event, params) {
    if (params.store === 'orders') {
        Orders.initForm();
    }
});

The full list of functions and events is in the Jimbo.js Reference.

Rules

Do not change the files of this repository in a project. A change here has an effect on each theme and each project.
Do not load a second copy of jQuery or Bootstrap in a plugin.
Put the JavaScript of a plugin in the static directory of the plugin. See Static Files.
Extend Jimbo from your own file: add a listener or a function Jimbo.set<Type>Response.