View on GitHub

Laravel theme bundle

Theme Bundle for laravel framework.

Download this project as a .zip file Download this project as a tar.gz file

Theme Bundle for Laraval framework

This bundle will help better organize the skin/theme of laravel applications. The bundle is designed to work as a wrapper to all the views loaded through laravel routes including controllers and those that sit under bundles.

How to Install

Installation is fairly easy as you would download and install any other bundle for laravel the same way. Download this bundle and copy the directory Theme and its file into the laravel bundles directory.

You can install this bundle by running the following CLI command:

php artisan bundle:install Theme

Alternatively you can download it directly from GitHub:

http://github.com/raftalks/Laravel_Theme_Bundle

That's it, congratulations you have installed the bundle.

Now go to your public directory and create a new directory called themes (/public/themes/). You will use this directory to add your themes.

Almost done.

Wait.. you need to do few settings before you can start using Theme Bundle.

Configuration

Activate Theme Bundle by editing path/to/laravel/application/bundles.php file and adding the following into the array.

return array(
    'theme'=>array('auto' => true)
);

Notice that we need to register the bundle with auto loading configuration enabled.

How to create a theme

Structure of a theme

How to use Theme Bundle within your application

It's easy, you will need to replace laravels' View::make() to $theme->render()

Please note that Theme is used as a library and to make it available to all other areas of laravel framework, the library is registered inside Laravels' IoC container. You can find the code inside the start.php file of this bundle.

Before you can start using the instance of the Theme library, you will need to pass that instance to your variable, preferably set it as $theme. To do this, you can use the following code inside your route or controller.

$theme = IoC::resolve('Theme');

Set Theme

To set the theme to be used with all the views, you may edit the file theme.php in the Theme bundle or pass the name of the theme object as shown below. $theme->set_theme("admin") ; //sets the library to use Admin theme from directory public/themes/admin

Set Layout to wrap your view

This is very useful. For example, you have separate layout for home page, blog list, post page, etc. 

function action_index(){
  $theme = IoC::resolve('Theme');

  $theme->set_layout('home'); // for controller action_index
  ...

In your layout files, you should include the following code in order to load the generated view from your application.

<?php echo $theme_content; ?>

Using Partials

Partials are considered like html entities that represent theme UI element group etc. For example the Navigation menu or Side bar listing related posts etc. Dynamic data needed for partials can be passed through composer method provided in this Theme library. You can also use helper function to load a partial file without initially binding it to the $theme object.

Example 1. Binding a partial to the $theme object before rendering the theme.

     $theme->theme_partial('main_navigation');
     $theme->theme_partial('sidebar');

Example 2. Loading a partial directly without binding the partial as done above.

    //inside layout file home.php
    <div id='navigation_container'>
       <?php echo theme_partial("main_navigation"); ?>
    </div>
    // you can use this as well, partial set as a variable prefixed with "theme_"
      <?php echo $theme_main_navigation;?>

Example 3. Passing data to partial

$theme->theme_partial('main_navigation', $data);
<?php echo theme_partial("main_navigation", $data); ?>

Binding Theme Partial with Composer

One thing I like most about laravel is its View Composer. This theme library supports composer binding to theme partial to pass processed data through function callback. Example.

 $theme->composer('main_navigation', function($view){
            $view->with('theme_main_navigation', "This is loaded from composer of the theme.");
 });

Using theme_function.php

This file sites in the root your theme folder. The function inside this file must always be named according to the pattern function theme_. The function must have one parameter that will get passed with instance of the theme object.

Example:

function theme_admin($theme){
     $theme->add_asset('bootstrap.min.css');
     $theme->add_asset('jquery-1.7.2.min.js');
     $theme->add_asset('bootstrap.min.js');
     $theme->theme_partial('header');
     $theme->theme_partial('footer');
}

Theme Assets & other methods

There are many other functions such as registering theme assets to be loaded to the layout. Example

$theme->add_asset('style.css');

In the theme layout or partial file containing the head tag of the html layout can load the asset files easily with following code.

<html>
<head>
<title><?php echo $theme_data['title']; ?></title>
    <?php echo $theme_data['metadata']; ?>
</head>
...

Page title tag

As you can see in above example, the title tag contain $theme_data['title'] to set the title string passed by the following method.

$theme->title("Welcome");

It is always best to explode the file theme.php in this bundle, to understand the methods available as some of them and advanced features of it is not explained in here.

Please feel free to use this bundle at your own risk and let me know if you need any help. I am usually available at IRC channel of Laravel.