theme framework

Themes

1. 1. Overview
2. 2. Themes
   1. 2.1. Theme Directory Structure
   2. 2.2. Theme Development
   3. 2.3. Changing a Theme
   4. 2.4. Creating a New Theme
   5. 2.5. Element Reference Guide
   6. 2.6. Packaging Custom Themes
      1. 2.6.1. Example Theme Manifest File
   7. 2.7. Tips

Overview

An overview of the theme framework

Themes

The goal of the Themes framework is to reduce the complexity of the current themes and the amount of work needed to create new themes in the product.
The framework also provides tools for easily changing a theme in an upgrade-safe way without modifing the theme directly.
This is all possible through an inheritance mechanism that is part of the framework, where themes can build upon other themes to build the user interface for the application. This directly reduces the duplication of code in the application, and enables new UI elements to be supported more easily in any theme.

 

 

Theme Directory Structure

The theme directory has a more formal structure to it, which must be followed in order for the inheritance mechanism in the themes framework to work correctly. It is as follows:

• ./themes/
• ./themes/<theme name>/
• ./themes/<theme name>/themedef.php
• ./themes/<theme name>/css/ (all css files go here)
• ./themes/<theme name>/css/style.css
• ./themes/<theme name>/css/print.css
• ./themes/<theme name>/images/ (all images go here)
• ./themes/<theme name>/js/ (all js files go here)

The themedef.php file specified also has a specific format to it so that it can be interpreted properly by the application. It is as follows:

$themedef  = array (


// theme name

'name'=> 'Sugar',

// short description of the theme

'description'=> 'Sugar',

// maximum number of tabs shown in the bar

'maxTabs'=> $max_tabs,


// true if png image files are used in this theme, false if gifs

'pngSupport'=> true,

// name of the theme this theme inherits from, if something other than the default theme.

'parentTheme'=> 'ParentTheme',

'barChartColors'=> array(....),

'pieChartColors'=> array(....),

);

Please note that only the 'name' specification is required; all other elements are optional.

Theme Development

When you are developing a new theme or adding modifications to an existing theme,
it is recommended to turn developer mode on in the 'System Settings' in the 'Admin' section of the application.

 

This is so that any changes you make will become immediately visible to you, making testing you changes easier.
Once the theme development is complete, it is recommended that you turn off the Developer Mode.

 

The theme framework performance is greatly enhanced with the use of an external caching mechanism such as APC or Memcache. It is highly recommended to have this in place.

 

Changing a Theme

Modifications to any theme in the application can be made in the custom/themes/ directory under the theme in question. For example, to replace the default Accounts.gif image in the Sugar theme, drop the new.gif image file into the custom/themes/<theme name>/images/ directory. You can do the same for CSS and JS files; in these cases the given files will be appended to the existing ones instead of being used in place of them.

The order in which directories are searched for overriding images/css/js files is as follows:

1. ./custom/themes/<theme name>/
2. ./themes/<theme name>/
3. any parent themes ( custom directory first, then regular one )
4. ./custom/themes/default/
5. ./themes/default/

 

 

Creating a New Theme

The easiest way to create a new theme is to find a base themes that you like and base your design on it. This reduces the amount of CSS work you'll have to do on your own, and you can rest assured that any theme fixes will also be fixed in your theme, thanks to inheritance. To do this, you'll need to create a themedef.php file with the following specifications in it:

$themedef= array(

// theme name

'name'=> \"MySugar\",


// optional, short description of the theme

'description'=> \"Sugar theme for me\",

// name of the theme this theme inherits from, in this case the Sugar theme

'parentTheme'=> \"Sugar\",

);

You can now add any CSS, images, and/or JS code to their respective directories to make the needed alterations to the parent theme to create the desired theme. It is by no means a requirement to derive a theme from one of the existing ones in the product; if you do not specify the 'parentTheme' attribute above, then the theme settings in the themes/default/ directory will be used.

 

Element Reference Guide

Below is a guide of the various id elements and classes that are used in the application. IDs are indicated below where they are prefixed by a # sign ( i.e. #dog for the ID dog ), and classes are specified by a '.' ( .cat for class cat ).

 

.edit      EditView containers

.detail    DetailView containers

.list       ListView containers

