Monday, April 06, 2009

Как вставить код программы в HTML сайт

В отличие от вставки аудио (MP3) или видео (WAV, MPG) вставить код программы немного сложнее, примерно также как вставить TeX.

UPDATE 12-10-2010: Использование HTML table в Blogger
END OF UPDATE

Ниже есть продолжение.

Примечание: Здесь речь идёт о версии 2.0.296 от 01 марта 2009. Установка и использование предыдущих версий слегка отличается. Миграция на эту версию не совсем straight-forward. Я здесь описываю установку с нуля.

Для начала, давайте разберёмся, что мы хотим. Мы хотим иметь простой способ написать текст программы, чтобы её легко было прочитать. Что мы понимает под удобством чтения? В главных, это идентация, т.е. выравнивание, ну и в качестве бонуса, подсветка. Именно для этих целей и был написан SyntaxHighlighter

Итак, после того, как мы разобрались зачем нам это нужно, давайте разберёмся как мы можем добавить эту функциональность на сайт.

Самый простой способ.

1. Вставьте в ваш сайт, желательно перед тэгом </body> следующий код:


<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>

<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shCore.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJava.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJScript.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushXml.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushProperties.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushBash.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushPlain.js'/>
<script language='javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://alexgorbatchev.com/pub/sh/2.0.296/scripts/scripts/clipboard.swf';
SyntaxHighlighter.all();
</script>



2. В вашем посте в блоге (Blogger, например) или на вашем сайте в любом месте где вы хотите вставить код программы, скажем на Java, вы должны просто заключить этот код в тег <pre&rt и указать атрибут class, например, class="brush: java" для исходного кода на Java.
Так,

<pre class="brush: java">
public class HelloBlogger {
public static void main(String [] args) {
System.out.println("Hello Blogger!!");
}
}
</pre>

будет отражено как


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


Полный список доступных языков доступен тут http://alexgorbatchev.com/wiki/SyntaxHighlighter:Brushes. Можно указать и другие параметры. См. http://alexgorbatchev.com/wiki/SyntaxHighlighter:Сonfiguration

Недостатком этого метода является то, что теперь ваш сайт зависит от некоторого внешнего источника (alexgorbatchev.com). Хотя, это и является сайтом разработчика SyntaxHighlighter, однако если с ним что-то случится, например, он захочет сделать реорганизацию, или просто решит удалить этот скрипт, то ваш сайт или блог вдруг перестанет работать. Пока, он уверяет, что ничего такого делать он не собирается. Этот способ хорош для того чтобы сделать proof of concept, "пощупать" это решение.

Примечание: Ниже вы найдёте тонкую настройку.

Обычный способ.
1. Если у вас нет своего хостинга, то вы должны найти хостинг.

2. Скачайте SyntaxHighlighter

3. Распакуйте файлы в директории scripts and styles.

4. Залейте (с помощью, например, FTP) содержимое этих директории на свой хостинг. Я буду ниже предполагать, что вы не меняли имя директорий и\или их структуру.

5. Вставьте в ваш сайт, желательно перед тэгом </body> следующий код:


<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>


Полный список тем можно найти http://alexgorbatchev.com/wiki/SyntaxHighlighter:Themes. Подробнее см. пукнт 1 в тонкой настройке.

6. Сразу после этого нужно добавить список языков программирования.


<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shCore.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJava.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJScript.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushXml.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushProperties.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushBash.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushPlain.js'/>


Полный список поддерживаемых языков программирования можно найти тут http://alexgorbatchev.com/wiki/SyntaxHighlighter:Brushes. Желательно добавлять сюда только реально используемые вещи, так как каждый такой скрипт увеличивает время загрузки страницы. Подробнее см. пукнт 2 в тонкой настройке.

7. В конце нужно добавить:


<script language='javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://alexgorbatchev.com/pub/sh/2.0.296/scripts/scripts/clipboard.swf';
SyntaxHighlighter.all();
</script>


где bloggerMode = true должно быть уставлено если вы используете blogger. Указание на clipboardSwf опционально. Подробности см. в пункте 3 тонкой настройке.

