Частенько появляется соблазн сделать какие-то изменения в CKEditor: дописать туда свои плагины, сконфигурировать его под свои нужды. Благо все это позволяет сделать CKEditor малой кровью. Все это можно найти в документации по CKEditor 4. В данном посте хотел бы рассказать подробно о том, как работать с девелоперской версией CKEditor 4: получение из девелоперской версии релиз версии, сжатие скриптов, включение иконок кастомных плагинов в спрайт и прочее. Всех заинтересованных прошу под кат.
Забрать исходники CKEditor 4 можно с git-репозитория: github.com/ckeditor/ckeditor-dev
Также dev версию можно выкачать в определенной конфигурации ckeditor.com/builder, воспользовавшись предлагаемым на сайте интерфейсом или загрузив конфигурационный файл build-config.js. Подробнее о назначении этого файла расскажу позже.
Итак, начнем. Выкачаем ckeditor-dev с git-репозитория. Внутри есть папка samples, где можно опробовать эти исходники. Чтобы собрать из dev-версии release-версию нам понадобится CKBuilder. Найти его можно в папкe dev/builder. Внутри лежат два интересующих нас файла: build-config.js и build.sh.
Запустим build.sh, после чего найдем созданную папку ckbuilder, где лежит ckbuilder.jar.
Для того, чтобы собрать CKEditor, нужно использовать ckbuilder.jar с необходимыми параметрами. О параметрах CKBuilder можно узнать с помощью ключа --help:
> java -jar ckbuilder.jar --help
Процесс сборки осуществляется следующим образом:
После запуска ckbuilder проверит наличие всех необходимых файлов. Далее начнётся процесс сборки, ckbuilder соберёт все плагины из build-config.js в один файл ckeditor.js. Затем начнётся процесс минификации, все файлы будут изменены и уменьшены.
Важно: CKBuilder в процессе сборки включает в ckeditor.js все необходимые файлы и указанные вами плагины из конфигурационного файла build-config.js.
Все шаги выполнения процесса сборки будут выводится в консоль. Готовый ckeditor по-умолчанию будет лежать в папке release.
Для чего нужен build-config.js?
В этом файле находится стандартные настройки wysiwyg'a, а также список всех плагинов, которые будут собраны в один файл ckeditor.js. Например:
var CKBUILDER_CONFIG = {
skin: 'moono',
ignore: [
'dev',
'README.md',
'.gitignore',
'.gitattributes',
'.idea',
'.mailmap',
'.DS_Store',
'ckbuilder'
],
plugins: {
a11yhelp: 0,
about: 0,
basicstyles: 1,
bidi: 0
}
};
Для того, чтобы включить какой-нибудь плагин в сборку, нужно добавить его название в список с параметром 1.
В ignore можно добавить файлы и папки, которые вы не хотите видеть в release версии. Например, я включил в этот массив папку ckbuilder – она не попадает в release. Все файлы и папки не входящие в ignore окажутся в релиз версии и все js файлы будут минимизированы. Если вы хотите оставить файл не минимизированным, вставьте в него строчку:
// %LEAVE_UNMINIFIED% %REMOVE_LINE%
Подробнее о директивах CKBuilder
CKBuilder копирует файл за файлом из исходной папки в итоговую. Он ищет специальные комбинации символов (директивы) в текстовых файлах и обрабатывает их соответствующим образом.
Некоторые директивы:
%VERSION%
– версия сборки (может быть вставлена с помощью ключа --version ).
%TIMESTAMP%
– конкатенация четырех символов year + month + day + hour (YYMMDDHH) в 36-ричной системе счисления. (Например, 87bm == 08071122).
%REMOVE_LINE%
– удаление строки.
%REMOVE_START%
и %REMOVE_END%
– удаляет все строки между %REMOVE_START% и %REMOVE_END%, включая сами директивы.
%LEAVE_UNMINIFIED%
— оставляет файл, в котором есть эта директива, не сжатым. (Использовать так: // %LEAVE_UNMINIFIED% %REMOVE_LINE%
)
Включаем иконки для кастомных плагинов в спрайт.
Чтобы уменьшить количество запросов к серверу можно включить в спрайт иконки кастомных плагинов. Для этого делаем следующее:
1. В папке со скином создаем папку icons и складываем туда иконки в формате png. Название файла иконки должно совпадать с названием плагина. Чтобы не было проблем с названиями лучше всего называть файлы иконок в нижнем регистре.
2. В папке с плагином тоже создаем папку icons. Туда кладем иконку для этого плагина (название файла желательно в нижнем регистре).
Этого вполне достаточно. Но для того, чтобы иконки работали и в dev-версии, необходимо изменить файл skin.js в папке со скином. В этом файле находим строчку:
// 4. Register the skin icons for development purposes only
Далее раскомментируем написанную ниже функцию. В icons добавим иконки кастомных плагинов.
(function() {
var icons = (
'bullet,' +
'plugin1,' +
'plugin2'
).split(',');
var iconsFolder = CKEDITOR.getUrl( CKEDITOR.skin.path() + 'icons/' );
for ( var i = 0; i < icons.length; i++ ) {
CKEDITOR.skin.addIcon( icons[ i ], iconsFolder + icons[ i ] + '.png' );
}
})();
Подробнее о работе со скинами можно прочитать в документации: docs.cksource.com/CKEditor_4.x/Skin_SDK
Добавляем сжатый ckeditor.js в bundle с помощью SquishIt
Для пущего «ужимательства» рассмотрим добавление сжатого ckeditor.js в bundle с использованием .Net библиотеки SquishIt.
Пробуем включить в bundle файл ckeditor.js:
@MvcHtmlString.Create(Bundle.JavaScript()
.Add("~/Scripts/jquery-1.7.1.min.js")
.Add("~/Scripts/ckeditor/ckeditor.js")
.Render("~/Scripts/test_#.js"))
В результате получим множество джаваскриптовых ошибок:
Причина в том, что ckeditor пытается найти эти файлы относительно текущего местоположения. Проблема решается очень просто. Достаточно указать базовый путь к папке с ckeditor:
<script type="text/javascript">
var CKEDITOR_BASEPATH = '@Url.Content("~/Scripts/ckeditor/")';
</script>
@MvcHtmlString.Create(Bundle.JavaScript()
.Add("~/Scripts/jquery-1.7.1.min.js")
.Add("~/Scripts/ckeditor/ckeditor.js")
.Render("~/Scripts/test_#.js"))
Автоматизация сборки CKEditor 4 в ASP.NET MVC Framework
В данном разделе покажу один из вариантов автоматизации сборки CKEditor 4 в ASP.NET MVC Framework. Заставим проект использовать ту или иную версию ckeditor в зависимости от параметра в web.config.
<compilation debug="false" targetFramework="4.0">
true — используем dev версию
false — используем release версию
Добавим в web-проект в папку Scripts папку ckeditor-dev со всем содержимым. Из девелоперских приблуд в папке dev нам понадобится только ckbuilder, поэтому я удалю эту папку, а вместо нее создам папку ckbuilder с тремя файлами в ней:
— build.bat
— build.js
— ckbuilder.jar
Файл build.bat:
@ECHO OFF
CLS
java -jar %1ckeditor-devckbuilderckbuilder.jar --build %1ckeditor-dev %1ckeditor --build-config %1ckeditor-devckbuilderbuild.js --version 4.2.2 --no-zip --no-tar --overwrite
XCOPY %1ckeditorckeditor* %1ckeditor /e /i
RD %1ckeditorckeditor /s /q
Добавим в проект статический класс DebugSettings:
public static class DebugSettings
{
public static string CkEditorFolder
{
get
{
if (HttpContext.Current.IsDebuggingEnabled)
{
return "ckeditor-dev";
}
return "ckeditor";
}
}
}
Тогда подключение ckeditor будет выглядеть следующим образом:
<script type="text/javascript">
var CKEDITOR_BASEPATH = '@Url.Content(string.Format("~/Scripts/{0}/", DebugSettings.CkEditorFolder))';
</script>
@MvcHtmlString.Create(Bundle.JavaScript()
.Add("~/Scripts/jquery-1.7.1.min.js")
.Add(string.Format("~/Scripts/{0}/ckeditor.js", DebugSettings.CkEditorFolder))
.Render("~/Scripts/test_#.js"))
Осталось только автоматизировать сборку ckeditor. Для этого будем использовать батник build.bat. Ему нужно передать в качестве параметра путь к папке, в которой лежит ckeditor-dev.
На TestApp я добавил вызов build.bat в Post-build event:
call $(SolutionDir)TestAppScriptsckeditor-devckbuilderbuild.bat $(SolutionDir)TestAppScripts
Чтобы ckeditor не пересобирался всякий раз, когда билдим проект, вызов можно закомментировать и вызывать только когда нужно пересобрать ckeditor из исходников:
::call $(SolutionDir)TestAppScriptsckeditor-devckbuilderbuild.bat $(SolutionDir)TestAppScripts
При желании можно добавить в csproj таргет и собирать ckeditor через msbuild. Дело вкуса.
Автор: ne4ta