0
Welcome Guest! Login
0 items Join Now

RocketTheme Blog

Basics: Debugging & Customizing with LESS/CSS

  • Friday, 29 March 2013 00:00
  • James Spencer

This guide is a brief overview of the tools for self help, providing you with the abilities to debug your own issues and identify what and how to customize in the same manner as the RocketTheme Team. Most styling issues, whether bugs or customization requests, are typically very easy to address yourself.

This guide outlines how to inspect, debug, amend and customize using LESS.

NOTE: This guide is primarily focused on Joomla, but most of the contents can be applied to all platforms.

References:

1. Custom Overrides (CSS/LESS)

The first step is to outline the process of how to customize or to amend the templates/extensions styling themselves. As general practice, we now recommend you use the inbuilt Custom Stylesheet facility in Gantry, or if you are using a pre-Gantry template, a manually added custom stylesheet. The benefits of this approach are two fold:

  1. Firstly, it prevents or mitigates the impact of updating the template when we issue updates, as all your style changes are located in a single file, so less likely to get lost.
  2. Secondly, its useful for your own debugging, as it consolidates all your changes, so at a glance, you can see your amendments and identify quickly if any of them are causing a problem.

Gantry

Gantry is included in all templates from Reaction (December 2009) onwards, so this part should be applicable to most situations.

Fortunately, there is a comprehensive guide on the Gantry Framework Documentation Site that addresses how to implement a Custom Stylesheet with Gantry, located here.

Basically, if you are using a non-LESS template, you will want to create a file in the /templates/[TEMPLATE]/css/ directory called [TEMPLATE]-custom.css, such as reaction-custom.css if you were using Reaction.

If you are using LESS, so templates from Fracture (September 2012) onwards, you'll want to create a file in the /templates/[TEMPLATE]/less/ directory in the format [LESS_FILE_NAME]-custom.less such as template-custom.less. This will automatically be compiled into the master.css file that is loaded in the template.

Non-Gantry

If you are using a non-Gantry template, you'll need to take a manual approach. You'll need to create a file, say [TEMPLATE]-custom.css in the template's /css directory, and add the call into the relevant file. As a general statement, the index.php file, in between the <head></head> tags, should be where you'd place the call for this custom.css file, but in our templates from MediaMogul to Iridium (our only non-Gantry templates that have Joomla 2.5 (or 3.0 pending) support, this is actually the rt_head_includes.php file.

I will take Iridium as an example here. Basically, as a general rule, locate any entries that loads a CSS file, such as:

$this->addStylesheet($this->baseurl."/templates/".$this->template."/css/template.css");

In this case, we'd just duplicate the line and change the call to our new custom.css file, such as:

$this->addStylesheet($this->baseurl."/templates/".$this->template."/css/custom.css");

If the format is different, such as in HiveMind, follow the same procedure of copy, paste and amend. For example, find:

<link href="<?php echo $this->baseurl; ?>/templates/<?php echo $this->template?>/css/template.css" rel="stylesheet" type="text/css" />

And add below:

<link href="<?php echo $this->baseurl; ?>/templates/<?php echo $this->template?>/css/custom.css" rel="stylesheet" type="text/css" />

Overriding CSS/LESS

The process of Adding Your Custom Rules and Properties is dealt with succinctly on the Adding a Custom Style Sheet tutorial, as referenced earlier.

In essence, if you just duplicate a CSS entry from the stylesheets, and put it in the custom CSS file, it won't override it, unless the CSS file is loaded first. Nevertheless, this a simple matter to address by using more specific tag entries.

For example, if we wanted to override the following:

.rt-block {padding: 15px; margin: 10px; position: relative;}

We'd have to either use !important (which we don't recommend unless in very exceptional circumstances), or use a more specific entry such as:

#rt-showcase .rt-block {padding: 15px 0; margin: 10px; position: relative;}

In this situation, we are using the #rt-showcase ID to force the override. Naturally, the additional tags have to be in the same hierarchy, as in, related to the element you are trying to override, in order to work. The process of doing this will be outlined below.

2. Web Inspector

This guide will primarily focus on Chrome's Web Inspector, although all major browser have their own inspector tools now, and Firefox benefits from Firebug, the source of the original blog entry.

The Web Inspector allows you to identify, and even amend live, elements of the page without having to touch the files themselves, which is an incredibly powerful tool in debugging and even customization.

HTML

The default view in most Web Inspectors, is to load the HTML/Source of the page. In Chrome, this is under Elements, HTML under Firebug. Essentially, it provides a cascade view of the source, showing you the relationship between each elements. For example, in the screenshot below:

