Cum instalăm şi utilizăm SyntaxHighlighter 2.0 pe Blogger

Deoarece majoritatea articolelor publicate pe acest blog vor avea legătură cu IT(Information Technology), şi cum IT-ul fără de cod nu poate exista, am hotărît să-mi instalez pe blog un modul care va evidenţia şi colora codul sursă publicat în articole.

După o căutare pe Google am dat de SyntaxHighlighter, o bibliotecă scrisă în JavaScript menită să evidenţieze şi să coloreze codul sursă. De notat că SyntaxHighlighter începînd cu 1 martie 2009 este licenţiat sub licenţa LGPL3, ceea ce ne permite să-l utilizăm liber şi gratis.

Curios este faptul că pînă la 1 martie 2009 SyntaxHighlighter era licenţiat sub licenţa LGPL2.1 dar cu o excepţie adăugată de autorul bibliotecii, prin care acesta cerea utilizatorilor care folosesc această bibliotecă pe paginile lor web sau în produsele acestora să doneze în mod obligatoriu cît îi lasă inima pentru susţinerea şi dezvoltarea de mai departe a acestui proiect. Acest lucru este complet incompatibil cu licenţa LGPL, fapt care probabil nu a fost observat de către autor. Îmbucurător este faptul că autorul s-a auto-sesizat şi acum donaţiile nu mai sunt obligatorii ci doar binevenite. Aşa că dacă utilizaţi şi vă place acest produs, susţine-ţi autorii acestei minunate biblioteci donînd cît consideraţi necesar.

În acest articol voi descrie cum de instalat şi mai apoi folosit SyntaxHighlighter 2.0 pe Blogger. De menţionat faptul ca versiunile precedente mai sunt găzduite pe Google Code cu toate că în prezent acesta nu mai este un proiect activ.

1. De ce avem nevoie de SyntaxHighlighter.

Pentru a demonstra utilitatea evidenţierii şi colorării codului sursă este suficient să aducem următorul exemplu.

Aşa arată fragmentul de cod fără a utiliza SyntaxHighlighter. Fragmentul de cod este inclus între <pre>...</pre>

public class HelloWorld {
public static void main(String[] args) {
 System.out.println("Hello World!");

 System.out.print("Echo: ");
 for(int i = 0; i < 5; i++) {
     System.out.print("Hello! ");
 }
}
}

Astfel arată fragmentul de cod cu utilizarea SyntaxHighlighter. Fragmentul de cod este inclus între <pre class="brush: java; highlight:[6, 7, 8]">...</pre> astfel specificînd limbajul şi numerele rîndurilor pe care dorim să le selectăm.

public class HelloWorld {
public static void main(String[] args) {
 System.out.println("Hello World!");

 System.out.print("Echo: ");
 for(int i = 0; i < 5; i++) {
     System.out.print("Hello! ");
 }
}
}

Este simplu şi arată mult mai bine nu-i aşa? Pe lîngă evidenţierea şi colorarea cuvintelor cheie, numerotării rîndurilor, mai există şi posibilitatea selectării individuale a rîndurilor pentru a atrage atenţia cititorului sau pentru a face referire la ele din text. [Click mai jos pentru a citi articolul în întregime]

2. Cum instalăm SyntaxHighlighter.

Pentru început este nevoie de a descărca SyntaxHighlighter de aici şi de a-l încărca pe blog-ul dumneavoastră. Dar aşa cum Blogger nu oferă posibilitatea încărcării fişierelor(cu excepţia pozelor şi filmuleţelor) va trebui să-l încărcăm pe un site public unde oricine are acces.

O altă opţiune este folosirea versiunii găzduite pe site-ul SyntaxHighlighter. Mai multe detalii aici. Dacă alegeţi această opţiune atunci puteţi trece direct la pasul următor (nr. 3), dar totuşi ar fi bine sa urmăriţi comentariile şi observaţiile ce ţin de performanţă care se vor aduce în continuare.

Pentru a găzdui SyntaxHighlighter eu am ales Google Sites, unde există posibilitatea de a crea un site gratis în doar cîteva clipe. În plus există posibilitatea de a păstra aici fişiere şi de a face referire la ele de pe blog. Spaţiul oferit de Google Sites este de 100MB.

Biblioteca SyntaxHighlighter constă din două mape scripts şi styles. Anume conţinutul lor şi trebuie încărcat. Mapa scripts conţine următoarele fişiere:

• clipboard.swf - este un fişier Flash folosit de către SyntaxHighlighter pentru a copia textul în clipboard atunci cînd utilizatorul apasă butonul Copy to clipboard de pe toolbar. Dacă doriţi această funcţionalitate atunci acest fişier trebuie încarcat, dacă nu, atunci ignoraţi-l.
• shCore.js - este nucleul bibliotecii. Trebuie încărcat obligatoriu.
• shLegacy.js - este un proxy pentru fragmentele de cod publicate folosind versiunile mai vechi ale SyntaxHighlighter. Mai multe detalii aici. Dacă nu aţi mai folosit SyntaxHighlighter pînă acum puteţi ignora acest fişier.
• shBrush*.js - sunt fişiere pensule pentru fiecare limbaj susţinut de bibliotecă. Acestea din urmă conţin informaţia despre cuvintele cheie, structura şi comentariile limbajelor respective. Este nevoie de încărcat doar fişierele pentru limbajele pe care le veţi folosi pe blog-ul dvs.

