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:

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
|   |-- action-lock.js              holds back grid actions while one runs
|   |-- 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
|   |-- dgs-list.js                 DGS grid without a page reload
|   |-- dgs-mobile-list.js          selection bar, sheet menus and main action of a phone grid
|   |-- store-dialog-guard.js       Discard Changes? for a store form
|   |-- page-navigation.js          pages of one area without a page reload
|   |-- dgs-page-form.js            DGS form as its own page without a page reload
|   |-- loader.js                   wait indicator
|   |-- filter-panel.js             opens the filter panels and applies their filters
|   |-- filters-bar.js              folds the applied filters on a phone
|   |-- sheet.js                    grip, drag and close of the phone bottom sheets
|   `-- mobile-menu-gestures.js     gestures for the mobile menu
|-- bootstrap/                      Bootstrap: css, fonts, js
|-- styles/                         shared CSS, Font Awesome, loader.css, sheet.css, filters-bar.css
`-- 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>
<script src="<?php echo $assetsUrl; ?>js/action-lock.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.

Other scripts

A theme loads each of these scripts from assets/js/ after jimbo.js, when it needs it.

  • dgs-list.js (DgsList): a DGS grid marked data-ajax-list applies its filters, sorting and paging without a page reload.
  • dgs-mobile-list.js (DgsMobileList): the phone layout of a DGS grid. It counts the checked lines in the selection bar, closes a sheet menu on a tap of its item, and moves a main action that a plugin marks in the browser to the header. DefaultTheme of the theme package loads it. See dgs-mobile-list.js.
  • store-dialog-guard.js (StoreDialogGuard): asks before a store form with unsaved changes is left. The theme sets StoreDialogGuard.phrases in the user's language.
  • page-navigation.js (PageNavigation): opens a page of the same area without a page reload. See Pages without a page reload.
  • dgs-page-form.js: the object DgsPageForm, which opens a DGS form as its own page without a page reload. It needs page-navigation.js. DefaultTheme of the theme package loads these two files.
  • loader.js (PageLoader) with styles/loader.css: shows a wait indicator when a load runs longer than a second. The theme prints the .b-loader markup.
  • mobile-menu-gestures.js (MobileMenuGestures): opens and closes the phone menu with a finger drag, and blocks the browser's edge swipe.
  • filter-panel.js (FilterPanel): opens and closes the filter panels of the theme and applies their filters, to the page address or by their form. DefaultTheme of the theme package loads it. See Filter panels.
  • filters-bar.js (FiltersBar) with styles/filters-bar.css: on a phone, folds the applied filters of a filter panel under a bar with their count. It does nothing for a panel without the bar, so a theme can load it on each screen. See Filters bar.
  • sheet.js (Sheet) with styles/sheet.css: on a phone, gives each bottom sheet a grip to drag it to full height, to shrink it or to close it. The theme registers the sheets of its libraries and gives the colours. See Bottom sheets.

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.
  • Name a new file in lowercase letters and hyphens. The global object inside it is PascalCase: dgs-list.js holds DgsList. See Naming Conventions.