|
Ubiquity uses Twig as the default template engine (see Twig documentation). |
The views are located in the app/views folder. They must have the .html extension for being interpreted by Twig. |
Ubiquity can also be used with a PHP view system, to get better performance, or simply to allow the use of php in the views. |
Loading |
------- |
Views are loaded from controllers: |
|
|
|
|
|
|
|
|
|
|
|
Default view loading |
~~~~~~~~~~~~~~~~~~~~ |
If you use the default view naming method : |
The default view associated to an action in a controller is located in |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Loading and passing variables |
----------------------------- |
Variables are passed to the view with an associative array. Each key creates a variable of the same name in the view. |
|
|
|
|
|
|
|
|
|
|
|
In this case, it is usefull to call Compact for creating an array containing variables and their values : |
|
|
|
|
|
|
|
|
|
|
|
Displaying in view |
The view can then display the variables: |
|
|
|
Variables may have attributes or elements you can access, too. |
You can use a dot (.) to access attributes of a variable (methods or properties of a PHP object, or items of a PHP array), or the so-called "subscript" syntax ([]): |
|
|
Ubiquity extra functions |
------------------------ |
Global |
|
Get framework installed version: |
|
Return the active controller and action names: |
|
|
Return global wrapper classes : |
For request: |
|
For session : |
|
see Framework class in API for more. |
PHP view loading |
Disable if necessary Twig in the configuration file by deleting the templateEngine key. |
Then create a controller that inherits from |
|
|
|
|
|
|
|
|
|
|
|
|
Note |
|
Assets |
====== |
Assets correspond to javascript files, style sheets, fonts, images to include in your application. |
They are located from the public/assets folder. |
It is preferable to separate resources into sub-folders by type. |
Assets integration with twig |
++++++++++++++++++++++++++++ |
Local files |
|
|
|
|
|
|
Integration of css or js files : |
|
|
|
CDN files |
|
|
CDN with extra parameters: |
|
Themes |
Note
The themes are totally useless if you only have one presentation to apply.
Ubiquity support themes wich can have it's own assets and views according to theme template to be rendered by controller. Each controller action can render a specific theme, or they can use the default theme configured at config.php file in templateEngineOptions => array("activeTheme" => "semantic")
.
Ubiquity is shipped with 3 default themes : Bootstrap, Foundation and Semantic-UI.
With devtools, run :
Ubiquity install-theme bootstrap
The installed theme is one of bootstrap, foundation or semantic.
With webtools, you can do the same, provided that the devtools are installed and accessible (Ubiquity folder added in the system path) :
With devtools, run :
Ubiquity create-theme myTheme
Creating a new theme from Bootstrap, Semantic...
With devtools, run :
Ubiquity create-theme myBootstrap -x=bootstrap
With webtools :
Theme view folder
The views of a theme are located from the app/views/themes/theme-name folder
app/views
└ themes
├ bootstrap
│ └ main
│ ├ vHeader.html
│ └ vFooter.html
└ semantic
└ main
├ vHeader.html
└ vFooter.html
The controller base class is responsible for loading views to define the header and footer of each page :
<?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 );
}
}
}
Theme assets folder
The assets of a theme are created inside public/assets/theme-name
folder.
The structure of the assets folder is often as follows :
public/assets/bootstrap
├ css
│ ├ style.css
│ └ all.min.css
├ scss
│ ├ myVariables.scss
│ └ app.scss
├ webfonts
│
└ img
activeTheme is defined in app/config/config.php
with templateEngineOptions => array("activeTheme" => "semantic")
The active theme can be changed with devtools :
Ubiquity config:set --templateEngineOptions.activeTheme=bootstrap
It can also be done from the home page, or with webtools :
From the home page :
From the webtools :
This change can also be made at runtime :
From a controller :
ThemeManager::saveActiveTheme('bootstrap');
To set a specific theme for all actions within a controller, the simplest method is to override the controller's initialize method :
namespace controllers;
use \Ubiquity\themes\ThemesManager;
class Users extends BaseController{
public function initialize(){
parent::intialize();
ThemesManager::setActiveTheme('bootstrap');
}
}
Or if the change should only concern one action :
namespace controllers;
use \Ubiquity\themes\ThemesManager;
class Users extends BaseController{
public function doStuff(){
ThemesManager::setActiveTheme('bootstrap');
...
}
}
Conditional theme change, regardless of the controller :
Example with a modification of the theme according to a variable passed in the URL
use Ubiquity\themes\ThemesManager;
use Ubiquity\utils\http\URequest;
...
ThemesManager::onBeforeRender(function(){
if(URequest::get("th")=='bootstrap'){
ThemesManager::setActiveTheme("bootstrap");
}
});
Add a mobile device detection tool. Installing MobileDetect:
composer require mobiledetect/mobiledetectlib
It is generally easier to create different views per device.
Create a specific theme for the mobile part (by creating a folder views/themes/mobile
and putting the views specific to mobile devices in it). It is important in this case to use the same file names for the mobile and non-mobile part.
It is also advisable in this case that all view loadings use the @activeTheme namespace:
$this->loadView("@activeTheme/index.html");
index.html must be available in this case in the folders views
and views/themes/mobile
.
use Ubiquity\themes\ThemesManager;
...
ThemesManager::onBeforeRender(function () {
$mb = new \Mobile_Detect();
if ($mb->isMobile()) {
ThemesManager::setActiveTheme('mobile');
}
});
use Ubiquity\themes\ThemesManager;
...
public function initialize() {
$mb = new \Mobile_Detect();
if ($mb->isMobile()) {
ThemesManager::setActiveTheme('mobile');
}
parent::initialize();
}
For loading a view from the activeTheme folder, you can use the @activeTheme namespace :
namespace controllers;
class Users extends BaseController{
public function action(){
$this->loadView('@activeTheme/action.html');
...
}
}
If the activeTheme is bootstrap, the loaded view is app/views/themes/bootstrap/action.html
.
DefaultView ~~~~~~~~~~
If you follow the Ubiquity view naming model, the default view loaded for an action in a controller when a theme is active is : app/views/themes/theme-name/controller-name/action-name.html
.
For example, if the activeTheme is bootstrap, the default view for the action display in the Users controller must be loacated in app/views/themes/bootstrap/Users/display.html
.
namespace controllers;
class Users extends BaseController{
public function display(){
$this->loadDefaultView();
...
}
}
Note
The devtools commands to create a controller or an action and their associated view use the @activeTheme folder if a theme is active.
Ubiquity controller Users -v
Ubiquity action Users.display -v
The mechanism is the same as for the views : @activeTheme
namespace refers to the public/assets/theme-name/
folder
{{ css('@activeTheme/css/style.css') }}
{{ js('@activeTheme/js/scripts.js') }}
{{ img('@activeTheme/img/image-name.png', {alt: 'Image Alt Name', class: 'css-class'}) }}
If the bootstrap theme is active, the assets folder is public/assets/bootstrap/
.
For Bootstrap or foundation, install sass:
npm install -g sass
Then run from the project root folder:
For bootstrap:
ssass public/assets/bootstrap/scss/app.scss public/assets/bootstrap/css/style.css --load-path=vendor
For foundation:
ssass public/assets/foundation/scss/app.scss public/assets/foundation/css/style.css --load-path=vendor