<a href="/" id="rt-logo"></a>

Is the child of:

<div class="rt-block logo-block"></div>

This information is useful if you are wanting to do overrides as outlined in Step One above.

alt Image

In addition to inspection, you can also edit the HTML. You can edit the tag or its attributes inline by a double click, or right click and click Edit as HTML.

The usefulness of this facility depends on your intended use, but common examples can be:

  • Adding/Removing classes/ids on elements to check the behaviour without live changes.
  • Changing text to see how it will look.
  • Adding/Removing entire blocks of code to identify a possible cause of an issue.

NOTE: In Chrome at least, you can undo your immediate code changes with the Cmd + Z (Mac) or Ctrl + Z (Windows) keyboard shortcuts. Naturally, very useful when you've just removed a block of code without needing to refresh the whole page.

![alt Image](images/blog/coding/debugless/img2.jpg0

CSS Inspection

Within the same pane, Elements, you can also inspect and manipulate the CSS. This appears in the right column of the pane.

This section will show you what CSS is being applied to an element and its location, such as in our example:

.logo-type-gantry #rt-logo {
    
background: url(../images/logo/dark/logo.png) 0 0 no-repeat;
}
#rt-logo {
    
margin: 0;
    
width: 112px;
    
height: 46px;
    
display: block;
}

alt Image

Therefore, if we wished to override the margin, width, height or display of #rt-logo, we could use any tag that is above in the hierarchy to achieve that, such as, in reverse order:

  • .rt-block, .logo-block or .rt-block.logo-block
  • .rt-grid-3, .rt-alpha, .rt-grid-3.rt-alpha
  • .rt-container
  • #rt-header
  • Body classes: .logo-type-gantry .headerstyle-dark .font-family-helvetica .font-size-is-default .menu-type-dropdownmenu .layout-mode-responsive .col12

Therefore, as an example from the above list, we could use:

#rt-header #rt-logo {
    height: 100px;
}

Additionally, you can use any combination that you want to achieve the override. Nevertheless, do remember that some elements are repeated, so you may end up applying a CSS override to multiple elements unintentionally. In such a case, you will need to find a unique element, or add one yourself, such as a module class suffix or page class suffix.

The CSS pane will show you the file location and line number of the CSS that is applying to the selected element. The example below is for .rt-grid-3, which is located in the grid-responsive.css file on line 14. Hover over the element to locate the path of the file, in this case: /libraries/gantry/css/.

alt Image

CSS Customization

As with the Edit as HTML facility outlined above, you can also edit CSS live. There are three approaches:

  • Firstly, you can interact with the CSS directly in the CSS pane, such as changing #rt-logo's margin from 0 to 10px. Do this by clicking on the attribute or value, and typing. Tab to load changes if not automatically. You can disable a value by selecting the checkbox. Further, if you wish to add new attributes, click on the last value, in this case, block; and tab, it will insert a new line. Here you can add a new attribute and value, such as padding and 10px.
  • Secondly, you use the same method under element.style {}. Just click between the {} parentheses and start typing CSS.
  • Alternatively, you can click the + icon in the Styles pane of element.style {}. This will create a new CSS entry, so you can insert a new class/id then apply the CSS as outlined in the previous paragraphs.

Therefore, the CSS pane allows you to manipulate existing CSS, add CSS to a specific element inline, or create new CSS entries. Firefox offers more facilities, as you can edit the CSS files themselves directly, so is more convenient if you are doing mass changes.

3. Finding RokBooster/Compressed/Compiled CSS

NOTE: As general advice, always ensure that your permissions are correct, typically 755/644 or 775/664 (folders/files). This is particularly acute with RokBooster — although, do check its Advanced Permissions settings - if the site goes blank in the sense that no CSS is loaded.

However, the location of CSS files is no longer a simple affair, if you are using RokBooster, a LESS template, or any other 3rd party plugin that compresses, consolidates, combines or compiles files. This section therefore, will show you how to debug in this new environment.

RokBooster Files

With RokBooster, or equivalent caching extensions, the CSS files are compiled and collated into singular PHP files. This approach is the same for Javascript files also.

Therefore, you will need to disable RokBooster or any caching extension, then clear your Joomla Cache (Site → Maintenance → Clear Cache) and your browser cache. Load your site and inspect the elements again, as outlined in Step 2.

Below is an example from Chapelco:

alt Image

LESS (Compiled) Files

