SugarCRM Developer's Manual: Customize and extend SugarCRM

If you're using Windows then the first thing that you'll have to do is to find the SugarCRM directory. Obviously if you've installed everything manually then you'll know where the directory is—however, if you've used the Windows installer then it may not be quite so obvious. You may (or may not) know that the SugarCRM directory has to be in the document root for your web server, and if you've used the installer then this will probably be something like C:\Program Files\SugarCRM\oss\httpd\htdocs:

All you have to do is rename the directory (for instance our friend Pygoscelis might want it renamed penguin_pi for the Penguin P.I. organization), and then type the new URL into your browser (and for the Penguin P.I. organization this would be http://achilles/penguin_pi).

In this instance Linux isn't too different from Windows—all you need to do is find the SugarCRM directory (again it will be in your web server's document root), and then rename it appropriately:

mv SugarOS-Full-4.5.0f penguin_pi

With that done the new URL will work: (e.g. http://hector/penguin_pi/index.php?action=index&module=Home)

Having sorted out SugarCRM's URL we can turn our attention to the rest of the screen.

To start with you need to log on to the administrator account (by default this will be by using the user name 'admin'), and then go to the ADMINISTRATION: HOME screen:

Here you can either click Rename Tabs, or you can go to the Studio screen first:

Now you can rename any of the SugarCRM tabs to something more appropriate to your organization:

Once you've saved your changes your users will see something that relates to them. For example, here we've renamed:

And now Korora would have tabs that she'd immediately understand:

However, the screen still contains a large amount of the default text (which has nothing to do with Korora's job), and this would be even more apparent if Korora were to click on one of the newly named tabs such as Preliminary Investigations:

Still not exactly 'custom' is it? And I'm sure that you've had a look around the administration screens to change other details on the screen, but not had any success. That's because any further changes need to be done outside the SugarCRM application, in the SugarCRM custom directory.

We'll do most of our work in the SugarCRM custom directory—in fact we've been using it already. You'll find it in your SugarCRM folder on your web server, and if you take a look there, you will see that there's already a file in the folder—when we saved the changes to the tab names SugarCRM created custom/include/language/en_us.lang.php. Examination of the file will reveal the changes made:

<?php
$app_list_strings['moduleList'] = array (
  'Home' => 'Home',
  'Dashboard' => 'Dashboard',
  'Contacts' => 'Contacts',
  'Accounts' => 'Accounts',
  'Opportunities' => 'Preliminary Investigations',
  'Cases' => 'Investigations',
  'Notes' => 'Notes',
  'Calls' => 'Surveillance',
  'Emails' => 'Emails',
  'Meetings' => 'Meetings',
  'Tasks' => 'Tasks',
  'Calendar' => 'Calendar',
  'Leads' => 'Leads',
  'Activities' => 'Activities',
  'Bugs' => 'Bug Tracker',
  'Feeds' => 'RSS',
  'iFrames' => 'Web Sites',
  'TimePeriods' => 'Time Periods',
  'Project' => 'Projects',
  'ProjectTask' => 'Project Tasks',
  'Campaigns' => 'Campaigns',
  'Documents' => 'Documents',
  'Sync' => 'Sync',
  'Users' => 'Users',
  'Releases' => 'Releases',
  'Prospects' => 'Targets',
  'Queues' => 'Queues',
  'EmailMarketing' => 'Email Marketing',
  'EmailTemplates' => 'Email Templates',
  'ProspectLists' => 'Target Lists',
  'SavedSearch' => 'Saved Searches',
  'Invoice' => 'Invoices',
);
?>

And that should give you a clue as to how language customization works within SugarCRM.

We're not going to look at every tab screen—once you know how to modify one then you can make changes as required. Since we've already been looking at the Opportunities screen let's carry on with that—but don't forget that the techniques we use will apply on any other screen that you want to customize.

We've seen that we use a file called en_us.lang.php in order to make our own changes to the text displayed on the SugarCRM screen, and you may well reason that we'll use this file to make changes to any text on the screen. Well, you're nearly right. We will use an en_us.lang.php file—but not the same one. This time we're going to use a file called custom/modules/Opportunities/language/en_us.lang.php (remember that custom is in your SugarCRM directory—and you'll need to create the sub-directories and the file itself).

The way in which this works is quite simple—SugarCRM will look at its default language files for the text to be displayed. However, if you've got your own definitions in a custom file then it will use those instead. Of course, next you'll need the default definitions so that you know what to put into your custom language file.

You may have already worked this out (but in case you haven't) the default language file for 'Opportunities' is modules/Opportunities/language/en_us.lang.php. If you examine the file then you'll find that it contains similar data to the en_us.lang.php that we've already seen:

$mod_strings = array (
  'LBL_MODULE_NAME' => 'Opportunities',
  'LBL_MODULE_TITLE' => 'Opportunities: Home',
  'LBL_SEARCH_FORM_TITLE' => 'Opportunity Search',
  'LBL_VIEW_FORM_TITLE' => 'Opportunity View',
  'LBL_LIST_FORM_TITLE' => 'Opportunity List',
  'LBL_OPPORTUNITY_NAME' => 'Opportunity Name:',

As you can see, it contains the text to be displayed in the tab screen labels, and you may be wondering why we don't just edit this file instead. There are a few reasons:

So, the next stage is to edit the custom/modules/Opportunities/language/en_us.lang.php file so that it contains the text that you actually want to be displayed on the Opportunities screen:

<?php
$opp_single = 'Preliminary Investigation';
$opp_title = $opp_single . 's';
$mod_strings['LBL_MODULE_NAME'] = $opp_title;
$mod_strings['LBL_MODULE_TITLE'] = $opp_title . ': Home';
$mod_strings['LBL_LIST_FORM_TITLE'] = $opp_title . ' List';
$mod_strings['LBL_OPPORTUNITY_NAME'] = $opp_single . ' Name';
$mod_strings['LBL_NEW_FORM_TITLE'] = 'Create ' . $opp_title;
$mod_strings['LNK_NEW_OPPORTUNITY'] = 'Create ' . $opp_title;
$mod_strings['LNK_OPPORTUNITY_LIST'] = $opp_title;
$mod_strings['LBL_TOP_OPPORTUNITIES'] = 'My Top Open ' . $opp_title;
$mod_strings['LBL_DEFAULT_SUBPANEL_TITLE'] = $opp_title;
?>

Notice that we haven't just hard coded all of the label details—this time we're using some variables ($opp_single and $opp_title). This means, of course, that if you decide to change the name of the module then you only need to change one line of code to update all the labels.

Once you've saved the file you can see the effects immediately by going to the Opportunities tab:

Obviously you need to repeat this process for each of the tab screens, but before long you won't have a generic CRM system—you will have a CRM system that uses the same terminology as your organization.

We've now modified the SugarCRM screens so that any users recognize the language, but we can still do more to reflect your company's brand. The first thing to look at is the browser title. At the moment it will look like:

While we're not trying to cover up the fact that we're using SugarCRM, we are trying to stamp our own brand onto the application. To do this we'll need to edit the custom/include/language/en_us.lang.php file again, and add a line:

$app_strings['LBL_BROWSER_TITLE'] = 'Penguin PI - SugarCRM';

Now, you need to refresh the browser:

With the title set correctly, we can think about one of the most important parts of a brand—the company logo.

You may already have a logo that you're wanting to use with your SugarCRM installation. However, whether you're going to use an existing one, or you're creating a completely new one, there are a couple of things that you need to keep in mind:

Then it's just a matter of creating the image with an appropriate piece of software; for example, you could use Gimp (Gimp is the GNU Image Manipulation Program, and if it's not already on your computer then you can get it from http://www.gimp.org).

Once you have saved your image you'll want to apply it to your SugarCRM implementation—so, it's back to the main admininistration screen, where you need to click on System Settings:

And then you can upload the logo:

With that done you've got a SugarCRM implementation with:

Now your users can log on and see your company's SugarCRM application, and they'll know that it's something designed for them, and (hopefully) they'll be happy to use it:

At this stage you may decide that you don't need to do any further customizations to the look and feel of SugarCRM, and if that's the case then it's time to move on to Chapter 2 where we start looking at customizing the application contents. However, before you do that it's worth spending a little time considering another aspect of the SugarCRM front-end user experience—Themes.

You'll find that the easiest way to create a new theme is simply to copy an existing one and then modify it. Start by looking for the themes directory—a sub-directory of your main SugarCRM folder. On Linux you can achieve this by typing something like:

cd /var/www/htdocs/penguin_pi/themes
cp -R SugarClassic PenguinPI

or on Windows:

cd "C:\Program Files\SugarCRM\oss\httpd\htdocs\SugarCRM\themes"
copy sugarclassic penguinpi

You now need to move to your new directory, edit the config.php file, and add the theme name and description:

<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
$theme_name = "Penguin PI";
$theme_description = "Penguin PI theme";
$version_compatibility = 3.0;
$max_tabs = 12;
$png_support = false;
?>

Also in the directory you'll find all of the files needed for formatting the theme itself. For now we'll just look at a very simple modification—we'll change the theme so that any link is highlighted in yellow when the mouse pointer is placed over it.

All you need to do is edit the style.css file in your new theme folder, and make the following change:

a:hover {
             color: #666666;
             text-decoration: underline;
             background-color:yellow; //highlight the link
        }

You'll probably need to restart your browser, but once you have done so, then you'll be able to select your new theme from the drop-down list at the bottom of the SugarCRM screen:

This new theme will appear exactly the same as the Sugar theme, except that links will be highlighted in yellow when you place the mouse pointer over them:

Of course, when you've finished creating the theme that you want, then you can start thinking about removing the themes that you don't want.

Some themes are incompatible with your company image. So you go to the themes directory and delete the directory containing the offending theme.

Next time the browser is started the theme will be absent—and don't worry, if someone was using the theme that you've deleted then they move to to the next theme on the list by default in their next session.