FuelPHP - Themes

Themes are used to enable multiple look and feel for the application. It provides option for the user/developer to change the look and feel of the application without disturbing the functionality of the application. An application can have one or more themes. Each theme lives in its own folder. Let us learn how to create themes in this chapter.

Theme Configuration

FuelPHP provides a separate configuration file for themes, fuel/app/config/themes.php. All theme related settings are configured in this file. Some of the main theme settings are as follows −

  • active − Name of the active theme

  • fallback − Name of the fallback theme, if active theme is not found

  • paths − Array of the path to search and find themes

  • assets_folder − Normally, assets need to be inside DOCPATH so that it will be accessible through web. It refers to the asset folder for the themes inside the DOCPATH

  • view_ext − Extension of the theme's view file

  • info_file_name − File having extended information about themes

  • require_info_file − Whether to require the theme information file, info_file_name

  • use_modules − Whether to use current module or not

Simple configuration for the theme file is as follows.

<?php  
   return array ( 
      'active' => 'tpthemes', 
      'fallback' => 'tpthemes', 
      'paths' => array ( 
         APPPATH.'themes', 
      ), 
      'assets_folder' => 'assets', 
      'view_ext' => '.html', 
      'require_info_file' => false, 
      'info_file_name' => 'themeinfo.php', 
      'use_modules' => false, 
   );

Here we have set,

  • The name of the active and fallback theme as tpthemes
  • The path of the theme folder as fuel/app/themes/
  • The path of the asset folder as /public/assets/tpthemes/

Theme Class

Once the configuration is done, we can use the class, Theme provided by FuelPHP to do the functionality of the theme. Let us know about the methods available in the Theme class in this chapter.

instance

instance method enables to create a new theme. It has the following two parameters,

  • $name − Name of the theme (optional)

  • $config − Theme configuration array (same as seen in configuration section)

Both parameters are optional. If no parameter is specified, it tries to get the default theme from the configuration file. If the theme name is specified, it tries to get the other settings from the configuration file. If configuration is specified as well, then it will use the user specified setting instead of setting from the configuration file.

$theme = \Theme::instance(); 
$theme = \Theme::instance('tpthemes'); 
$theme = \Theme::instance ('mytheme', array ( 
   'active' => 'mytheme', 'view_ext' => '.php'));

forge

forge is similar to instance, except it only has configuration array.

$theme = \Theme::forge (array( 
   'active'   => 'tpthemes', 
   'fallback' => 'tpthemes', 
   'view_ext' => '.php', 
));

view

view method uses the View::forge() in the background. Both API are similar except view method searches the view file in the themes folder, fuel/app/themes/tpthemes/ instead of fuel/app/views/ folder.

$theme = \Theme::instance(); 
$view = $theme->view('template/index'); 
// *fuel/app/themes/tpthemes/template/index.php

presenter

presenter method uses the Presenter::forge() in the background. Both API are similar except presenter method searches the view file in the themes folder, fuel/app/themes/tpthemes/ instead of fuel/app/views/ folder.

$theme = \Theme::instance(); 
$presenter = $theme->presenter('template/index');

asset_path

asset_path method returns the path to the asset requested relative to the currently selected theme.

$theme = \Theme::instance();  

// public/assets/tpthemes/css/style.css 
$style = \Html::css($theme->asset_path('css/style.css'));

add_path

add_path method allows to add a theme path at runtime.

$theme = \Theme::instance(); 
$theme->add_path(DOCROOT.'newthemes');

add_paths

add_paths method allows to add multiple theme path at runtime.

$theme = \Theme::instance();   
$theme->add_path(DOCROOT.'newthemes');

active

active method allows to set the active theme.

$theme = \Theme::instance(); 
$active = $theme->active('newtheme');

fallback

fallback method allows to set the fallback theme.

$theme = \Theme::instance();
$fallback = $theme->fallback('custom');

get_template

get_template method will return the View instance of the currently loaded theme template.

$theme = \Theme::instance(); 
$theme->get_template()->set('body', 'Theme can change the look and feel of your app');

set_template

set_template method allows to set the theme template for the page.

$theme = \Theme::instance(); 
$theme->set_template('layouts/index')->set('body', 'set theme template');

find

find returns true, if the path to the theme is found, otherwise it returns false.

$theme = \Theme::instance(); 
$path = $theme->find('newtheme')

all

all method returns an array of all themes in all theme paths.

$theme = \Theme::instance(); 
$themes = $theme->all();

get_info

get_info method returns a specific variable from the theme info array. If no theme is specified, the info array of the active theme is used.