8. Все вместе это выглядит так:


<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>

<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shCore.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJava.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJScript.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushXml.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushProperties.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushBash.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushPlain.js'/>

<script language='javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://alexgorbatchev.com/pub/sh/2.0.296/scripts/scripts/clipboard.swf';
SyntaxHighlighter.all();
</script>


9. В вашем посте в блоге (Blogger, например) или на вашем сайте в любом месте где вы хотите вставить код программы, скажем на Java, вы должны просто заключить этот код в тег <pre> и указать атрибут class, например, class="brush: java" для исходного кода на Java.
Так,


<pre class="brush: java">
public class HelloBlogger {
public static void main(String [] args) {
System.out.println("Hello Blogger!!");
}
}
</pre>

будет отражено как


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


Полный список доступных языков доступен тут http://alexgorbatchev.com/wiki/SyntaxHighlighter:Brushes. Можно указать и другие параметры. См. http://alexgorbatchev.com/wiki/SyntaxHighlighter:Сonfiguration.

10. Примечание: Из-за ограничений технологии браузеров, в тексте исходной программы не возможно использовать знак < Например, для сравнения, как меньше или меньше равно, или как часть тега XML\HTML. Этот знак должен быть заменён на &lt;

Тонкая настройка.
Общая философия настройки выглядит следующий образом. У SyntaxHighlighter существует множество параметров, изменения значений которых меняет поведение программы. Например, отображать ли номер строки около текста программы или нет. У этих параметров установлены значения по-умолчанию. Далее, можно поменять эти значения по-умолчанию для своего сайта. Далее, можно изменить эти значения для конкретного элемента, который отображает исходный текст программы. Это же можно сделать при определении элемента.

На данном этапе я предполагаю, что первоначальная устновка либо самым простым способом, либо обычным способом завершена. Для удобства я приведу ещё раз код, который был добавлен на сайт:


<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://alexgorbatchev.com/pub/sh/2.0.296/styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>

<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shCore.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJava.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushJScript.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushXml.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushProperties.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushBash.js'/>
<script language='javascript' src='http://alexgorbatchev.com/pub/sh/2.0.296/scripts/shBrushPlain.js'/>

<script language='javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://alexgorbatchev.com/pub/sh/2.0.296/scripts/scripts/clipboard.swf';
SyntaxHighlighter.all();
</script>


где http://alexgorbatchev.com/pub/sh/2.0.296/ это либо линк as is либо должен быть заменён на линк на ваш хостинг.

1. Первые две строчки этого кода устанавливают CSS тему. Первая строчка содержит в себе "ядро" темы, и должна всегда присутствовать. Вторая строчка это собственно тема. В данном случае, выбрана тема по умолчанию. Для того чтобы поменять то, как будет выглядеть ваш исходный код, просто укажите во второй строчке другой CSS.

2. Затем с 4 по 10 строчки "пристёгиваются" языки программирования. Четвёртая строчка содержит "ядро", которое должно присутствовать всегда. Далее, нужно добавить те языки программирования, которыми вы будете пользоватся на своей сайте/блоге. Не следует добавлять "весь список", так как чем больше языков будет поддерживаться, тем медленнее будет загружаться страница (нужно время, чтобы подгрузить каждый JavaScript). Здесь можно найти полный список поддержуемых языков.

3. Далее начинается обящанная настройка параметров по умолчанию. Для начала разберём выделенные строчки 13, 14, 15.

В 13 строчке мы сообщаем SyntaxHighlighter, что он используется на сайте blogger. Если ваш сайт\блог не находится там, вы можете эту строчку вообще удалить. В таком случае, значения по умолчанию будет false, согласно "устновкам произодителя". См. таблицу http://alexgorbatchev.com/wiki/SyntaxHighlighter:Configuration. Вы можете, естественно, и указать значение false явно. Согласно документации если вы используете сайт blogger, вы обязаны установить здесь true.

В 14 строчке мы укзываем на то, где находится файл clipboardSwf. По умалчанию, там установлен null и это значит, что иконка для копирования в буфер показана не будет.