As an example, in the CSS pane screenshotted below, the #rt-logo CSS is being generated from a master-#.css file on line 1. This file has been compiled by LESS and compresses the entire code onto 1 line to improve performance. This is an output file, so you'll need to locate the source in order to make successful modifications or to locate the full CSS entry, maximising the success of an override.

alt Image

All master-#.css files are generated from the LESS files the the /less/ directory of the template which calls the master.css file.

However, the output CSS format is not replicated in the source CSS files, so the inspector will not tell you which source files, and what format, the source CSS is in. This requires a degree of user intuition to rectify.

The method I personally employ is to use a code editor, which has a multiple file opening/editing facility, or projects capability. Sublime Text, for Windows, Mac and Linux, has this ability; or TextMate, just to name a few examples.

Using Sublime Text 2 as an example, open all the LESS files in the /less/ directory. They will appear in the sidebar of the code editor.

alt Image

Then, use the Find All or equivalent (Find in Files for Sublime Text 2 - Cmd + Shft + F), keyboard command to do a search in all the files. For this example, we'll search for rt-logo. You will see all files and the line numbers where the referenced is located.

alt Image

The above example is simple, as its a single reference, and in the LESS files, it is in the traditional CSS format so is easy to find. LESS allows for far more complex code construction, that are not possible to do a straight search for. This section will outline key steps in successfully finding more complexly constructed elements.

The Joomla content icons (PDF/Email), in Gantry, have the following CSS applied to them:

.component-content ul.actions li a {
    
display: block;
    
font-size: 14px;
    
margin-left: 8px;
}

alt Image

However, if you searched for .component-content ul.actions li a in the LESS files, you will return 0 results. That is because, the following LESS is responsible for its output:

// Article Details
.component-content {
    ul.actions {
        float: right;
        li {
            list-style: none;
            display: inline-block;
            a {
                display: block;
                font-size: @baseFontSize;
                margin-left: 8px;
            }
        ...
        }
    ...
    }
...
}

alt Image

The <a> tag is nested inside several other tags, so requires a more focused search. As a general principle, you can search for each tag/class/id in the LESS files and ultimately you'll find the right entry. Nevertheless, some are generic such as LI and A in this example, or even .component-content which is a general class in Joomla. Therefore, try to refine your search to specific tags, in this case, ul.actions.

NOTE: Not all LESS files will come from the template per se, but may be imported from Gantry itself, such as the various Bootstrap entries. In such circumstances, you would want to locate them, for Gantry, the path is: /libraries/gantry/assets/jui/less/

Additionally, we always recommend that you override using the Custom Stylesheet/LESS approach outlined in Step 1. This is to ensure that changes are not wiped out. Nevertheless, finding the exact entry, particularly with LESS, makes the reproduction easier. For example, if we wanted to change the margin-left from 8px to 10px for the above ul.actions example, we could add the following:

body {
    .component-content {
        ul.actions {
            li {
                a {
                    margin-left: 10px;
                }
            }
        }
    }
}

Alternatively, the following is also acceptable, but if you are making several adjustments, it is easier to maintain the nested layout of LESS:

body .component-content ul.actions li a {margin-left: 10px;}

Inline Code

Furthermore, some CSS is loaded inline, such as when a style attribute is applied through the Template Manager, such as link color. Naturally, this will not appear in the CSS/LESS files. As an example, I am going to use Camber, and its general accent color, which on inspect, looks like the following:

#rt-container-bg .title span {
    
color: #D01A13;
}

The inspector indicates that it is being loaded from demo.rockettheme.com on line 44, which of course, isn't a specific file. With a RocketTheme template, this is what indicates its something being generated from the admin.

alt Image

Therefore, the easiest way is to change those values in the admin itself. Nevertheless, the original code is generated in /features/styledeclaration.php for Gantry templates.

$css .= '#rt-container-bg .title span {color:'.$gantry->get('body-accent').';}'."\n";

The value specifically comes from the /gantry.config.php file:

$gantry_presets = array (
    'presets' => array (
        'preset1' => array (
            'name' => 'Preset 1',
            ...
            'main-accent' => '#2C8BA6',
            ...
        ),
...

Nevertheless, you'll need to make a decision on which method is best, whether to edit in the admin, the core files directly, or override via a custom file. That varies on your specific circumstance, but hopefully this overview provides you with more options for inline style references.

Summary

I hope the above guide provides a useful overview of the tools and techniques employed in debugging issues and identifying what to customize. A basic understanding of what is involved allows you to make changes quicker and to a more extensive degree than ever before, that can always be complimented by our Moderating team.