ltswitch Follow @yiiframework

Use this component, if you support multiple languages and/or themes in your application. If you host your yii-application for different customers with different themes you can configure hosts too. So this extension is not only a theme- or language picker.

Requirements ¶

Developed with Yii 1.1.12

Installation/Configuation ¶

• Extract the 'ELTSwitch.php' file to protected/components

• Configure the component in protected/config/main.php

Add it as a preload component after 'log'

// preloading components
     'preload'=>array('log','ltswitch'),
 
...
 
'components'=>array(
  ...
 
 
//----------- all options -----------
 
'ltswitch'=>array(
        'class'=>'ELTSwitch',
        'languages'=>array('de'=>'Deutsch','en'=>'English'),
        'themes'=>array('default'=>'Default theme','customer1'=>'Blue theme','customer2'=>'Red theme'), 
 
         //allow to switch the theme by GET param 'theme' only if is in debugmode
        'themeGetParam' => YII_DEBUG ? 'theme' : '',
 
        //allow to switch the language by GET param 'lang' only if is in debugmode
        'languageGetParam' =>YII_DEBUG ? 'lang' : '',
 
        //persist theme/language in a cookie
        'cookieDays' => 180,
 
        //Change the basePath of the themes: use aliaspath or absolute path
        //'basePath'=>'application.themes', //= /protected/themes
 
        //Change the baseUrl of the themes
        //relativ to app baseUrl
        //'baseUrl'=>'themes', //= (themes
 
        //configure allowed themes/languages depending on the (virtual) host
        'hosts'=>array(
            'localhost'=>array( //allow switch between all themes/languages
                 'themes'=>array('default','customer1','customer2'), 
                 'languages'=>array('de','en') 
                ),
            'customer1.myapp.com'=>array(
                'themes'=>'customer1', //fixed
                'languages'=>'de', //fixed: de only
            ),
            'customer2.myapp.com'=>array(
                'themes'=>'customer2', //fixed
                'languages'=>array('de','en') 
            ),
        ),
    ),
 
  ...
 
),

Comment the lines for themes if you only want to support different languages only and reveres.

I prefer to keep the themes code in the protected directory and only the public files in /themes/... So I configure the basePath/baseUrl property of the ELTSwitch like above.

Usage ¶

Switch the themes/language by

• The configured $_GET param: http://customer2.myapp.com/?lang=de, http://localhost/yiiapp/?theme=customer1

• By a post form, posting the value with the formvar 'eltTheme' / 'eltLanguage' (see the code of renderDropDownForm)

You can use the predefined dropdownLists (render a 'post' form, see code):

• Yii::app()->ltswitch->renderThemeDropDown()
• Yii::app()->ltswitch->renderLanguageDropDown()

These dropdownLists will only be rendered if the theme/language is not fixed by configuration/hosts

Use the functions

• Yii::app()->ltswitch->setTheme('customer1')
• Yii::app()->ltswitch->setLanguage('de')

for example after user login or in an ajax-call from your own nice looking language/theme picker ...

The current theme will be stored in the users session and in a cookie (if cookieDays>0 is configured). So you have to switch only once by GET/POST....

Helper methods ¶

• Yii::app()->ltswitch->getThemeName(): the longname of the current theme

• Yii::app()->ltswitch->getLanguageName(): the longname of the current language

• ELTSwitch::cssFile($file, $subDir = '',$media='', $absoluteUrl = false);

  echo ELTSwitch::cssFile('styles.css', 'css');
  will publish the 'styles.css' from 'themes/CURRENTTHEME/css'

• analog: ELTSwitch::scriptFile, ELTSwitch::image (see code).

more helper methods:

unsetTheme() / unsetLanguage() / getThemeNames() / getLanguageNames() / isFixedTheme() / isFixedLanguage()/getThemeFileUrl() see the comments in the code.

Module themes ¶

I prefer to keep the views code of a module together with the modules code and not in the global themes directory. So I can deploy/reuse a module easier. But Yii modules have no 'theme' property.

protected/modules/mymodule/views/CURRENTTHEME/site/...

You can execute the static method 'enableModuleTheme' in the init() of the module.

class MyModule extends CWebModule
{
 
    //public $theme; 
 
 
    /**
     * Set the viewPath to the yii-theme (or the modules theme)
     */
    public function init()
    {
        parent::init();
        ... 
        ELTSwitch::enableModuleTheme($this);      
    }
}

This will add the current yii theme to the viewPath of the module. If you add the property $theme, this will be used instead and you can configure the modules theme in main.php.

Resources ¶

• Theming guide