Mapa styles conţine următoarele fişiere:

• shCore.css - este fişierul CSS de bază. Trebuie încărcat obligatoriu.
• shTheme*.css - SyntaxHighlighter 2.0 a întrodus noţiunea de temă sau aspect. Aceasta permite schimbarea aspectului şi palitrei de culori utilizate de SyntaxHighlighter. Mai multă informaţie aici. Este nevoie de încărcat doar fişierul cu tema pe care doriţi să o utilizaţi pe blog-ul dvs.
• *.png - imaginile folosite de SyntaxHighlighter. Trebuie încărcate obligatoriu.

NOTĂ DE PERFORMANŢĂ: După ce vor fi încărcate pe Google Sites, şablonul blog-ului dvs va trebui modificat pentru a include toate aceste fişiere. Ca urmare, browserul dvs va trebui să descarce toate aceste fişiere, ceea ce înseamnă în jur de 20 de conexiuni adăugătoare. Cu toate că aceste fişiere sunt foarte mici, fiecare conexiune nouă este costisitoare. Sfatul meu este să combinaţi toate fişierele shBrush*.js în unul singur, şi să-l numiţi shBrushAll.js, astfel veţi reduce considerabil numărul conexiunilor necesare pe care browserul dvs va trebui sa le facă şi veţi îmbunătăţi performanţa.

Acelaşi lucru este şi cu fişierele CSS. Alegeţi tema pe care o veţi folosi pe blog-ul dvs şi combinaţi acest fişier cu shCore.css. De exemplu daca utilizaţi shThemeDefault.css atunci fişierul primit de la combinarea shCore.css cu shThemeDefault.css poate fi numit shCoreThemeDefault.css.

În această privinţă am făcut chiar un test, în care am măsurat timpul de încărcare al unei pagini pe Blogger care includea fiecare shBrush*.js în parte şi al altei pagini care includea doar shBrushAll.js. Iată rezultatele: 20 de secunde contra a 4 secunde. O îmbunătăţire de 5 ori. Timpul de încărcare a fost măsurat cu ajutorul serviciului Stopwatch. După părerea mea 20 de secunde pentru o pagină care practic nu avea nimic pe ea e prea mult.

Aşa că gîndiţi-vă bine înainte de a folosi versiunea găzduită pe site-ul SyntaxHighlighter, deoarece în acest caz veţi fi nevoit să includeţi fiecare fişier în parte, ceea ce înseamnă un timp mai mare de încărcare a paginilor dvs.

Pentru a instala SyntaxHighlighter pe Google Sites veţi avea nevoie să parcurgeţi următorii paşi:

a) Înregistraţi-vă şi creaţi un site nou. Fiţi siguri ca aţi ales opţiunea de a-l face public, adică oricine va putea accesa acest site.

b) Creaţi o pagină web nouă accesînd butonul din imagine.

c) Alegeţi setările astfel cum este arătat în imaginea de mai jos.

d) Creaţi o altă pagină web şi alegeţi setările astfel cum este arătat în următoarea imagine. Fiţi atenţi la alegerea locaţiei. Pagina scripts trebuie sa fie inclusă în syntaxhighlighter. Pentru a specifica locaţia folosiţi link-ul Alege o altă locaţie (Choose a different location)

e) Unul cîte unul, încărcaţi toate fişierele din mapa scripts pe noua pagină web scripts, folosind butonul din imagine. (Dacă aţi hotărît combinarea tuturor fişierelor shBrush*.js în unul singur shBrushAll.js atunci încărcaţi-l doar pe cel din urmă. În orice caz nu uitaţi să încărcaţi şi shCore.js)

ATENŢIE: Google Sites nu permite încărcarea fişierelor JavaScript (extensia .js), din acest motiv înainte de a încarca fişierele, schimbaţi-le extensia în .txt

f) Repetaţi paşii d) şi e) pentru mapa styles. Folosiţi aceleaşi setări schimbînd doar numele cu styles.

g) În final trebuie sa aveţi următoare ierarhie de pagini. (În această imagine este arătată doar ierarhia paginilor, fără fişierele pe care acestea le conţin)

3. Cum configurăm SyntaxHighlighter.

După ce aţi încarcat toate fişierele, urmează modificarea şablonului blog-ului dvs cu scopul de a include toate aceste fişiere. Pentru aceasta mergeţi la Setări -> Aspect -> Editaţi HTML (Settings -> Layout -> Edit HTML) şi imediat după tag-ul <head> adăugaţi fişierul CSS de bază şi cel ce ţine de tema aleasă de dvs, aşa cum este arătat mai jos (în exemplul de mai jos am folosit tema shThemeDefault.css, dar dvs puteţi folosi oricare alta):

