Vues

Ubiquity utilise Twig comme moteur de template par défaut (voir Documentation Twig).
Les vues sont situées dans le dossier app/views. Elles doivent avoir l’extension .html pour être interprétées par Twig.

Ubiquity peut également être utilisé avec un système de vues PHP, pour obtenir de meilleures performances, ou simplement pour permettre l’utilisation de php dans les vues.

Chargement

Les vues sont chargées depuis les contrôleurs :

app/controllers/Users.php

 namespace controllers;

 class Users extends BaseController{
     ...
     public function index(){
                     $this->loadView("index.html");
             }
     }
 }

Chargement de la vue par défaut

Si vous utilisez la méthode de dénomination des vues par défaut :
La vue par défaut associée à une action dans un contrôleur est située dans le dossier views/controller-name/action-name :

views
     │
     └ Users
         └ info.html

app/controllers/Users.php

 namespace controllers;

 class Users extends BaseController{
     ...
     public function info(){
                     $this->loadDefaultView();
             }
     }
 }

Chargement et passage de variables

Les variables sont transmises à la vue dans un tableau associatif. Chaque clé crée une variable du même nom dans la vue.

app/controllers/Users.php

 namespace controllers;

 class Users extends BaseController{
     ...
     public function display($message,$type){
                     $this->loadView("users/display.html",["message"=>$message,"type"=>$type]);
             }
     }
 }

Dans ce cas, il est utile d’appeler compact pour créer un tableau contenant des variables et leurs valeurs :

app/controllers/Users.php

 namespace controllers;

 class Users extends BaseController{
     ...
     public function display($message,$type){
                     $this->loadView("users/display.html",compact("message","type"));
             }
     }
 }

Affichage dans une vue

La vue peut alors afficher les variables :

users/display.html

 <h2>{{type}}</h2>
 <div>{{message}}</div>

Les variables peuvent également avoir des attributs ou des éléments auxquels vous pouvez accéder.

Vous pouvez utiliser un point (.) pour accéder aux attributs d’une variable (méthodes ou propriétés d’un objet PHP, ou éléments d’un tableau PHP), ou la syntaxe dite « d’indice » ([]) :

{{ foo.bar }}
{{ foo['bar'] }}

Fonctions supplémentaires Ubiquity

La variable globale app donne accès à des fonctionnalités prédéfinies d’Ubiquity Twig :

app est une instance de la classe Framework et donne accès aux méthodes publiques de cette classe.

Obtenir la version installée du framework :

{{ app.version() }}

Renvoie les noms du contrôleur actif et de l’action :

{{ app.getController() }}
{{ app.getAction() }}

Retourne les wrapper classes globales :

Pour la requête :

{{ app.getRequest().isAjax() }}

Pour la session :

{{ app.getSession().get('homePage','index') }}

voir Classeframework dans API pour plus d’informations.

Chargement des vue PHP

Désactivez si nécessaire Twig dans le fichier de configuration en supprimant la clé templateEngine.

Créez ensuite un contrôleur qui hérite de « SimpleViewController », ou de « SimpleViewAsyncController » si vous utilisez Swoole ou Workerman :

app/controllers/Users.php

 namespace controllers;

 use Ubiquity\controllers\SimpleViewController;

 class Users extends SimpleViewController{
     ...
     public function display($message,$type){
                     $this->loadView("users/display.php",compact("message","type"));
             }
     }
 }

Note

Dans ce cas, les fonctions de chargement des assets et des thèmes ne sont pas prises en charge.

Assets

Les assets correspondent aux fichiers javascript, feuilles de style, polices de caractères, images à inclure dans votre application.
Ils se trouvent dans le dossier public/assets.
Il est préférable de séparer les ressources en sous-dossiers par type.

public/assets
     ├ css
     │   ├ style.css
     │   └ semantic.min.css
     └ js
         └ jquery.min.js

Intégration de fichiers css ou js :

{{ css('css/style.css') }}
{{ css('css/semantic.min.css') }}

{{ js('js/jquery.min.js') }}

{{ css('https://cdnjs.cloudflare.com/ajax/libs/semantic-ui/2.4.1/semantic.min.css') }}

