Creating a Theme Admin Panel
As of Web Store 3.1, individual themes can have their own admin panel page. This allows theme designers to offer choices within Admin Panel that can affect layout, coloring, or other features. This guide will walk you through the process of creating a theme panel.
###Sample panel
Below is a sample admin panel we have made.
Simply put, a panel is simply a list of choices you provide the shop owner to make changes to the theme. Choices can be designed as On/Off switches, dropdowns with a number of choices, a radio button list, or a free form entry blank. The panel is simply an HTML form, so any controls you are used to using within a typical web page can be placed here.
Choices can also be made using other information from Web Store. For example, our new Image Gallery can be used to select a photo from the user's own library. A Color Picker Control, can allow a user to choose an RGB value which we will see in the next article.
For any value that the user has chosen, you can use these defined values in the logic of your form. This can include basic if/then logic, or passing a value as part of a URL. We will detail examples of these further in this guide.
###Structure
Every theme will have a file that makes up the AdminForm. This file contains your custom panel, as well as basic information about your theme including its name, version number, and options that affect how the theme operates.
This file is technically called a class file, a definition of how the theme operates.
###Theme naming and filenames
Your theme name can be whatever you want. Many LightSpeed-created themes are city names, a result of being based on one of the sets of view files (cities and cities2), but you are free to use anything you want. Bear in mind that your theme name will be used as both a foldername and a filename, so pick one without punctuation (ex. St. Peter poses a problem if you try and use the period).
###Sample File
class brooklyncopyAdminForm extends ThemeForm
{
/*
* Information keys that are used for display in Admin Panel
* and other functionality.
*
* These can all be accessed by Yii::app()->theme->info->keyname
*
* for example: echo Yii::app()->theme->info->version
*/
protected $name = "BrooklynCopy";
protected $thumbnail = "brooklyn.png";
protected $version = 1;
protected $description = "Our default template, suitable for any type of business.";
protected $credit = "Designed by LightSpeed";
protected $parent; //Used when a theme is a copy of another theme to control inheritance
protected $bootstrap = null;
protected $viewset = "cities";
protected $cssfiles = "base,style";
/*
* IMAGE SIZES
*/
protected $DETAIL_IMAGE_HEIGHT = 256; //Image size used on product detail page
protected $DETAIL_IMAGE_WIDTH = 256;
protected $LISTING_IMAGE_HEIGHT = 190; //Image size used on grid view
protected $LISTING_IMAGE_WIDTH = 190;
protected $MINI_IMAGE_HEIGHT = 30; //Image size used in shopping cart
protected $MINI_IMAGE_WIDTH = 30;
protected $PREVIEW_IMAGE_HEIGHT = 30;
protected $PREVIEW_IMAGE_WIDTH = 30;
protected $SLIDER_IMAGE_HEIGHT = 90; //Image used on a slider appearing on a custom page
protected $SLIDER_IMAGE_WIDTH = 90;
/*
* Define any keys here that should be available for the theme
* These can be accessed via Yii::app()->theme->config->keyname
*
* for example: echo Yii::app()->theme->config->CHILD_THEME
*
* The values specified here are defaults for your theme
*
* keys that are in ALL CAPS are written as xlsws_configuration keys as well for
* backwards compatibility.
*
* If you wish to have values that are part of config, but not available to the user (i.e. hardcoded values),
* you can add them to this as well. Anything "public" will be saved as part of config, but only
* items that are listed in the getAdminForm() function below are available to the user to change
*
*/
public $CHILD_THEME = "light"; //Required, to be backwards compatible with CHILD_THEME key
public $PRODUCTS_PER_PAGE = 12;
public $disableGridRowDivs = true;
//public $testvar;
public $menuposition = "left";
public $column2file = "column2";
/**
* Declares the validation rules.
*/
public function rules()
{
return array(
array('CHILD_THEME','required'),
array('menuposition,column2file','safe'),
//array('testvar','required'), //you can also stack items i.e. array('CHILD_THEME,testvar','required'),
);
}
/**
* Declares customized attribute labels.
* If not declared here, an attribute would have a label that is
* the same as its name with the first letter in upper case.
*/
public function attributeLabels()
{
return array(
'CHILD_THEME'=>ucfirst(_xls_regionalize('color')).' set',
'menuposition'=>'Products menu position',
'column2file'=>'Place shopping cart',
);
}
/*
* Form definition here
*
* See http://www.yiiframework.com/doc/guide/1.1/en/form.builder#creating-a-simple-form
* for additional information
*/
public function getAdminForm()
{
return array(
//'title' => 'Set your funky options for this theme!',
'elements'=>array(
'CHILD_THEME'=>array(
'type'=>'dropdownlist',
'items'=>array('light'=>'Light','dark'=>'Dark'),
),
'column2file'=>array(
'type'=>'dropdownlist',
'items'=>array('column2'=>'Left side','column2r'=>'Right side'),
),
// 'testvar'=>array(
// 'type'=>'text',
// 'maxlength'=>64,
// ),
),
);
}
}###Using theme panel information
In the Sample File above, notice there are two groups of variables, protected and public. Anything listed as a protected variable is "information" about the theme (not user configurable, but hardcoded into the theme definition) and accessed with the keyword info. Variables marked as public can be provided as an option to the user, and are accessed with the keyword config.
Protected variables can be accessed in your PHP theme file as
Yii::app()->theme->info->plus your variable name. For example...
Yii::app()->theme->info->namePublic variables are accessed as ```php Yii::app()->theme->config-> ``` For example ```php Yii::app()->theme->config->CHILD_THEME ```
Note that public variables may not actually be choices provided to the user in the admin panel (that depends on if it is listed in the form definition in the getAdminForm() section), but it would be always be available via Yii::app()->theme->config.