<head>
<link type="text/css" rel="stylesheet" href="http://sites.google.com/site/numeledvs/syntaxhighlighter/styles/shCore.css" />
<link type="text/css" rel="stylesheet" href="http://sites.google.com/site/numeledvs/syntaxhighlighter/styles/shThemeDefault.css" />
...

Apoi trebuie adăugat shCore.js urmat de toate fişierele pensule pe care le veţi folosi pe blog-ul dvs (în exemplul de mai jos extensia fişierelor este .js pentru a nu crea confuzii în cazul în care cineva a hotărît să găzduiască SyntaxHighlighter pe un site altfel decît Google Sites, dvs însă trebuie să o schimbaţi în .txt în cazul în care aţi încărcat fişierele pe Google Sites):

<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shCore.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushJScript.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushJava.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushSql.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushXml.js"></script>

Şi în sfîrşit trebuie invocată funcţia SyntaxHighlighter.all() care practic şi face tot job-ul:

<script type="text/javascript">
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.all();
</script>

Ţin să atenţionez asupra importanţei liniei de cod subliniate. Aceasta din urmă trebuie adăugată atunci cînd folosim SyntaxHighlighter pe Blogger. Aceasta se datorează faptului ca Blogger foloseşte <br> pentru trecerea la rînd nou, şi fără setarea acestui parametru toate <br> vor fi afişate în fragmentele de cod. Iată un exemplu. Aşa va arăta fragmentul de cod cu specificarea bloggerMode = true;

Iar aşa fără specificare:

În final totul împreună trebuie să arate aşa:

<head>
<link type="text/css" rel="stylesheet" href="http://sites.google.com/site/numeledvs/syntaxhighlighter/styles/shCore.css" />
<link type="text/css" rel="stylesheet" href="http://sites.google.com/site/numeledvs/syntaxhighlighter/styles/shThemeDefault.css" />

<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shCore.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushJScript.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushJava.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushSql.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushXml.js"></script>

<script type="text/javascript">
 SyntaxHighlighter.config.bloggerMode = true;
 SyntaxHighlighter.all();
</script>
...

Sau dacă mi-aţi urmat sfatul şi aţi combinat fişierele împreună, atunci rezultatul final va arăta aşa:

<head>
<link type="text/css" rel="stylesheet" href="http://sites.google.com/site/numeledvs/syntaxhighlighter/styles/shCoreThemeDefault.css" />

<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shCore.js"></script>
<script type="text/javascript" src="http://sites.google.com/site/numeledvs/syntaxhighlighter/scripts/shBrushAll.js"></script>

<script type="text/javascript">
 SyntaxHighlighter.config.bloggerMode = true;
 SyntaxHighlighter.all();
</script>
...

ATENŢIE: Nu uitaţi să schimbaţi numeledvs în toate adresele cu numele pe care l-aţi dat site-ului în momentul în care l-aţi creat.

4. Cum utilizăm SyntaxHighlighter.

Simplu de tot. SyntaxHighlighter caută în pagină toate tag-urile <pre> care conţin atributul class formatat într-un mod special. Acest format este acelaşi ca şi al atributului style în HTML. Unicul parametru obligator este brush care trebuie setat cu unul dintre sinonimele fişierelor pensulă incluse de dvs. Acesta din urmă va specifica limbajul fragmentului de cod utilizat.

Iată un caz tipic de utilizare:

<pre class="brush: java">
System.out.println("Hello World!");
</pre>

IMPORTANT: Fiţi atenţi la fragmentele de cod ce conţin caracterele < şi > Acestea trebuie înlocuite cu &lt; şi respectiv &gt;

De asemenea pe lîngă parametrul obligatoriu brush, mai putem specifica şi alţi parametri. Lista întreagă cu toţi parametri şi descrierea acestora o găsiţi aici.

Iată un exemplu mai sofisticat:

<pre class="brush: java; ruler: true; toolbar: false; first-line: 10; highlight: [11, 12]; font-size: 125%">
System.out.println("Hello World 1!");
System.out.println("Hello World 2!");
System.out.println("Hello World 3!");
</pre>

Parametrii adiţionali care au fost specificaţi au dus la următoarele:

• Vizualizarea riglei.
• Ascunderea toolbar-ului.
• Numerotarea rîndurilor începe de la 10.
• Liniile 11 şi 12 sunt selectate.
• Specificarea mărimii font-ului de 125%.

Un lucru important este faptul că există posibilitatea redefinirii valorilor implicite a acestor parametri. De exemplu, dacă doriţi să ascundeţi toolbar-ul în toate fragmentele din toate articolele dvs, atunci puteţi adăuga următoarea linie de cod selectată, înaintea invocării SyntaxHighlighter.all(); aşa cum este arătat mai jos:

<script type="text/javascript">
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
</script>

Aceasta va seta valoarea implicită a parametrului toolbar. Ca rezultat toate fragmentele de cod care nu au specificat explicit valoarea acestui parametru, vor utiliza aceasta valoare, ceea ce va duce la ascunderea toolbar-ului.

După cum vedeţi SyntaxHighlighter este foarte simplu şi uşor în utilizare şi în acelaşi timp oferă o gamă largă de posibilităţi.

Utilizare plăcută :-)