{{ js('https://cdnjs.cloudflare.com/ajax/libs/semantic-ui/2.4.1/semantic.min.js') }}

CDN avec des paramètres supplémentaires :

{{ css('https://cdn.jsdelivr.net/npm/foundation-sites@6.5.3/dist/css/foundation.min.css',{crossorigin: 'anonymous',integrity: 'sha256-/PFxCnsMh+...'}) }}

Thèmes

Note

Les thèmes sont totalement inutiles si vous n’avez qu’une seule présentation à appliquer.

Ubiquity supporte des thèmes qui peuvent avoir leurs propres assets et vues selon le modèle du thème à afficher par le contrôleur. Chaque action du contrôleur peut utiliser un thème spécifique, ou peut utiliser le thème par défaut configuré dans le fichier config.php dans templateEngineOptions => array("activeTheme" => "semantic").

Ubiquity est livré avec 3 thèmes par défaut : Bootstrap, Foundation et Semantic-UI.

Installation d’un thème

Avec les devtools, exécuter :

Ubiquity install-theme bootstrap

Le thème installé est l’un des suivants : bootstrap, foundation ou semantic.

Avec webtools, vous pouvez faire de même, à condition que les devtools soient installés et accessibles (dossier Ubiquity ajouté dans le chemin du système) :

../_images/themesManager-install-theme.png

Création d’un nouveau thème

Avec les devtools, exécuter :

Ubiquity create-theme myTheme

Création d’un nouveau thème à partir de Bootstrap, Semantic…

Avec les devtools, exécuter :

Ubiquity create-theme myBootstrap -x=bootstrap

Avec les webtools :

../_images/themesManager-create-theme.png

Structure et fonctionnement des thèmes

Structure

Dossier vues d’un thème

Les vues d’un thème sont situées dans le dossier app/views/themes/theme-name.

app/views
        └ themes
               ├ bootstrap
               │         └ main
               │              ├ vHeader.html
               │              └ vFooter.html
               └ semantic
                        └ main
                             ├ vHeader.html
                             └ vFooter.html

La classe de base contrôleur est responsable du chargement des vues pour définir l’en-tête et le pied de page de chaque page :

app/controllers/ControllerBase.php

     <?php
     namespace controllers;

     use Ubiquity\controllers\Controller;
     use Ubiquity\utils\http\URequest;

     /**
      * ControllerBase.
      **/
     abstract class ControllerBase extends Controller{
             protected $headerView = "@activeTheme/main/vHeader.html";
             protected $footerView = "@activeTheme/main/vFooter.html";

             public function initialize() {
                     if (! URequest::isAjax ()) {
                             $this->loadView ( $this->headerView );
                     }
             }
             public function finalize() {
                     if (! URequest::isAjax ()) {
                             $this->loadView ( $this->footerView );
                     }
             }
     }

Dossier assets d’un thème

Les assets d’un thème sont créés dans le dossier public/assets/theme-name.

La structure du dossier des assets est souvent la suivante :

public/assets/bootstrap
                                ├ css
                                │   ├ style.css
                                │   └ all.min.css
                                ├ scss
                                │   ├ myVariables.scss
                                │   └ app.scss
                                ├ webfonts
                                │
                                └ img

Changement du thème actif

Changement persistant

activeTheme est défini dans app/config/config.php avec templateEngineOptions => array("activeTheme" => "semantic")

Le thème actif peut être modifié avec les devtools :

Ubiquity config:set --templateEngineOptions.activeTheme=bootstrap

Il est également possible de le faire à partir de la page d’accueil, ou avec les webtools :

Depuis la page d’accueil :

Depuis les webtools :

Cette modification peut également être effectuée au moment de l’exécution :

Depuis un contrôleur :

ThemeManager::saveActiveTheme('bootstrap');

Changement local non persistant

Pour définir un thème spécifique pour toutes les actions d’un contrôleur, la méthode la plus simple consiste à surdéfinir la méthode initialize du contrôleur :

app/controllers/Users.php

 namespace controllers;

 use \Ubiquity\themes\ThemesManager;

 class Users extends BaseController{

         public function initialize(){
             parent::intialize();
             ThemesManager::setActiveTheme('bootstrap');
         }
     }