В 15 строчке происходит "магия включения SyntaxHighlighter". В этой строчке мы запускаем JavaScript SyntaxHighlighter, чтобы он делал разментку исходного кода.

4. Давайте коротко разберём более сложный вариант.

<script language='javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://alexgorbatchev.com/pub/sh/2.0.296/scripts/clipboard.swf'
SyntaxHighlighter.config.strings.expandSource = "+ раскрыть исходник"
SyntaxHighlighter.config.strings.viewSource = "посмотреть исходник"
SyntaxHighlighter.config.strings.copyToClipboard = "скопировать в буфер"
SyntaxHighlighter.config.strings.copyToClipboardConfirmation = "Код успешно скопирован в буфер"
SyntaxHighlighter.config.strings.print = "Распечатать"
SyntaxHighlighter.config.strings.help = "Помощь"
SyntaxHighlighter.config.strings.alert = ""
SyntaxHighlighter.config.strings.noBrush = "Не могу найти язык программирования для: "
SyntaxHighlighter.config.strings.brushNotHtmlScript = "Этот язык программирования не поддерживает html-script опцию "

SyntaxHighlighter.all();
</script>



В 13 строчке мы сообщаем SyntaxHighlighter, что он используется на сайте blogger. Если ваш сайт\блог не находится там, вы можете эту строчку вообще удалить. В таком случае, значения по умолчанию будет false, согласно "устновкам произодителя". См. таблицу http://alexgorbatchev.com/wiki/SyntaxHighlighter:Configuration. Вы можете, естественно, и указать значение false явно. Согласно документации если вы используете сайт blogger, вы обязаны установить здесь true.

В 14 строчке мы укзываем на то, где находится файл clipboardSwf. По умалчанию, там установлен null и это значит, что иконка для копирования в буфер показана не будет.

Со строчки 15 по строчки 24 включительно производиться локализация SyntaxHighlighter на русский. Подробности можно найти тут http://alexgorbatchev.com/wiki/SyntaxHighlighter:Configuration:strings.

В 25 строчке происходит "магия включения SyntaxHighlighter". В этой строчке мы запускаем JavaScript SyntaxHighlighter, чтобы он делал разментку исходного кода.

5. До сих пор мы настраивали параметры, которые находятся в SyntaxHighlighter.config. Эти параметры "глобальные" для всего сайта. Как я говорил выше, есть параметры по-умолчанию для конкретного блока с исходным кодом. Их можно задать двумя способами.

Способ первый, задать их через SyntaxHighlighter.defaults. Например,


SyntaxHighlighter.defaults['gutter'] = false;
SyntaxHighlighter.defaults['smart-tabs'] = false;
...
SyntaxHighlighter.all();


В первой строчке включается нумерация строк, во-второй, включается фича smart-tabs.

Обратите внимание, что эти параметры задаются до вызова функции SyntaxHighlighter.all().

Другой, более распространённый способ, это задать эти параметры в самом блоке с исходным кодом. Пары ключ\значения задают способом, которым напоминает способ их задачи в CSS. Например,

<pre class="brush: java; toolbar=false; gutter=false; collapse=true">

Это означает отразить элемент без панели, без нумерации строк, и в свёрнутом виде.

Тоже самое можно выразить иначе

<pre class="brush: java; light=true; collapse=true">

light=true выключает toolbar и gutter.

Для более подробной информации см. http://alexgorbatchev.com/wiki/SyntaxHighlighter:Configuration

P.S. После одноразовой настройки и небольшой "подгонке" достаточно использовать вышеприведённый линк для справочной информации в повседневной работе.

2 comments:

  1. Спасибо за пост. Как раз занимаюсь прикруткой данной вещи к своему порталу www.isql.co.il.
    А можно ли как нибудь ускорить парсинг
    SyntaxHighlighter.all();?

    ReplyDelete
  2. А вы тоже заметили, что он немного медленно бежит?
    Я видел только совет помещать это сразу перед закрытием тега </body>
    Внутрь скрипта я не лез.

    ReplyDelete