sfGeshiPlugin - 1.0.2

sfGeshiPlugin provides easy use of the Generic Syntax Highlighter (GeSHi)

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

sfGeshiPlugin

Provides very easy use of Generic Syntac Highlighter (GeSHi) in symfony projects. Current release of the plugin is based on version 1.0.8.5 of GeSHI.

Installation

Either command line:

$ ./symfony plugin:install sfGeshiPlugin

or checkouting repository:

$ svn co http://svn.symfony-project.com/plugins/sfGeshiPlugin/trunk plugins/sfGeshiPlugin

from the project root directory.

Usage

Original GeSHi library usage

Although the plugin provides a nice and easy API, you may still want to use original GeSHi library class:

$code_orig = "<?php echo \"hello GeSHi\"; ?>";
$geshi = new GeSHi($code_orig, 'php');
$code_high = $geshi->parse_code();

Basic plugin usage

The plugin provides you a nice and easy-to-use sfGeshi class with static methods. Basic usage of sfGeshiPlugin is based on the sfGeshi::parse_single method. It's obvious - store all the code you want to highlight in one variable and pass it as the first parameter to the parse_single method. The second parameter is the language name. See the example below:

$code_orig = "<?php echo \"hello GeSHi\"; ?>";
$this->code = sfGeshi::parse_single($code_orig, 'php');

That was the action code. The template code is as simple as the previous one:

<?php echo $code ?>

As you can see, there's nothing difficult.

Advanced plugin usage

You may encounter a problem, when you have a big amount of text mixed with code (e. g. more than 10k letter string). If you use standard GeSHi highlighting, it will try to highlight also the normal text, which will be surrounded with the <pre>...</pre> tags (so that all your layout will break). And this is where the plugin comes to help!

The usage of code-and-text mixed block is... still simple:

$code_orig = "Hello, mom!";
$code_orig .= "[php]<?php echo \"hello GeSHi\"; ?>[/]";
$code_orig .= "Wait, mom!";
$code_orig .= "[cpp] class Symfony { public: Symfony() { } }; [/]";
$code_orig .= "Bye, mom!";
$code_high = sfGeshi::parse_mixed($code_orig);

You might have noticed two very important things:

  • You don't have to specify the name of the language while calling sfGeshi::parse_mixed method - as you may want to embed codes of many different programming languages at one time.

  • But you have to specify the name of the language directly inside the mixed block, using [language_name]...[/] meta-plugin-tags.

The method works like this: the mixed text is treated as normal text until [language_name] opening tag is found. Then a closing tag shall occur. Such a piece of mixed block (beginning from the opening tag and finishing at the closing tag) is replaced with its GeSHi syntax highlighting output.

Notes on advanced plugin usage

The plugin is most useful for IT bloggers and tutorial websites. As sfGeshi::parse_mixed needs some time to highlight big amounts of text, it's strongly advised to store highlighted version of mixed text in a separate column in the blog article table. This is because highlighting would be performed only once, the output would be stored in database and the result page would be rendered a lot faster (because GeSHi was already used).

sfGeshiExample

The plugin is provided with an example module to test if everything works fine. Right after installation, go to your application config directory and add sfGeshiExample module to enabled modules section in settings.yml file. Next step is to edit config/routing.yml file of the plugin - you shall uncomment all lines. Then clear the cache:

$ ./symfony cc

and everything is ready to run:

http://local.site/geshi

in your browser. You shall see a demonstration of highlighting PHP code of the actions.class.php file. The first part tests parse_single method, while the second one tests parse_mixed method.

Custom language files

Of course, there are lots of languages (probably not very popular ones) which are not supported by GeSHi. You may create your own language file (read chapter IV of GeSHi documentation for more details). If you do so, let GeSHi authors know!

The plugin gives you a possibility to add new syntax highlighting language files and overriding existing ones. For this purpose, you shall create new files in sfGeshiPlugin/lib/custom directory.

How parse_single works

The parse_single method (which is root of all plugin syntax highlighting) tries to find custom language file first (in the sfGeshiPlugin/lib/custom directory). If it exists, it's used. The original GeSHi file is used only if there is no overriding file in the custom directory.

Adding new/overriding language files

All new files should appear in the sfGeshiPlugin/lib/custom directory. If you want to override a language file, simply copy it from sfGeshiPlugin/lub/geshi/geshi directory.

Highlighting layout

This is probably the most interesting feature. And that's how to configure it: each language file contains $language_data array which contains subarray with STYLES key. This is the part you shall edit.

Language file overriding example

An example of syntax highlighting overriding is provided: sfGeshiPlugin/lib/custom/php.php file. You can edit STYLES key subarray in this file and check the sfGeshiExample action to see the changes. For example, in origial PHP GeSHi highlighting comments shall appear green, whereas the overriding version makes it purple. Edit the custom file or delete it to see the changes.

Documentation

See the GeSHi documentation.

GeSHi support for YAML

GeSHi is still missing support for our precious YAML language. If you want GeSHi to support .yml files as soon as possible, join the quest form geshi-yml-support here :)!