$theme = \Theme::instance(); 
$var = $theme->get_info('color', 'green', 'newtheme');

Here, the method get the color is defined in ‘newtheme’. If it is not defined, then it will use ‘green’ as the default color.

set_info

set_info method sets a variable in the active or fallback theme.

$theme->set_info('color', 'green', 'fallback');

set_partial

set_partial method allows to set a view partial for a named section of your page template. Usually, it is done via HMVC call.

$theme = \Theme::instance(); 
$theme->set_template('layouts/homepage'); 
$theme->set_partial('navbar', 'homepage/navbar');

get_partial

get_partial method allows to get the view instance of a previously set partial in a named section of your page template.

$theme = \Theme::instance(); 
$theme->set_partial('sidebar', 'partials/menu'); 
$theme->get_partial('sidebar', 'partials/menu')->set('class', 'menu green');

Working Example

Let us add theme support in our employee application.

Step 1 − Add new theme configuration file, fuel/app/config/theme.php with the following content.

<?php  
   return array ( 
      'active' => 'tpthemes',
      'fallback' => 'tpthemes', 
      'paths' => array (APPPATH.'themes', ), 
      'assets_folder' => 'assets', 
      'view_ext' => '.html', 
      'require_info_file' => false, 
      'info_file_name' => 'themeinfo.php', 
      'use_modules' => false, 
   );

Step 2 − Add new asset folder, public/assets/tpthemes/css for the theme, tpthemes.

cd /go/to/app/root/path 
mkdir -p public/assets/tpthemes/css

Step 3 − Download the latest bootstrap and place the bootstrap.min.css under public/assets/tpthemes/css

Step 4 − Add new folder, tpthemes under fuel/app/themes folder.

cd /go/to/app/root/path   
mkdir -p fuel/app/themes/tpthemes

Step 5 − Add new layout template, bootstrap.html under fuel/app/themes/tpthemes/layout/ and add the following code.

<!DOCTYPE html> 
<html lang = "en"> 
   <head> 
      <title>Theme example</title> 
      <meta charset = "utf-8"> 
      <meta name = "viewport" content = "width = device-width, initial-scale = 1"> 
      <!-- Bootstrap core CSS --> 
      <?php echo \Theme::instance()->asset->css('bootstrap.min.css'); ?> 
   </head> 
   
   <body> 
      <?php echo $header; ?> 
      <div class = "container"> 
         <div class = "row">
            <div class = "col-sm-12"> 
               <?php echo $content; ?> 
            </div> 
         </div> 
      </div> 
   </body>
   
</html>

Here, we have used theme instance and asset method to get the path of the bootstrap file. We have defined two variables, header and content. header is defined to set the header details dynamically. content is defined to set the actual content of the page dynamically.

Step 6 − Add new header template, header.php at fuel/app/themes/tpthemes/partials as follows.

<div class = "jumbotron text-center">
   <h1>Theme support in fuelphp</h1> 
   <p>bootstrap based template</p>  
</div>

Step 7 − Create a new controller, ThemeSample at fuel/app/classes/controller/themesample.php and action at action_index as follows.

<?php  
   class Controller_ThemeSample extends \Controller { 
      public function before() { 
         $this->theme = \Theme::instance(); 
         $this->theme->set_template('layouts/bootstrap');  
         $header = $this->theme->view('partials/header'); 
         $this->theme->get_template()->set('header', $header); 
      }  
      public function action_index() { 
         $content = $this->theme 
         ->view('themesample/index') 
         ->set('message', 'This data comes from action page');  
         $this->theme 
         ->get_template() 
         ->set('content', $content); 
      } 
      public function after($response) { 
         if (empty($response) or  ! $response instanceof Response) { 
            $response = \Response::forge(\Theme::instance()->render()); 
         } 
         return parent::after($response); 
      } 
   }

Here, we have used before and after method to do the initialization of the theme using methods of Theme class. Some of the methods used are instance, get_template, set_template, and view.

Step 8 − Finally, add view for the index action, index.php at fuel/app/themes/tpthemes/themesample as follows.

<p>The data comes from *fuel/app/themes/tpthemes/themesample/index.html* file.</p> 
<p> 
   <?php echo $message; ?> 
</p>

Here, we have defined one variable, message, which needs to be set dynamically in the controller.

We have created a new theme, tpthemes and used it in ThemeSample controller. Let us now check the result by requesting the URL, http://localhost:8080/themesample/index. The result is as follows.

Theme Support
Advertisements