Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Developing Themes for Web Store 3
##Introduction This document will detail how Themes are created for the new Web Store. Themes are variations in color, styling and limited object placement that affect the display of Web Store products and information. (Prior versions of Web Store used the term "templates", but we have switched to using "Themes" both because it is the preferred terminology of the Yii framework that Web Store is built upon, and to differentiate from the old system since the files work differently.)
##View layer structure Web Store is built on the Yii framework (http://www.yiiframework.com), an MVC framework for PHP. The files that control the layout of the store are in the View Layer, which largely contains HTML and CSS, as well as PHP commands from the framework to display the various elements. The View layer in Yii is hierarchical, made up of broad layout files which control major components of the layout (headers, sidebars, footers, etc), with individual files for the individual pieces.
##Layout files The top of the pyramid is the "layout" file. There are two layout files in a default Yii installation, "column1.php" and "column2.php". As you can probably tell by their names, these control the layout in either a single column (the entire width of the page), or in two-column format. For Web Store purposes, column1 is used whenever we wish the content to display all the way across, such as on the checkout page. Column2 is used when we display content taking up about 70% of the page, with our shopping cart and sidebars displaying along the right side in a second column.
No matter if you're using column1 or column2, they each call a file main which is the primary HTML wrapper page. (Note that all view and theme files are .php files, but for convention, we won't keep repeating the extension here. You can assume a file such as "main" is named "main.php".) Main is the file that begins "<!DOCTYPE html>" and ends by closing our "</body>" tag. Main in turn calls other files, for things like our <head> meta data, menus, navigation bars, etc. All of these files are located in /views/layouts which you can view. (If you have followed our directions for copying a theme, these files will all be under /themes/brookyn-copy/views)
(Note that our documentation will refer to brooklyn-copy as the theme in progress here because generally most people will copy that theme to work with. If you have made a copy of a different theme, you would have a different folder name.)
Web Store has a default programmed in for each type of page (i.e. checkout uses column1, but custom pages, product display, customer registration, etc. all use column2). However it is possible to override this within the template files, as we will discuss later. Important: There is a Yii documentation page which discusses the hierarchy and view flow which you should read at http://www.yiiframework.com/wiki/249/understanding-the-view-rendering-flow/
##Files for each controller
In MVC parlance, a Controller can be thought of as a major section of Web Store. For example, we have a Product controller which is responsible for all the product detail pages. We have a Custom Page controller which is responsible for all custom pages. The Cart controller is responsible for both cart display and editing, and the entire checkout process. There's even a Site controller which handles functions that are global no matter where you are in Web Store, such as the menuing, login button, headers and footers.
For every major Controller, there is a set of corresponding View files that go with it. In the /views folder, you'll see subfolders that match each of these Controller names. The cart subfolder contains our view files that belong to anything cart related, such as displaying the cart and our checkout. The mail subfolder are for view files that deal with anything sent by email, such as receipts to the user, or when someone uses the Contact Us form to email the store.
The structure of these folders makes it very easy to find and customize the portion of the program you're looking for. If you wish to change how the headers or footers look, these can be found in the site view folder since the Site controller handles the global functions.
##The difference between Themes and View Layer files It is important to note that when you customize Web Store, you should not touch any of the View Layer files directly (located under /core/protected/views). In fact, on hosted systems, these files are marked as read-only to prevent changes from the outside. Instead, we have Themes, which override the view layers in places where we wish to customize the layout.
In Web Store (and in Yii in general), Themes act as "onion layers". If the system finds a theme file for a specific function, it will use it to override the default functionality of the system. If it does not find a page, the system will simply use the default view. This is why we have a two-step procedure to create a theme, an initial step which does copy all the view files to your theme, but also a cleanup at the end which removes unmodified files and leaves the theme folder with ONLY changed files.
This allows the modified files in your theme to take priority, but other view files revert back to the core view files.
This means in practice, that creating a new theme can be as simple as creating a new CSS file with changes in colours and fonts, in a themes folder (such as /themes/brooklyn-copy/css/style.css), because the system will use your custom CSS with the default layout files. If you are wanting to override a specific file without having to copy the entire viewset again, you can always manually copy any file from /core/protected/views and place it in the equivalent folder under your /themes/brooklyn-copy/views folder.
It is also possible to override the layout files in the same way. Just as you duplicate the folder structure for the view files themselves, you can create /themes/brooklyn-modified/views/layouts and place a file such as main.php to override that particular file. As with the other view files, you should only override what is absolutely necessary to do your customizations.
In order to make current and future customization easier and more orderly, Web Store uses the concept of viewsets. Simply put, a Viewset refers to the complete collection (set) of master view layer files upon which themes are based. At release time, the only viewset available is called cities. The default theme for Web Store 3 is Brooklyn (a port of the template set from Web Store 2.5.) For purposes of organization, derivative themes based on a viewset would follow a matching naming convention. In the case of cities, other themes would also carry city names so as to be easily identifiable (by technical support, for example) to which viewset they belonged. Thus in addition to Brooklyn, themes could be called "Miami", "Tokyo", etc, or any city-sounding names such as anything ending in "ville". Future viewsets developed by LightSpeed will carry a different moniker (to choose an example, "mountains") and those derived themes would be named to match.
The viewset itself is located under the protected folder, and is named views-cities. All viewset folders will always be named using "views-" followed by the name. Names should be all lower case with no spaces. Admin Panel looks for this pattern when displaying available viewsets to the user, and Admin Panel will point to the correct folder automatically for whatever viewset the user has chosen (this is done by a symbolic link on the web server itself).
Third-party companies may choose to create their own viewsets and their own theme collections, to be entirely supported by that company. Default functionality (for example, buttons that submit AJAX requests like the Apply Promo Code button on checkout) should still function as expected by formatting and submitting requests in the same way. Practically speaking, we recommend that companies begin with simpler theme development based on cities and only develop viewsets if they wish to radically alter the layout of the views or they have specialized needs.
It should be noted that it is technically possible to completely supersede the viewset by creating a theme which contains every file normally found in the viewset, meaning that Web Store would use all the theme files and none of the underlying view files. In this instance, you are no longer really using the view from Web Store. However, this violates the principle of how views and themes work together and is not recommended. If you are changing enough files where little of the view is being used, this may be a case where creating your own viewset is a consideration.
##Twitter Bootstrap The views have been designed using Twitter Bootstrap layout, a set of files which makes design easier. Twitter Bootstrap (http://twitter.github.com/bootstrap/) has been included as part of a Yii extension, so the file are always loaded. This is why you do not find the links to the files in the HTML Header document. Yii adds them as part of the display process. The most used portion of Twitter Bootstrap in Web Store is the grid system for layout. The grid system divides up the page into 12 columns, and your view files use <div class> statements to specify with (such as <div class="span5">My Content Here</div> to display content using 5 columns). It is high recommended you read up on columns at http://twitter.github.com/bootstrap/scaffolding.html#gridSystem since they will assist greatly in layout.
One advantage of using the grid system is proper collapsing on smaller screen sizes. For example, a page with hardcoded widths may display incorrectly on an iPad or iPhone, or force the user to zoom in and out and scroll to view the content. Proper use of a grid means that the screen will resize automatically and look correct on each platform. The Brooklyn theme on a desktop will also show on an iPad, and you will even see scaling differences between iPad landscape and portrait mode as you turn the device. It will always present correctly.) Any modifications to themes should not break this functionality, and your templates should operate correctly on both platforms. (Submissions to the template gallery will be tested for this functionality.) iPhone is particular challenge and we are generally more forgiving of "perfection" when displaying on an iPhone. However, the template should still be usable to navigate products and perform a checkout.
Because Twitter Bootstrap is always installed, you can use anything available in the package. There is also default css loaded by Web Store that we have used for buttons in lieu of Twitter Bootstrap buttons. You are free to use either.
Each theme folder should contain a file called config.xml which is read by Web Store Admin Panel to display titles and options for the theme. We have a complete file describing how this file is created at Creating customizable options for a theme