Ou si le changement ne doit concerner qu’une seule action :

app/controllers/Users.php

 namespace controllers;

 use \Ubiquity\themes\ThemesManager;

 class Users extends BaseController{

         public function doStuff(){
             ThemesManager::setActiveTheme('bootstrap');
             ...
         }
     }

Changement de thème conditionnel, indépendamment du contrôleur :

Exemple avec une modification du thème en fonction d’une variable passée dans l’URL

app/config/services.php

use Ubiquity\themes\ThemesManager;
use Ubiquity\utils\http\URequest;

...

ThemesManager::onBeforeRender(function(){
             if(URequest::get("th")=='bootstrap'){
                     ThemesManager::setActiveTheme("bootstrap");
             }
     });

Support pour appareils mobiles

Ajouter un outil de détection des appareils mobiles.
Installer MobileDetect :

composer require mobiledetect/mobiledetectlib

Il est généralement plus facile de créer des vues différentes par appareil.

Créez un thème spécifique pour la partie mobile (en créant un dossier views/themes/mobile et en y plaçant les vues spécifiques aux appareils mobiles).
Il est important dans ce cas d’utiliser les mêmes noms de fichiers pour la partie mobile et la partie non-mobile.

Il est également conseillé dans ce cas que tous les chargements de vues utilisent l’espace de noms @activeTheme :

$this->loadView("@activeTheme/index.html");

index.html doit être disponible dans ce cas dans les dossiers views et views/themes/mobile.

Détection globale des mobiles (à partir de services.php)

app/config/services.php

use Ubiquity\themes\ThemesManager;

...

ThemesManager::onBeforeRender(function () {
     $mb = new \Mobile_Detect();
     if ($mb->isMobile()) {
             ThemesManager::setActiveTheme('mobile');
     }
});

Détection locale (depuis un contrôleur)

app/controllers/FooController.php

use Ubiquity\themes\ThemesManager;

...

     public function initialize() {
             $mb = new \Mobile_Detect();
             if ($mb->isMobile()) {
                     ThemesManager::setActiveTheme('mobile');
             }
             parent::initialize();
     }

Chargement de vues et d’assets

Vues

Pour charger une vue à partir du dossier activeTheme, vous pouvez utiliser l’espace de nom @activeTheme :

app/controllers/Users.php

 namespace controllers;

 class Users extends BaseController{

         public function action(){
             $this->loadView('@activeTheme/action.html');
             ...
         }
     }

Si le activeTheme est bootstrap, la vue chargée est app/views/themes/bootstrap/action.html.

Vue par défaut

Si vous suivez les conventions de nommage des vues Ubiquity, la vue par défaut chargée pour une action dans un contrôleur lorsqu’un thème est actif est : app/views/themes/theme-name/controller-name/action-name.html.

Par exemple, si le thème actif est bootstrap, la vue par défaut pour l’action display dans le contrôleur Users doit se trouver dans le fichier app/views/themes/bootstrap/Users/display.html.

app/controllers/Users.php

 namespace controllers;

 class Users extends BaseController{

         public function display(){
             $this->loadDefaultView();
             ...
         }
     }

Note

Les commandes devtools pour créer un contrôleur ou une action et leur vue associée utilisent le dossier @activeTheme si un thème est actif.

Ubiquity controller Users -v

Ubiquity action Users.display -v

Chargement des assets

Le mécanisme est le même que pour les vues : l’espace de nom @activeTheme fait référence au dossier public/assets/theme-name/.

{{ css('@activeTheme/css/style.css') }}

{{ js('@activeTheme/js/scripts.js') }}

{{ img('@activeTheme/img/image-name.png', {alt: 'Image Alt Name', class: 'css-class'}) }}

Si le thème bootstrap est actif, le dossier des assets est public/assets/bootstrap/.

Compilation Css

Pour Bootstrap ou foundation, installez sass :

npm install -g sass

Ensuite, exécutez depuis le dossier racine du projet :

Pour bootstrap:

ssass public/assets/bootstrap/scss/app.scss public/assets/bootstrap/css/style.css --load-path=vendor

Pour foundation:

ssass public/assets/foundation/scss/app.scss public/assets/foundation/css/style.css --load-path=vendor