.view     Styles for any of the detail, edit. list, and search view containers

.search  Search container

 

The below figure illustrates the where the main UI div elements are located and what their IDs are.

Packaging Custom Themes

The Upgrade Wizard, accessible through the Admin screen, allows you to apply themes without unzipping the files manually. The theme is also actually added to the “Theme” dropdown on the Sugar Login screen.

The Upgrade Wizard relies on a file named manifest.php, which should reside alongside the root directory of your theme ZIP file.

The following section outlines the format of the manifest file. An example manifest file can be found in the following section:

• acceptable_sugar_flavors : Contains which Sugar editions the package can be installed on. Accepted values are any combination of: CE, PRO, CORP, ENT, and ULT.
• acceptable_sugar_versions : This directive contains two arrays:

  • exact_matches : each element in this array should be one exact version string, i.e. “6.0.0b” or “6.1.0”

  • regex_matches : each element in this array should be one regular expression designed to match a group of versions, i.e. “6\\.1\\.0[a-z]”

• author : Contains the author of the package; for example, “SugarCRM Inc.”
• copy_files : An array detailing the source and destination of files that should be copied during installation of the package. See the example manifest file below for details.
• description : A description of the package. Displayed during installation.
• icon : A path (within the package ZIP file) to an icon image that will be displayed during installation. Examples include “./patch_directory/icon.gif” and “./patch_directory/images/theme.gif”
• is_uninstallable : Setting this directive to TRUE allows the Sugar administrator to uninstall the package. Setting this directive to FALSE disables the uninstall feature.
• name : The name of the package. Displayed during installation.
• published_date : The date the package was published. Displayed during installation.
• type : The package type. This should be set to “theme”
• version : The version of the patch, i.e. “1.0” or “0.96-pre1”

Example Theme Manifest File

The following is an example manifest.php file:

<?php

$manifest= array(

'acceptable_sugar_versions'=> array(

         'exact_matches' => array(),

         'regex_matches' => array(

                     0 => '3.5.[01][a-z]?'


         ),

),

'acceptable_sugar_flavors'=> array(

0 => 'OS',

1 => 'PRO',

2 => 'ENT',

),

'name'=> 'Theme Name',

'description'=> 'Theme Description’,


'author'=> 'SugarCRM Inc.',

'published_date'=> '2005-09-15 16:00:00',

'version'=> ‘3.5.1',

'type'=> 'theme',

'is_uninstallable'=> TRUE,


'icon'=> 'ThemeName/images/Themes.gif',

'copy_files'=> array(

'from_dir'=> 'ThemeName',

'to_dir'=> 'themes/ThemeName',

'force_copy'=> array(),

),


);

?>

You’ll need to create a root directory that contains the theme directory. The name of this root directory (ThemeName) is what should be used in the from_dir element of the copy_files array in manifest.php. You’ll also need to place your manifest.php alongside this root directory. Create a ZIP file containing the root directory and the manifest.php file at the top level. Now your language pack is ready to be installed with the Upgrade Wizard.

Tips

• Pick your canvas : Think about how you want the general look and feel of your theme, and see which out-of-the-box existing Sugar theme best fits. This will reduce any extra work that may come out of rearranging the layout because you chose the first theme you saw.
• Replace All : When changing colors in the css files, do a “replace all” on the file. For example, if you are changing the color ‘#FF0000’ to ‘#CC0000’, change all instances of ‘#FF0000’ to ‘#CC0000’. Eventually you will get to a point where you may want your changes to only affect one class, and may have to go back and refine some of the mass changes. However doing this initially will usually yield favorable results, and save you some time.
• Check your work : So you have all your css laid out and your home page looks good? Did you check your Edit and List views? Did you check the calendar popup widgets (from date fields)? Often, developers forget to check the css for Sugar Dashlets, reports and charts. Do not forget to do a thorough check, and keep in mind that you may have to tweak with navigation.css, layout_utils.php, and sugarColors.xml files before being finally done.
• Personalize your theme : Remember this is your theme now. If you want to add a new div, or introduce a new class, you do not have to make it fit within the confines of the theme with which you started. Most of the images are transparent and work fine, but changing the look and feel of those would add an extra degree of customization. So, go ahead and add your flash intro, embedded mp3 or Star Wars Background.