Convert a 3.0 theme config.xml to 3.1 AdminForm
In order for a 3.0 theme to take advantage of some of the new 3.1 features that have been implemented, it will need an Admin Form. This is a file that is similar to the existing config.xml file but better suited for usability within new versions of Web Store. Read on to learn how to transition the config.xml file into an Admin Form.
Before you go any further you should read this Admin Form article to quickly familiarize yourself with the file you will be creating.
- Make a copy of an existing Admin Form
- Use config.xml to rename and modify relevant variables
- Make changes to _head.php to ensure css files are rendered correctly
- Add any other necessary variables in AdminForm
Having reviewed the Admin Form article, let's go ahead and create that file. We will make a copy of the Brooklyn theme's Admin Form, place it in our custom theme, rename it and then modify it to suit. You should find Brooklyn's Admin Form in its models folder,
Copy this file and paste it into the same place in your theme. This may require you to create a folder in your theme's root called models. For this example our theme is called My Theme. So we create a file called mythemeAdminForm.php
Open your new admin form file. The first thing we want to modify is the class name. Change the section where it says 'brooklyn' to the name of your theme (all lowercase, no spaces). It should now look something like this,
class mythemeAdminForm extends ThemeFormNext we open our config.xml file. Consider the following example,
<config>
<viewset>cities</viewset>
<name>My Theme</name>
<thumbnail>mytheme.png</thumbnail>
<version>1</version>
<description>My Standard Theme for my Web Store.</description>
<noupdate>true</noupdate>
<credit>Designed by ACME Ltd</credit>
<subthemes>
<subtheme>
<name>Light</name>
<css>light</css>
</subtheme>
<subtheme>
<name>Dark</name>
<css>dark</css>
</subtheme>
<subtheme>
<name>Custom</name>
<css>custom</css>
</subtheme>
</subthemes>
<defaults>
<configuration>
<key_name>CATEGORY_IMAGE_HEIGHT</key_name>
<key_value>180</key_value>
</configuration>
<configuration>
<key_name>CATEGORY_IMAGE_WIDTH</key_name>
<key_value>180</key_value>
</configuration>
<configuration>
<key_name>DETAIL_IMAGE_HEIGHT</key_name>
<key_value>256</key_value>
</configuration>
<configuration>
<key_name>DETAIL_IMAGE_WIDTH</key_name>
<key_value>256</key_value>
</configuration>
<configuration>
<key_name>LISTING_IMAGE_HEIGHT</key_name>
<key_value>190</key_value>
</configuration>
<configuration>
<key_name>LISTING_IMAGE_WIDTH</key_name>
<key_value>180</key_value>
</configuration>
<configuration>
<key_name>MINI_IMAGE_HEIGHT</key_name>
<key_value>30</key_value>
</configuration>
<configuration>
<key_name>MINI_IMAGE_WIDTH</key_name>
<key_value>30</key_value>
</configuration>
<configuration>
<key_name>PREVIEW_IMAGE_HEIGHT</key_name>
<key_value>30</key_value>
</configuration>
<configuration>
<key_name>PREVIEW_IMAGE_WIDTH</key_name>
<key_value>30</key_value>
</configuration>
<configuration>
<key_name>SLIDER_IMAGE_HEIGHT</key_name>
<key_value>90</key_value>
</configuration>
<configuration>
<key_name>SLIDER_IMAGE_WIDTH</key_name>
<key_value>90</key_value>
</configuration>
<configuration>
<key_name>DEFAULT_TEMPLATE_THEME</key_name>
<key_value>dark</key_value>
</configuration>
<configuration>
<key_name>PRODUCTS_PER_PAGE</key_name>
<key_value>9</key_value>
</configuration>
</defaults>
</config>Using the information in config.xml, we make necessary changes. After the first few changes, our Admin Form should look something like this,
class mythemeAdminForm 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 = "My Theme";
protected $thumbnail = "mytheme.png";
protected $version = 1;
protected $description = "My Standard Theme for my Web Store.";
protected $credit = "Designed by ACME Ltd";
protected $parent; //Used when a theme is a copy of another theme to control inheritance
protected $bootstrap = null;
protected $viewset = "cities";The next variable $cssfiles is a list of the base set of css files necessary to render the theme correctly. We only include these base css files in the list and exclude ones that appear as subthemes in our config file. When we get to the section where we modify our _head we will recognize the importance of this variable.
In your theme folder, you should have a folder called css with all your css files.
Identify your base css files and then modify the $cssfiles variable to reflect the correct filenames.
protected $cssfiles = "mythemebase,mythemestyle";$GoogleFonts is the next variable.
protected $GoogleFonts = "Dosis:700,500,400|Ropa+Sans";This is meant to offer an elementary way to load Google fonts. Leaving this as it is will not affect your theme in anyway. You can edit it to reflect the Google fonts that your theme uses or you can remove it if you wish. For more information, take a look at our Google Fonts article.
Now we adjust the image dimension values to match our config.xml values. Note that the key_name as defined in config.xml is the same as the variable name.
protected $CATEGORY_IMAGE_HEIGHT = 180;
protected $CATEGORY_IMAGE_WIDTH = 180;
protected $DETAIL_IMAGE_HEIGHT = 256;
protected $DETAIL_IMAGE_WIDTH = 256;
protected $LISTING_IMAGE_HEIGHT = 190;
protected $LISTING_IMAGE_WIDTH = 180;
protected $MINI_IMAGE_HEIGHT = 30;
protected $MINI_IMAGE_WIDTH = 30;
protected $PREVIEW_IMAGE_HEIGHT = 30;
protected $PREVIEW_IMAGE_WIDTH = 30;
protected $SLIDER_IMAGE_HEIGHT = 90;
protected $SLIDER_IMAGE_WIDTH = 90;As of Web Store 3.1.5, users have the ability to disable or enable a css file from being included when the view is rendered via a checkbox. The variable $activecss is intended to govern the list of files that are active. It is necessary for Brooklyn's Admin Form for fresh installation scenarios, but not for other themes. Remove this variable from your Admin Form, there is already logic to build and maintain this array within the controllers.
Now we declare the default number of products that should display in the product grid and our default child theme. Just choose one of the subthemes for this value, EXCEPT custom. Note that these are defined as public variables.
public $CHILD_THEME = "dark";
public $PRODUCTS_PER_PAGE = 9;The next three variables are safe to ignore. While removing them should not affect your theme, it is recommended that they remain in the Admin Form.
public $disableGridRowDivs = true;
public $menuposition = "left";
public $column2file = "column2";Next we get to the functions. rules determine the importance of our modifiable attributes. According to our config.xml file we have more than one possible color scheme (child theme) that we can apply to our theme. We should ensure that this is defined, so we make it a required option.
/**
* Declares the validation rules.
*/
public function rules()
{
return array(
array('CHILD_THEME', 'required'),
);
}Displaying the variable as Child_theme in the Admin Panel is not very user-friendly. The function attributelabels() allows us to customize labels for our attributes. If this is not done, the option will display as its variable name, with the first letter in uppercase.
/**
* 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',
);
}ucfirst() makes the first letter uppercase, and _xls_regionalize() is an internal public function that outputs the expected spelling of a word according to the default country setting. In this case, 'color' is the parameter being passed so either 'Color' or 'Colour' will be displayed accordingly.
Lastly, the getAdminForm() function populates our AdminForm with our attributes so that they show up in the Admin Panel. For each attribute we declare the type and if necessary, the available options.
/*
* 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(
'elements' => array(
'CHILD_THEME' => array(
'type' => 'dropdownlist',
'items' => array(
'light'=> 'Light',
'dark' => 'Dark',
),
),
),
);
}_head.php is the file where we declare the css files necessary to render the theme. It will be located in views/site in your theme.
If you do not have this file then you do not have to modify anything as your theme will be reading from the updated file in the core. However, if you do have this file in your theme, check it for the following code, and REMOVE this code from the file.
<?php Yii::app()->getClientScript()->registerCssFile(Yii::app()->baseUrl.'/css/base.css'); ?>
<?php Yii::app()->getClientScript()->registerCssFile(Yii::app()->theme->baseUrl.'/css/style.css'); ?>
<?php Yii::app()->getClientScript()->registerCssFile(Yii::app()->theme->baseUrl.'/css/'._xls_get_conf('CHILD_THEME').'.css'); ?>
<?php Yii::app()->getClientScript()->registerCssFile(Yii::app()->theme->baseUrl.'/css/custom.css'); ?>We are replacing these static links to the CSS files here with a loop to load each file instead. This is because as of Web Store 3.1.5 there is a new feature to enable or disable individual CSS files from within the Admin Panel. In order for this feature to work, Web Store passes the names of the active CSS files to _head to display here.
Place this new block of code at the end of the file but before the closing html </head> tag.
<?php
foreach(Yii::app()->theme->info->cssfiles as $cssfile)
Yii::app()->getClientScript()->registerCssFile(Yii::app()->theme->cssUrl($cssfile));
Yii::app()->getClientScript()->registerCssFile(Yii::app()->theme->cssUrl(Yii::app()->theme->config->CHILD_THEME));
Yii::app()->getClientScript()->registerCssFile(Yii::app()->theme->cssUrl('custom'));
?>The foreach statement, goes through the base css list that we assigned to the $cssfiles variable and outputs the source location of each file in turn. Without this variable, our base css will not get rendered so it is imperative we include it in our AdminForm. The next two lines output the locations of the selected color scheme css file (child theme file) and the custom.css file.
The order that these files appear in the code block is also very important as it defines the override hierarchy. For example, anything in custom.css will trump settings in any other css file because it is declared last.
You may need to include a few other variables in your AdminForm to ensure the integrity of your theme. The following is a short list of possible variables you may want/need to include. Each is accompanied with some notes that describe how they affect the theme.
| Variable name | Type | Visibility | Usage Example |
|---|---|---|---|
| $showCustomIndexOption | bool | protected | protected $showCustomIndexOption = false; |
| $useCustomFolderForCustomcss | bool | protected | protected $useCustomFolderForCustomcss = true; |
Once you've completed the above, you should have the ability to configure your theme and edit your css files directly in the Admin Panel. The css should also render correctly on your public site.