MarkTaff.com

  • Increase font size
  • Default font size
  • Decrease font size
Home Software Joomla! GeSHi Extreme

GeSHi Extreme

E-mail Print PDF

In porting my website to Joomla!, I was rather disappointed in the state of Joomla!'s syntax highlighting.  I discovered the Geshi Plus plug-in, which allowed for use of an alternate tag style that makes it possible to use the syntax highlighter with a WYSIWYG editor.  While that was helpful, it didn't provide nearly enough power for my purposes.  So, having an itch, I scratched it. ;-)

Introducing GeSHi Extreme

GeSHi Extreme maintains the alternate tag style introduced by GeSHi Plus, and adds several useful features:

  • Render code directly from a source file
  • Specify a range of lines from a source file to be rendered
  • Render all the code between two arbitrary markers in a source file
  • Permits using GeSHi's fancy line numbering option
  • Permits specifying extra CSS styles to be applied to both normal and fancy lines
  • Permits starting line numbering from any positive integer*
  • Permits (x)html line breaks within the opening GeSHi tag to make life with WYSIWYG editors less irritating
  • Easily specify global default values for basic parameters from the Plugin Manager
  • Easily write example commands by doubling the initial geshi brace or angle bracket [{{ | <<]

*N.B. Using this feature produces code that is not XHTML Strict compliant, so don't use it if strict compliance is important to you.

Highlighter Languages

A stock installation of Joomla! ships with syntax highlighting specification files for only a handful of the most common scripting and formatting languages.  The GeSHi Extreme plug in administration interface has an informative drop-down list that contains all of the syntax highlighter languages currently available in your Joomla! installation.

You may download all of the available language files from the GeSHi website.  As of this writing, GeSHi 1.0.8.1 is the latest stable release.  To add the language files to your Joomla! installation, downloaded and unzip the *.[tar.gz|tar.bz2|zip] file.  Copy the desired language files from the /geshi/geshi folder to the /libraries/geshi/geshi folder in your Joomla! installation.

I don't know if Joomla! has a built-in mechanism for updating it's libraries, but getting these additional languages installed programmatically is on my @todo list, albeit an incredibly low priority.

Examples

A basic GeSHi use:

{geshi xml:lang="javascript"}// Say hello!
var message = "Hello World";
alert(message);{/geshi}

Produces the following output:

  1. // Say hello!
  2. var message = "Hello World";
  3. alert(message);

A more complex example, grabbing a class definition from this theme's template.css file:

{geshi xml:lang="css" lines="true" begintag="/* Outermost" endtag="}" includetag="true" \
src="/home/mark_taff/marktaff.com/templates/taff_purity/css/template.css" }{/geshi}

Produces the following output:

  1. /* Outermost container holding a captioned image, generated by caption.js */
  2. .captioned_image_container
  3. {
  4. /* How much space between container & surrounding content? */
  5. margin: 8px 8px 2px 8px;
  6. /* How much space on between container & the contained content? */
  7. padding: 0px;
  8. display: block;
  9. text-align: left;
  10. width: auto;
  11. border: 1px solid #ccc;
  12. }

Another complex example, grabbing some lines from my XHTML standards-compliant version of Joomla!'s caption.js image auto-captioning program:

{geshi xml:lang="javascript" lines="fancy" beginline="48" endline="70" includetag="true" initial="48" \
src="/home/mark_taff/marktaff.com/media/system/js/caption.js" }{/geshi}

Produces the following output:

  1. if (align=="") {
  2. align="none";
  3. }
  4.  
  5. text.appendChild(caption);
  6. text.className = this.selector.replace('.', '_');
  7.  
  8. element.parentNode.insertBefore(container, element);
  9. container.appendChild(element);
  10. if ( element.title != "" ) {
  11. container.appendChild(text);
  12. }
  13. container.className = this.selector.replace('.', '_');
  14. container.className = container.className + " " + align;
  15. container.setAttribute("style","float:"+align);
  16.  
  17. container.style.width = width + "px";
  18.  
  19. }
  20. });
  21.  
  22. document.caption = null;
  23. window.addEvent('load', function() {
  24.  

This example will slurp in an entire enternal file:

{geshi xml:lang="cpp-qt" src="/home/mark_taff/media.marktaff.com/portfolio/code/kgamesvgdocument.cpp" }{/geshi}

Though, in the interests of brevity, I'm not going to actually display this 700-line C++ file I wrote for KDE here.

Attributes

lang="<language>"

Used to specify which language highlighting file should be used.  <language> may be any installed language name, as listed in the Language Name parameter field in the Plugin Manager.

This attribute is identical to GeSHi Plus.

lines="[false|true|fancy]"

Used to specify which type of line numbering should be used. false means do not number the lines. true means use normal line numbering. fancy means use fancy line numbering.

This attribute is identical to GeSHi Plus.

src="/<path>"

Used to specify the external file that should be included. <path> the absolute path to the file.

This attribute is unique to GeSHi Extreme.

beginline="<integer>"

Used to specify the first line of an external file that should be included. <integer> is any positive integer smaller than the integer for the endline attribute.

This attribute is unique to GeSHi Extreme.

endline="<integer>"

Used to specify the last line of an external file that should be included. <integer> is any positive integer larger than the integer for the beginline attribute and smaller than total number of lines in the file.

This attribute is unique to GeSHi Extreme.

begintag="<string>"

Used to specify an arbitrary string to begin grabbing text from an external file. The match is non-greedy, and it will only return the first match.

This attribute is unique to GeSHi Extreme.

endtag="<string>"

Used to specify an arbitrary string to stop grabbing text from an external file. The match is non-greedy, and it will only return the first match.

This attribute is unique to GeSHi Extreme.

includetag="[true|false]"

When matching text between two arbitrary strings, should the arbitrary strings themselves be consider part of the match? true means they should, while false means the shouldn't.

This attribute is unique to GeSHi Extreme.

initial="<integer>"

Used to specify the initial value for the line numbering.  <integer> is any positive integer.  Note that GeSHi implements this in a manner that is not XHTML Strict compliant (due to IE's lack of support). So do not use this method is XHTML Strict compliance it a requirement.

This attribute is identical to GeSHi Plus.

interval="<integer>"

Used to specify n for every nth line of code that is rendered in the fancy style.  The default value is every 5th line. <integer> is any positive ineteger.

This attribute is identical to GeSHi Plus.

normalstyle="<string>"

Used to specify additional CSS style properties to be merged with default properties for every line rendered in the normal style. When setting the global default for this property in the Plugin Manager, do not use any pound signs (#) for any reason, due to a limitation in Joomla!  GeSHi Extreme will automatically add the missing pound sign to CSS color specs as required, lest they be naked. ;-)

This attribute is unique to GeSHi Extreme.  GeSHi Plus does however allow you to set the background color for normal and fancy lines, using the foreground and background properties.

fancystyle="<string>"

Used to specify additional CSS style properties to be merged with default properties for every line rendered in the fancy style. When setting the global default for this property in the Plugin Manager, do not use any pound signs (#) for any reason, due to a limitation in Joomla!  GeSHi Extreme will automatically add the missing pound sign to CSS color specs as required, lest they be naked. ;-)

This attribute is unique to GeSHi Extreme.  GeSHi Plus does however allow you to set the background color for normal and fancy lines, using the foreground and background properties.

Download

Install & Upgrade

  1. Disable the existing Joomla 1.5 Geshi plugin using the Joomla 1.5 Plugin manager.
  2. Disable the GeSHi Plus plugin using the Joomla 1.5 Plugin manager.
  3. If upgrading, remove the existing GeSHi Extreme plgin using the Joomla 1.5 Plugin manager.
  4. Install the GeSHi Extreme plugin using the Joomla Extensions install utility.
  5. Enable the GeSHi Extreme plugin using the Joomla 1.5 Plugin manager.
  6. Set the global default parameter values as desired using the Joomla Extension Plugin Manager.

See Also

Last Updated ( Wednesday, 28 January 2009 22:05 )  

Quotes, Aphorisms & Epigrams

Computers do not solve problems, they execute solutions. Laurent Gassar