Using CSS Classes - GeSHi/geshi-1.0 GitHub Wiki

Using CSS to highlight your code instead of in-lining the styles is a definate bonus. Not only is it more compliant (the w3c is deprecating the style attribute in XHTML 2.0) but it results in far less outputted code - up to a whopping 90% saving - which makes a huge difference to those unlucky of us on modems!

Enabling CSS Classes

By default, GeSHi doesn’t use the classes, so it’s easy just to whack out some highlighted code if you need without worrying about stylesheets. However, if you’re a bit more organised about it, you should use the classes ;). To turn the use of classes on, you call the enable_classes() method:

$geshi->enable_classes();

If you want to turn classes OFF for some reason later:

$geshi->enable_classes(false);

If classes are enabled when parse_code() is called, then the resultant source will use CSS classes in the output, otherwise it will in-line the styles. The advantages of using classes are great - the reduction in source will be very noticeable, and what’s more you can use one stylesheet for several different highlights on the same page. In fact, you can even use an external stylesheet and link to that, saving even more time and source (because stylesheets are cached by browsers).

👉 Note:

There have been problems with inline styles and the Symbol Highlighting added in 1.0.7.21. If you can you should therefore turn CSS classes ON to avoid those issues. Although latest reworks in 1.0.8 should fix most of those issues.

❗ Caution:

This should be the very first method you call after creating a new GeSHi object! That way, various other methods can act upon your choice to use classes correctly. In theory, you could call this method just before parsing the code, but this may result in unexpected behaviour.

Setting the CSS class and ID

You can set an overall CSS class and id for the code. This is a good feature that allows you to use the same stylesheet for many different snippets of code. You call set_overall_class() and set_overall_id to accomplish this:

$geshi->set_overall_class('mycode');
$geshi->set_overall_id('dk48ck');

The default classname is the name of the language being used. This means you can use just the one stylesheet for all sources that use the same language, and incidentally means that you probably won’t have to call these methods too often.

CSS IDs are supposed to be unique, and you should use them as such. Basically, you can specify an ID for your code and then use that ID to highlight that code in a unique way. You’d do this for a block of code that you expressly wanted to be highlighted in a different way (see the section below on gettting the stylesheet for your code for an example).

👉 Note:

As of GeSHi 1.0.8 the class name will always include the language name used for highlighting.

Getting the stylesheet for your code

The other half of using CSS classes is getting the stylesheet for use with the classes. GeSHi makes it very easy to get a stylesheet for your code, with one easy method call:

$geshi->enable_classes();
 
// Here we have code that will spit out a header for
// a stylesheet. For example:
 
echo '<html>
<head><title>Code</title>
<style type="text/css">
<!--';
// Echo out the stylesheet for this code block
echo $geshi->get_stylesheet();
 
// And continue echoing the page
 
echo '-->
</style></head>
<body>';

The get_stylesheet() method gets the stylesheet for your code in one easy call. All you need to do is output it in the correct place. As you can also see, you don’t even have to enable class usage to get the stylesheet nessecary either - however not enabling classes but using the stylesheet may result in problems later.

By default, get_stylesheet() tries to echo the least amount of code possible. Although currently it doesn’t check to see if a certain lexic is even in the source, you can expect this feature in the future. At least for the present however, if you explicitly disable the highlighting of a certain lexic, or disable line numbers, the related CSS will not be outputted. This may be a bad thing for you perhaps you’re going to use the stylesheet for many blocks of code, some with line numbers, others with some lexic enabled where this source has it disabled. Or perhaps you’re building an external stylesheet and want all lexics included. So to get around this problem, you do this:

$geshi->get_stylesheet(false);

This turns economy mode off, and all of the stylesheet will be outputted regardless.

Now lets say you have several snippets of code, using the same language. In most of them you don’t mind if they’re highlighted the same way (in fact, that’s exactly what you want) but in one of them you’d like the source to be highlighted differently. Here’s how you can do that:

// assume path is the default "geshi/" relative to the current directory
 
$geshi1 = new GeSHi($source1, $lang);
$geshi2 = new GeSHi($source2, $lang);
 
$geshi3 = new GeSHi($source3, $lang);
 
// Turn classes on for all sources
$geshi1->enable_classes();
 
$geshi2->enable_classes();
$geshi3->enable_classes();
 
// Make $geshi3 unique
$geshi3->set_overall_id('different');
 
 
//
// Methods are called on $geshi3 to change styles...
//
 
echo '<html>
<head><title>Code</title>
 
<style type="text/css">
<!--
';
 
// Get the nessecary stylesheets
echo $geshi1->get_stylesheet();
 
echo $geshi3->get_stylesheet();
 
echo '-->
</style></head>
<body>';
 
 
echo 'Code snippet 1:';
echo $geshi1->parse_code();
echo 'Code snippet 2 (same highlighting as 1):';
 
echo $geshi2->parse_code();
echo 'Code snippet 3 (DIFFERENT highlighting):';
echo $geshi3->parse_code();
 
 
echo '</body></html>';

Before version 1.0.2, you needed to set the class of the code you wanted to be unique to the empty string. This limitation has been removed in version 1.0.2 - if you set the ID of a block of code, all styling will be done based on that ID alone.

Using an External Stylesheet

An external stylesheet can reduce even more the amount of code needed to highlight some source. However there are some drawbacks with this. To use an external stylesheet, it’s up to you to link it in to your document, normally with the following HTML:

<html>
<head>
<link rel="stylesheet" type="text/css" href="url_to_stylesheet.css" />

In your external stylesheet you put CSS declarations for your code. Then just make sure you’re using the correct class (use set_overall_class() to ensure this) and this should work fine.

This method is great if you don’t mind the source always being highlighted the same (in particular, if you’re making a plugin for a forum/wiki/other system, using an external stylesheet is a good idea!). It saves a small amount of code and your bandwidth, and it’s relatively easy to just change the stylesheet should you need to. However, using this will render the methods that change the styles of the code useless, because of course the stylesheet is no longer being dynamically generated. You can still disable highlighting of certain lexics dynamically, however.

👉 Note:

As of version 1.0.2, GeSHi comes with a src/contrib/ directory, which in it contains a “wizard” script for creating a stylesheet. Although this script is by no means a complete solution, it will create the necessary rules for the basic lexics - comments, strings for example. Things not included in the wizard include regular expressions for any language that uses them (PHP and XML are two languages that use them), and keyword-link styles. However, this script should take some of the tedium out of the job of making an external stylesheet. Expect a much better version of this script in version 1.2!