Grails - SyntaxHighlighter Plugin

News

19 May 2008, 23:29: I've just released the plugin! You can install it by typing: grails install-plugin syntax-highlighter

20 May 2008: I've added better Groovy support

Description

This plugin adds a Syntax Highlighter for displaying code samples in GSP pages. The plugin consists of two taglibs and a Javascript library. The Javascript library used is written by Alex Gorbatchev, and can be found here.

The current version of the syntax-highlighter plugin is 0.1.2, which was released at 21 September 2008.

History

Version	Date	Remarks
0.1.2	21 September 2008	Bugfix release. Thanks Chris!
0.1.1	15 May 2008	Added Groovy support
0.1.0	1 May 2008	Inital version

Supported languages

This table defines the list of supported languages.

Language name	Language code
C++	cpp, c, c++
C#	c#, c-sharp, csharp
CSS	css
Delphi	delphi, pascal
Groovy	groovy
Java	java
Java Script	js, jscript, javascript
PHP	php
Python	py, python
Ruby	rb, ruby, rails, ror
Sql	sql
VB	vb, vb.net
XML/HTML	xml, html, xhtml, xslt

The 'language code' is used in the plugin and maps to the 'language(s)' attribute.

Installation

You can install the plugin by typing:

grails install-plugin syntax-highlighter

The plugin will be downloaded and will create a new 'syntaxhighlighter' directory in <projectroot>/web-app/js and in <projectroot>/web-inf/css, containing all the libraries for the Syntax Highlighter.

Usage

You can invoke the taglib by putting the <syntax:resource> tag in the <head> element of the GSP page, which is used to load Javscript and CSS libraries. The <syntax:format> tag can be used to format the code.

To use the Syntax Highlighter, include the following markup in your GSP.

<html>
<head>
  <!-- Resources like JavaScript libraries and CSS -->
  <syntax:resources name="code" languages="['Java', 'Xml']" />
</head>
<body>
  <syntax:format name="code" language="java">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
  </syntax:format></body>
</html>

<syntax:resource>

Used to import the necessary Javascript and CSS. The <syntax:resource> tag supports the following attributes:

Name	Type	Values	Description
name	required	true or false]	Name of the block to highlight. Use the same name in all code blocks.
languages	required	true or false	Specifies the list of languages to use. Javascript libraries will be loaded accordingly.
gutter	optional	true or false	Shows the gutter containing the line numbers.
controls	optional	true or false	Shows the controls (view plain, print) on the top of the code.
collapse	optional	true or false	Collapses the code which can be expanded by a mouseclick.
firstLine	optional	int	Allows to specify the first line where line numbering starts. This is usefull if you want to illustrate where the code block is located relative to the file.
showColumns	optional	true or false	Will show horizontal row columns in the first line.

Any values passed in the resource tag will override corresponding configuration option. This might work a bit counterintuitive (it does for me), so you are warned.

Example

This enables Java and c-sharp syntax highlighting, and will hide the controls for all code blocks. All linenumbers will start at line 20.

<syntax:resources languages="['Java', 'c-sharp']" controls="false" firstLine="20" />

<syntax:format>

Used to highlight the code. The <syntax:format> tag supports the following attributes:

Name	Type	Values	Description
name	required	true or false	Name of the code block. Used by the <syntax:resource> tag to find this code block.
language	required	true or false	Specifies the name of the language to use.
gutter	optional	true or false	Shows the gutter containing the line numbers.
controls	optional	true or false	Shows the controls (view plain, print) on the top of the code.
collapse	optional	true or false	Collapses the code which can be expanded by a mouseclick.
firstLine	optional	int	Allows to specify the first line where line numbering starts. This is usefull if you want to illustrate where the code block is located relative to the file.
showColumns	optional	true or false	Will show horizontal row columns in the first line.
escapeXml	optional	true or false (defaults to true)	When using unescaped XML, like <person><name>Erik Pragt</name></person>, the escapeXml attribute will HTML-encode the code block (e.g. replace the < and > by < and >). This prevents breaking the Javascript formatter.

Example

This syntax highlights the Java code. The linecount will start at 3, and no controls will be shown.

<syntax:format name="code" language="java" firstLine="3" controls="false">
public void thisIsSomeTestCode() {
  System.out.println("test if it works");
}                
</syntax:format>

Some examples

<syntax:format name="code" language="java">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format><syntax:format name="code" language="java" showColumns="true">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java" showColumns="false">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java" collapse="false" showColumns="true">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java" collapse="true" showColumns="true">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java" firstLine="3" gutter="true">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java" gutter="false">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java" firstLine="3">
public void thisIsSomeTestCode() {
   System.out.println("test if it works");
}                
</syntax:format>
<syntax:format name="code" language="java">
String erik = "&lt;person id="id">"
String erik = "&lt;person id="id">"
String erik = "&lt;person id="id">"
</syntax:format>
<syntax:format name="code" language="java" escapeXml="true">
/** test */
String erik = "<person version="1">"
String erik = "<person version="2">"
String erik = "<person version="3">"
/** end of test */
</syntax:format>

Output