About Themes

From ZenMagick Wiki

Contents 1 Introduction 2 Themes and MVC 3 Anatomy of a Theme 3.1 The Essentials 3.2 The ThemeInfo class 3.3 Directory Structure 4 Telling zen-cart about a new theme 5 Not using ZenMagick themes 6 Switching themes programmatically

Introduction

Themes are ZenMagicks way of customizing the look & feel of the storefront pages. As with zen-cart, a set of default files exist, the default theme, that can be used as fallback. This frees the theme developer from cretaing/copying all theme files if only minor changes are required.

Unlike zen-cart, however, all theme specific code is stored in a single location. This includes extra code, language settings, custom classes and settings.

Themes and MVC

ZenMagick themes implement the view component of the MVC pattern. A quick overview about all components should be helpful to put things into perspective:

Controller

The controller (class) is responsible for processing each request. Each page (main_page parameter) can have a unique controller :class that implements the specific request handling.

Since the controller is not supposed to display the response directly, it wraps the data to be displayed in the model.

Model

The model are the class or classes that are used to pass application data like account or product details around. Model objects are created by the controller and passed on to the view in order to be displayed.

View

Views are responsible for rendering the response for the current request; eg. the HTML returned.

ZenMagick supports two different types of views:

• Layout
  A layout is similar to zen-cart's tpl_main_page.php in that it contains the main HTML structure. The actual page contents is then inserted using a content view.
• Content View
  The content view is responsible for rendering the page contents that changes from page to page (for example the shopping cart or address list).

Anatomy of a Theme

Each theme in ZenMagick consists of a set of files and directories located under zenmagick/themes/[theme]. Similar to zen-cart, the theme directory name is used as theme id.

The Essentials

The minimum requirements for a theme are:

• A theme directory
• A ThemeInfo class

Everything else is optional and if not found the default theme will be used as fallback.

The ThemeInfo class

The ThemeInfo class is ZenMagick's version of zen-cart's template_info.phh file that needs to exist for each template. The exact class name is build by converting the theme id (folder name). Luckily, a admin tool exists to create a new theme so there is no need to worry about that any more.

However, there is more. In contrast to template_info.phh, the ThemeInfo class can be used to control:

• the name of the default layout
• optionally the layout for particular pages
• the name of the generic error page
• an optional default JavaScript onload handler for all pages
• JavaScript onload handler for individual pages

Directory Structure

Here is the directory layout of a ZenMagick theme:

• themes
  • my_theme
    • MyThemeThemeInfo.php
      • content
        • boxes
          • categories.php
          • manufacturers.php
          • login.php
          • ...
        • views
          • account.php
          • account_edit.php
          • account_history.php
          • ...
        • default_layout.php
        • header.php
        • footer.php
        • site.css
        • ...
      • extra
        • local.php
        • ...
      • lang
        • english
          • l10n.php
          • i18n.php
          • ...

Telling zen-cart about a new theme

Creating a new ZenMagick theme does not make it automatically show up on in the Template Selection list in zen-cart admin. This is because zen-cart expects templates in it's own directory structure. Registering the new theme is pretty simple:

1. Load the ZenMagick Installation page.
2. In the first list of options there should be unchecked option Create admin dummy files for all installed ZenMagick themes
   That indicates that there really are ZenMagick themes zen-cart does not know about. Tick the checkbox
3. Click update. ZenMagick will then generate the appropriate folders and files for zen-cart to recognize the new themes.

Not using ZenMagick themes

Theme support is enabled by default. To disable ZenMagick theme handling, just create a file local.php (if it doesn't exist) in the ZenMagick installation folder with the following content:

<?php
    ZMSettings::set('isEnableZenMagick', false);
?>

Switching themes programmatically

The active theme is controlled by the class ZMRuntime. Using it's method setThemeId($themeId) you can switch between themes on the fly. The demo theme has some code in extra/local.php to illustrate that. For all contact_us page the theme is switched to the default theme:

<?php
    if ('contact_us' == $zm_view->getPageName()) {
        ZMRuntime::setThemeId('default');
    }
?>