[Wiki] Building Your Web Application using a Theme++

What is Themes++ ?

With Themes++ you can construct your Web Application from a higher start point, including advanced menu and another improvments not present by default when you create a new Yii Application using yiic.bat.

What's the difference in comparison to existing yii themes projects ?

The main difference is themes++ is not only oriented to 'css and images', instead, is oriented to a -ready for use- application.

Download:

Themes++ is a subproject in my Github repository, it containts the Themes++ project and other tools like image uploader, etc. Please focus on 'themes' folder. Download Full Repository from Github

Or..you can browse Themes++ project on github directly. Download the 'protected' directory and your selected theme folder. Browse in Github

How is organizated

1. Various Themes reside under /themes/ folder, each one in its own folder, the folder name is the theme name.
2. The /protected provided directory contains extensions required by theme, and core components like WebApp.php.
3. Specific css and image files will reside under each parent theme folder.
4. A theme is invoked in your own application config file.

How to implement

1. Download or clone this repository (or simply download the entire 'themes' repository into your Yii instalation)
2. Specify your selected theme name for your app in your config file using: 'theme'=>'system-office-2'-, (locate it under: "'name'=>'My Web Application',")

Please be aware: copy all files involved in theme including -components and extensions- provided in github repository, because this is not only a simple theme layout, it is a theme++ !! , it has more requiered resources.

Available Resources

1. MbMenu component. Displays an extended Menu. I modify it to provide iconpack managment, using a very single configuration.
2. WebApp component. Provide some usefull functions to manage layout, menu, banners and resources.
3. Comming soon: An integrated multi-file uploader with drag and drop. ImageGallery support.

Using theme features

Extended MbMenu Component

I took the original MbMenu written by Mark van den Broek (mark@heyhoo.nl), an i add new features like: Theming and Iconpack. It is configured via components.WebApp.php class helper provided with Themes++ (this package).

Your MbMenu is initialized in: /themes/-yourtheme-/views/layouts/main.php

<div id="main-mbmenu"> <?php WebApp::getMbMenu($this); ?> </div><!-- mainmenu -->

The components/WebApp.php getMbMenu method:

public static function getMbMenu($controllerInstance){
            $controllerInstance->widget('application.extensions.mbmenu.MbMenu'
                ,array(
                    'themeSources'=>self::getThemeFolder().'/extras/mbmenu-sources/',
                    'iconpack'=>self::getThemeFolder()."/generic-icon-pack-16x16.png",
                    'items'=>self::getMenuItems()
                )
            );          
        }

As you can see i add two new arguments: themeSources and iconpack.

themeSources: point your MbMenu to look for sources at your theme directory named 'extras'.

iconpack: this a unique file for all your icons, each of them in a same file.

The Style for MbMenu is implemented into an extra theme folder: /themes/-yourtheme-/extras/mbmenu-sources/, here you can found the customized css and images for your menu, please remember to empty your assets folder after editing this sources

How to setup your menu items ?

In the same way yii startup project does. MbMenu allows you to specify two more extra arguments for each menu item: The 'items' for subitems, and a selected 'icon'.

Your MbMenu is initialized using WebApp.getMbMenu invoked from layout, in this method, you can see this line: 'items'=>self::getMenuItems(). The getMenuItems method contains an array of arrays, each of them containing your menu item.

A very basic menu entry is:

public static function getMenuItems(){
        return array(
            array(
                    'label'=>'Home', 
                    'url'=>array('/site/index'),
                    'icon'=>'-377px -234px',
                ),
        );
    }

please note that 'label' and 'url' are the same menu item arguments used by CMenu in your original Yii application, but it has two new arguments: icon and 'items'. (look at WebApp.php::getMenuItems to see a full usage for 'items' parameter, not showed in this basic example)

How to specify an icon for a top level menu ?

As you can see above, the 'icon' argument is configured in this way: 'icon'=>'-377px -234px' in your component WebApp (getMenuItems method).

Please remember that before in WebApp::getMbMenu you setup your iconpack argument, pointing it to a full graphic file containing all icons in one unique file. Now, with this in mind 'icon'=>'-377px -234px' indicates MbMenu to find an icon at position: x=377, y=234, please note the negative values, explain this negative value move this help beyond the objective, please use negative values or your icon will not be shown.

To style to your icon use a css class named '.menuicon' located in -your theme-\extras\mbmenu-sources\mbmenu.css, please remember to delete your assets content after any change to this sources.

Banner

A banner is an image located between your header and your content, and must be shown under your decision: for Home menu item only, or for every item. You can use any number of banners in your application.

In theme named 'system-office-3' you can observe a green banner that is shown only when home menu is visible, this is done using WebApp methods: getBannerFilename() and displayBanner().

To show an specific banner when index.php is shown then use:

<?php 
    echo WebApp::displayBanner(WebApp::getBannerFilename('home-banner.png'));
?>

Your 'home-banner.png' is a file located at your theme directory under css/ folder.

Why two functions to display a simple banner ? Because: one function gets the banner filename under your theme directory and another function displays the referenced banner. In this way you can customize the banner functions usage at your own.

Available Themes

This themes are applicable mainly for Online Systems, not simple web pages..

System Office #3

System Office #2

System Office #1