SmartAdmin Theme

SmartAdmin is the primary theme of the Festi Framework for admin panels and dashboards. It is a theme directory that you install in a project. It supplies:

the page layout: header, left menu, mobile menu bar, content area
the sign-in, registration, and password recovery pages
the CSS of the admin interface (Bootstrap 3 and SmartAdmin)
the JavaScript of the admin interface (jQuery, jQuery UI, Bootstrap, app.js)
ThemeAssets with jimbo.js, as the assets directory

The Composer package name is festi-team/festi-theme-smartadmin.

Read these pages first:

Theme package describes how a theme works.
How to Adjust SmartAdmin tells you how to change the look, the templates, and the header without a change to this repository.

Install

With the Festi CLI

The installer of the Festi CLI adds SmartAdmin to a new project as a git submodule in themes/<theme name>. No more steps are necessary.

In a project that exists

Add the theme as a submodule. The directory name is the theme name.

git submodule add [email protected]:FestiThemes/PHP_Festi_Theme_SmartAdmin.git themes/dashboard

Get ThemeAssets. It is a submodule of the theme (assets).
```
git submodule update --init --recursive
```

Set the theme name in the entry script of the admin panel.

$options = [
    'theme_name' => 'dashboard',
];

$core = Core::getInstance($options);

Make sure that the web server serves themes/dashboard/. Open <base URL>themes/dashboard/css/main.css in the browser. The server must return the file.

Templates

Layout

Template	What it renders	Rendered by
`main.phtml`	The page: `<html>`, `<head>`, `<body>`, the content area, the scripts at the end of the page	`DefaultTheme::fetchMain()`
`head.phtml`	The content of `<head>`: meta tags, CSS, JS	`fetchHead()`
`header.phtml`	The header: logo, user activity block, projects list, right content, sign-out	`main.phtml`, only for a signed-in user
`left_panel.phtml`	The left panel: user name, menu, and the mobile menu bar	`main.phtml`, only for a signed-in user
`menu_main.php`	The menu in the left panel	`left_panel.phtml`
`menu_bar.php`	The menu bar for small screens	`left_panel.phtml`
`logo.phtml`	The logo with a link	`fetchLogo()`
`notifications.phtml`	The messages for the user, as growl notifications	`fetchNotifications()`

System pages

The Jimbo system plugin renders these templates. The theme supplies them.

Template	Page
`signin.php`	Sign-in form
`signup.phtml`	Registration form
`forgot_password.phtml`	Password recovery form

In these templates $this is the Jimbo plugin, not the theme.

Other templates

Template	Use
`pager.php`	The pager of a DGS list
`jform/*.php`	Form elements of the old form builder

What `head.phtml` loads

head.phtml loads the files in this sequence:

jQuery 2.0.2 and jQuery UI 1.10.3 from https://ajax.googleapis.com/. If that request fails, the template loads the copies in js/libs/. Then Bootstrap JavaScript from the theme.
The CSS files of the theme: Bootstrap and the component CSS, then main.css, main-mobile.css, db.css, and the CSS of the date and time picker.
The Open Sans font from https://fonts.googleapis.com/
qTip2 and SmartNotification from assets/
The CSS files of the project: <http_base>static/css/styles.css and <http_base>static/css/print.css
assets/js/jimbo.js and other shared scripts from assets/
The CSS files that plugins registered ($info['css'])
The JS files that plugins registered ($info['js'])
The tags from ISEODataProvider::EVENT_HEAD_TAGS
The HTML from ITheme::EVENT_THEME_HEAD_BOTTOM

main.phtml loads the SmartAdmin components and js/app.js at the end of <body>.

The template thus needs two external hosts: ajax.googleapis.com and fonts.googleapis.com. A project in a closed network gets jQuery from the local copies, but it does not get the font. A project with a Content Security Policy must permit the two hosts.

The project file static/css/styles.css loads after each CSS file of the theme.

The theme adds ?v<js_version> to main.css, main-mobile.css, styles.css, jimbo.js, app.js, and to each registered file. js_version is a setting of the system plugin.

The theme class

Theme.php contains the class Theme, which extends Festi\Theme\DefaultTheme. It adds:

Method	Use
`fetchRightHeaderContent()`	Returns the HTML for the right side of the header. It dispatches two events (see below).
`getMenuBarItemsCount()`	Returns the number of items in the mobile menu bar. The setting `mobile_menu_bar_items_count` controls it. Default: 5.

Events

SmartAdmin dispatches all the events of the Theme package and one event of its own.

ISmartAdminTheme::EVENT_THEME_HEADER_CONTENT_RIGHT

Triggered when the theme renders the right side of the header. The theme prints the HTML that the listeners return.

The value of the constant is ThemeHeaderContentRight.

Listening (init.php):

$this->addEventListener(
    'ThemeHeaderContentRight',
    function (FestiEvent &$event) {
        return '<div class="btn-header pull-right"><span><a href="/help/"><i class="fa fa-question"></i></a></span></div>';
    }
);

Use the event name as text in init.php. The framework loads the files of the theme only when it renders the first page. Thus the interface ISmartAdminTheme is not available when init.php runs.

ITheme::EVENT_THEME_FETCH_HEADER_ELEMENT

Triggered at the same location, before EVENT_THEME_HEADER_CONTENT_RIGHT. This constant is in the Theme package, thus it is available in init.php. Use this event when the listener must also work with a different theme.

Target: * position – right

Listening (init.php):

use Festi\Theme\ITheme;

$this->addEventListener(
    ITheme::EVENT_THEME_FETCH_HEADER_ELEMENT,
    function (FestiEvent &$event) {
        if ($event->getTargetValueByKey('position') != 'right') {
            return '';
        }

        return '<div class="btn-header pull-right"><span><a href="/help/"><i class="fa fa-question"></i></a></span></div>';
    }
);

Settings

The theme reads these settings of the system plugin:

Setting	Use
`js_version`	The version parameter of the CSS and JS URLs. Change it after each release.
`site_caption`	The site name in the page title.
`logo_url`	The logo on the sign-in page.
`enable_rememberme`	`1` shows the "remember me" checkbox on the sign-in page.
`enable_forgot_password`	`1` shows the link "Forgot your password?" on the sign-in page.
`enable_signup`	`1` shows the button "Create Account" on the sign-in page.
`mobile_menu_bar_items_count`	The number of items in the mobile menu bar.
`google_analytics`	The analytics snippet.

JavaScript

js/app.js does these things when the page is ready:

It calls Jimbo.init({debug: false}).
It starts the SmartAdmin components of the page (pageSetUp()).
It listens to Jimbo.EVENT_ON_DISPLAY_STORE_FORM and starts the components again when a DGS form shows.
It listens to Jimbo.EVENT_CALL_GROWL and shows each notification as a SmartAdmin small box.

Your scripts can use jQuery, Bootstrap 3, and Jimbo. Do not load a second copy of these libraries.

A request with the parameter popup gets the content without the layout, thus without <head>. For such a request, include.php adds the JS and CSS files that the page registered to the start of the content. The scripts load with the function loadScript() of the theme.

Tests

git submodule update --init --recursive
composer install
cd tests && ../vendor/bin/phpunit

The tests extend Festi\Theme\Tests\ThemeTestCase from the Theme package.