Настройка
Общая настройка VSCode
Привязка файлов
Чтобы расширение применялось ко всем XML-файлам необходимо указать для них язык tib. За это отвечает параметр files.associations:
"files.associations": {"*.xml": "tib"}
Язык для любого файла можно поменять в нижнем правом углу, но это одноразовое изменение - в следующий раз файл откроется в соответствии с настройками. Этим удобно пользоваться в случае, если, например, вы попали в ситуацию, когда расширение tiburonscripter сломалось и не даёт нормально дописать скрипт. В этом случае нужно (сразу написать о проблеме и) переключить язык с tib (Tiburon XML script) на xml.
Trusted locations
Так как скрипты чаще всего находятся на сетевых дисках, а VSCode чересчур сильно печётся о вашей безопасности, то необходимо настроить доверенные зоны для доступа к удалённым файлам:
- запустить командную строку (
ctrl+shift+P)
- выполнить команду "
Workspaces: Manage Workspace Trust"
- и там с помощью кнопки "
Add Folder" надо добавить необходимые вам сетевые диски
Автозавершение
Большинство используемых слов встроено в расширение, но VSC может сам предлагать варианты автозавершения на основе слов из редактируемого файла. Если это мешает, то отключается вот так:
"editor.wordBasedSuggestions": false
Так же отдельно настраиваются некоторые области документа, в которых будет предлагаться автозавершение. Чтобы пользоваться всеми возможностями расширения лучше разрешить их везде (по умолчанию в строках и комментариях эта функция отключена):
"editor.quickSuggestions":
{
"comments": true,
"strings": true // включается расширением автоматически
},
Кодировка файла
Чтобы VSC пытался сам определить кодировку файла нужно включить
"files.autoGuessEncoding": true
Настройки расширения
Все настройки расширения имеют префикс tib.
tib.demoPath - путь к скрипту демонстрационной анкеты (используется в команде Открыть код демки);tib.formatSettings - настройки форматирования
braceStyle - стиль открывающейся скобки для JS и CSS, одно из значений: expand (на следующей строке) или collapse (на той же);
tib.useLinq - предлагать ли для автозавершения функции из библиотеки Linq (статические методы IEnumerable);tib.ShowTagInfo - показывать информацию о текущем положени;tib.templatePath - путь к папке с шаблонами;tib.ShowHelpMessages - предлагать подсказки по оптимизации (всплывающие окна);tib.showFullPath - всегда показывать полный путь к файлу в информационных сообщениях.tib.upcaseFirstLetter - автоматически заменять первую букву тегов на заглавную.tib.enableDiagnostic - включает/отключает диагностику.tib.enableFileLock - включает/отключает блокировку редактируемых файлов.tib.largeFileLineCount - определяет количесво строк, больше которого файл считается тяжёлым и функционал плагина ограничивается.
Разное полезное
Символы согласия с предложением
По умолчанию предложение автозавершения принимается не только клавишей Tab, но и Enter. Это не всегда удобно. Отключается вот так:
"editor.acceptSuggestionOnEnter": "off"
Мультикурсорный ввод
По умолчанию мультикурсорный ввод осуществляется с помощью клавиши Alt. Для изменения используется следующий параметр:
"editor.multiCursorModifier": "ctrlCmd"
Сочетания клавиш
Многие сочетания клавиш отличаются от привычного для многих UltraEdit, их можно настроить под себя: Файл -> Параметры -> Сочетания клавиш.
Также на сочетание клавиш можно повесить любой шаблон. Для этого нужно открыть файл keybindings.json (ссылка на него есть в окне настройки сочетания клавиш) и добавить туда такой элемент:
{
"key": "ctrl+alt+.", // сочетание клавиш
"command": "editor.action.insertSnippet",
"args": {
"name": "RedirectStatus" // имя шаблона
}
}
Список шаблонов расширения:
ftpPath - Стандартный путь к материалам проета;
src - img с путём к материалам проета;blockFolding - Сворачиваемый блок;blockLight - Зелёный блок;blockWarning - Красный блок;PageFull - Полная структура Page;PageShort - Краткая структура Page;Question - Структура Question;Block - Структура Block;List - Структура List;RedirectCode - Структура Redirect;RedirectStatus - Структура Redirect со статусом;Redirect18 - Финальный Redirect;Validate - Структура Validate;Filter - Структура Filter;CDATA - CDATA;CustomText1 - CustomText1;CustomText2 - CustomText2 (+style);Quota - Структура Quota;Methods - Структура Methods;
Количество видимых редакторов
Чтобы окно с открытыми файлами не ограничивалось по размеру полезно сделать так:
"explorer.openEditors.visible": 99
Функционал
Редактирование файлов
Т.к. на данный момент VSCode никак не предупреждает о стороннем изменении открытых в редакторе файлов в расширение добавлена следующая схема блокировки:
- при открытии файла для него устанавливается режим только для чтения (т.е. при попытке изменить и сохранить этот файл все остальные пользователи будут видеть предупреждение о том, что файл защищён от записи);
- при открытии файла, заблокированного другим пользователем, показывается предупреждение с указанием имени этого пользователя;
- при закрытии файла блокировка снимается.
P.S. Всегда можно отредактировать файл, занятый другим пользователем, если каждый раз утвердительно отвечать на вопрос VSCode о перезаписи защищённого файла.
Подсветка синтаксиса
Внутри XML распознаётся:
- C#
- Внутри тегов Redirect, Filter, Validate и Methods;
- в кодовых вставках
[c#][/c#];
- в сторчных методах
$method().
- CSS
- внутри тега
<style>;
- внутри
style="".
- JavaScript
- внутри тега
<script>.
- внутри области пользовательских скриптов.
- Специальные вставки
- встроенные функции, такие, как $repeat
- константы.
Выделение парных элементов
При нахождении курсора на одном из парных элементов второй тоже подсвечивается.
<теги>[теги]<!--#block сворачивающийся блок-->
XML шаблоны (Snippets)
Подробнее о создании своих шаблонов можно почитать тут.
При вводе расширение предлагает имеющиеся шаблоны (например, Page, Question и т.д.), которые принимаются нажатием клавиши Tab. Каждое следующее нажатие Tab перемещает курсор к следующей позиции, где предполагается ввод.
Кроме структуры XML предусмотрены следующие шаблоны:
Путь для материалов: после ввода src=" расширение предлагает подставить путь src="@ContentUrl/ с номером проекта из имени файла.
Готовые части кода, вставляющиеся по префиксу _ (для XML) и # (для C#).
Автозавершение атрибутов и значений
Для всех основных тегов (кроме Ui) предлагается список возможных атрибутов. Если атрибут имеет предопределённый список значений, то этот список также подставляется. Для нестроковых атрибутов подставляется значение по умолчанию (для bool-атрибутов — его отрицание). Также в описании указано, поодерживает ли атрибут кодовые вставки. Список подставляемых атрибутов фильтруется проверкой на наличие в текущем узле XML.
Автозавершения в C# коде
При нахождении в области C# кода предлагаются все возможные функции и почти все глобальные объекты и их свойства и методы из нашего движка, а также некоторые типы/структуры/классы и их статические методы из пространства имён System. Кроме того, в автозавершение подтягиваются методы, описанные в блоке <Methods> с модификаторами доступа.
В строках внутри C# предлагаются Id для Page, Question и List.
Автозавершение констант
- Предлагаются все объявленные в скрипте и подключённых к нему файлах, а также встроенные в двигло константы после ввода
@.
Переход к определению
С помощью соответствующих пунктов контекстного меню (Перейти к определению (F12) или Показать определени (Alt+F12)) можно перейти:
- из кодовых вставок к определению функций/переменных, описанных в Methods;
- к Page/Question/List по Id;
- к файлу, указанному в Include;
- к объявленным в скрипте константам;
Подсказки при наведении
При наведении курсора на xml-константу или C# функцию, метод, глобальную переменную и т.д. во всплывающем окне появляется соответствующее определение или список возможных перегрузок.
Форматирование документа
Стандартная команда форматирования блока (editor.action.formatDocument, Shift+Alt+F) форматирует по-разному XML, CSS, JS, C#, обычный текст. На данный момент форматирование подразумевает только изменение пробельных символов (в т.ч. переносы и табуляция) с целью повысить читаемость кода.
Чтобы иметь возможность форматировать C# необходимо установить расширение C# FixFormat. C# форматируется полностью этим расширением - все настройки описаны в его README.
Дополнительные команды
Для всех команд может быть (пере)назначено сочетание клавиш в настройках.
Для вызова команды без сочетания клавиш нужно вызвать командную строку (Ctrl+Shift+P) и ввести название нужной команды.
Все команды расширения можно найти по префиксу tib.
Выделенный текст можно обернуть в тег с помощью сочетаний клавиш Ctrl+Alt+T (команда tib.insertTag). После нажатия tab курсор переходит в позицию атрибутов для тега. По следующему нажатию - в положение после закрывающегося тега. По умолчанию оборачивается в тег [u].
Оборачивает выделенный текст в <![CDATA[ ]]>. По умолчанию назначено сочетание клавиш Ctrl+Alt+C.
- Обернуть текущий тег в CDATA
Оборачивает не выделенный фрагмент, а содержимое того тега, в котором сейчас находится курсор (Ctrl+ Alt + Shift + C).
- Обернуть в сворачиваемый блок
Располагает выделенный текст внутри сворачиваемого блока. По умолчанию назначено сочетание клавиш Ctrl+Alt+B.
- Преобразования
Answer <-> Item
Преобразование выделенных элементов с учётом только Id и Text.
При вставке текста с помощью этой команды (по умолчанию Ctrl+Alt+C) текст вставляется построчно в каждое выделение (конечно, если количество строк совпадает с количеством выделений). Если все строки вставляемого текста содержат табуляцию, то её предлагается заменить на запятую.
Открывает копию актуального скрипта демонстрационной анкеты (Ctrl+Alt+D).
Команда Выделить текущий тег (Ctrl + Alt + P) выделяет тег, в котором находится курсор.
Команда Выделить родительский тег (Ctrl + Alt + Shift + P) выделяет родительский тег (первый после Survey).
- Переключение подстановки
Linq
Команда для быстрого включения/выключения автозавершения из библиотеки Linq (Ctrl + Alt + L).
Вызов команды не изменяет настроек. При перезапуске VSCode значение будет браться из одноимённого параметра в настройках tib.useLinq.
Предлагает выбрать шаблон из XML-файлов в папке, указанной в настройках (tib.templatePath) и открывает его как новый документ (Ctrl + Alt + N).
- Удалить Id вопросов из заголовков
Удаляет Id вопросов, если они встречаются в начале заголовка.
Преобразование текста (квотных лимитов) в List.
Это как AgeList, только с пересечением на пол.
Сортирует выделенный <List> или набор элементов <Item> по указанному элементу (Id, Text, Var) с учётом типа (если все элементы целочисленные, то сортируется как int, иначе — как строка). Пока сортировка работает с не более чем одним списком.
- Преобразовать в Answer/Item
Преобразует выделенные строки в соответствующие элементы, с выделением Id.
Родительские теги (Page/Question/List) подставляются автоматически в зависимости от места вставки.
При генерации вопросов с ответом первая строка считается заголовком вопроса, из которой также получается Id (+ транслитерация при необходимости).
Если нужно сгенерировать только Answer, используйте команду Преобразовать в Answer без Question (ctrl+alt+shift+a).
- Преобразование в блок вопросов/Union-вопрос.
Порядок:
- Выделяем список вопросов и жмём
ctrl + alt + q (Получть Question из выделенного текста).
- Выделяем список ответов (возможно с заголовком) и жмём
ctrl + alt + a (Преобразовать в Answer/Item).
- Выбираем блок/Union/простой
Добавляет на место текущей позиции курсора списки и страницу с выбранной географией (Ctrl + Alt + G). Данные берутся из самого свежего Geo-файла на диске T. После выбора географии предлагается отметить варианты группировки (ФО, область) и ввести Id вопросов.
Добавляет шаблон из RespInfo + Generable + Repeat в зависимости от того, как должна выглядеть база (ротированная/разротированная).
Ctrl + Alt + R.
Выполняет указанный JS-код (Ctrl + Alt + J). Подробнее см раздел Пользовательские методы.
Копирует выделенные элементы (Answer/Item) в виде таблицы (с табуляцией и переносами). Доступна из контекстного меню.
Заменяет выделенные ответы на повтор по листу и создаёт этот лист перед текущей страницей. Доступна из контекстного меню.
Выполняет транслитерацию выделенного фрагмента.
- Документация по пользовательским скриптам
Открывает файл с описанием доступных классов и методов в пользовательских скриптах
Пользовательские методы
С помощью расширения есть возможность запускать свои JS-скрипты. Делается это с помощью команды Выполнить скрипт (tib.runCustomScript, Ctrl + Alt + J). В текстовом поле нужно ввести код и нажать клавишу ввода. Для хранения JS-методов в XML-документе можно использовать комментарий специального вида (содержимое подсвечивается как JS-синтаксис):
<!--#JS
function test() {
console.log(document.lists.getItemText("waveList", "1"));
}
-->
Перед запуском команды всё содержимое таких комментариев добавляется к контексту выполнения кода, поэтому можно просто вызывать созданный метод (например test() из примера выше).
Для удобства обращения к XML-элементам создан специальный объект document класса DocumentObjectModel. Актуальную структуру (для последней версии расширения) класса можно посмотреть в файле по ссылке: DomSignature.d.ts.
После изменений объекта document необходимо вызвать метод applyChanges для применения изменений к тексту документа.
При отладке JS-кода удобно пользоваться встроенной браузерной консолью, вызвать которую можно командой Toggle Developer Tools (Ctrl + Shift + I).
Т.к. код выполняется в контексте расширения, то доступны некоторые дополнительные переменные, методы и подключённые модули. Краткий перечень:
- переменные экспорта Node.js модулей:
- переменные расширения
_inProcess: bool - показывает, что документ находится в процессе обработки расширением (вносятся изменения)._lockedFiles: string[] - массив путей заблокированных пользователем файлов._userInfo: UserData - объект данных о пользователе.
- методы
function yesNoHelper(text: string): Promise<boolean> - показвает вопрос text и 2 ответа (да и нет). Возвращает true в случае "да"._outChannel.logToOutput(message: string, prefix = " > "): void - выводит сообщение в консоль VSCode.
Использование JQuery
С помощью переменной $dom можно работать с JQuery-моделью документа.
Дополнительные методы:
xml() - возвращает внутренний XML объекта;outerXml() - возвращает XML объекта вместе с родителем;XML(element: string) - создаёт новый объект из XML-строки;
Неочевидные особенности:
- Большинство методов JQuery адаптированы под tibXml, но сама функция
$() работает с XML некорректно, поэтому нужно пользоваться $dom и $.XML().
- После изменений в
$dom также необходимо вызывать document.applyChanges().
- Нужно учитывать, библиотека JQuery регистрозависимая и селекторы по id (
#id) в tibXml работать не будут.
Пример:
$dom.find('Quota[Id="test1"]').attr('Id', 'test2');
document.applyChanges();
Данный пример заменяет Id в квоте test1 на test2.
Комментирование
Стандартная команда комментирования зависит от языковой области, в которой вызывается. Если внутри комментируемой области найдены комментарии, команда останавливается.
Также в теме Tiburon Dark различаются по цвету 3 вида комментариев (и в XML, и в C# аналогично — добавлением 1 или 2 *) и сворачиваемый блок:
Тема
Тема находится в отдельном плагине — Tiburon XML themes.
Для выбора темы нужно перейти: Файл -> Параметры -> Цветовая тема. На данный момент доступна пока только тёмная (Tiburon Dark).
О том, как настроить тему под себя можно почитать тут.
Список сущностей языка tib:
"tib.iterator.prefix","tib.iterator.name","tib.iterator.depth","tib.iterator.varindex","tib.iterator.bracket","tib.constant.prefix","tib.constant.name","tib.constant" (целиком @Const),"entity.name.tag.cdata.tib","punctuation.definition.cdata.prefix.tib","punctuation.definition.cdata.bracket.tib","tib.cdata" (целиком <
Парное переименование тега
Стандартная команда Переименовать символ (F2) используется для переименования тегов (как xml, так и html).
XMLPath
В строке состояния (внизу слева) указан XMLPath — все родители и ма элемент, внутри которого сейчас находится курсор.
Особенности
Упрощённый режим
Для больших файлов в целях предотвращения проседания производительности некоторые функции расширения отключаются:
- диагностика;
- некоторые элементы функционала, связанные с данными скрипта (Id XML-элементов и т.п.): автозавершение, подсказки при наведении и т.д.;
- вместо XMLPath в строке состояния показывается надпись
TibXML: LargeFile.
Условия в <Item> вместо C#-кода
Если вместо C# используются условные <Item Page="" Question="" Answer=""/>, то во избежание коллапса подсветки после тега (например <Redirect>) необходимо поставить пробел или символ табуляции на той же строке. В этом случае текст внутри будет подсвечен, как обычный XML. При форматировании документа этото момент должен разрешаться автоматически.
<Methods>
Чтобы использовать все возможности расширения, касающиеся пользовательского кода, методы и переменные нужно объявлять с модификатором доступа (public/private/protected). В противном случае они не будут попадать в список автозавершения и их сингнатуры не будут видны при наведении.
Сочетания клавиш для вызова команд
Все команды (за исключением мультистрочной вставки) расширения завязаны по умолчанию на сочетания клавиш, начинающиеся с Ctrl+Alt, что является не рекомендуемым вариантом для Windows =) Поэтому в случае возникновения проблем просьба сообщать.
Константы
Расширение умеет работать только с константами, не содержащими символ _.
Обратная связь
