Пишем plugin для Jetbrains IDE: отображение файлов вне проекта в Project Tool

Доброго времени суток, дорогой читатель. Меня зовут Михаил, я Android-разработчик в компании Циан. Этой статьёй я открываю для себя цикл статей по внутренней кухне разработки плагинов для Jetbrains IDE: IDEA, Android Studio (AS) и пр. На дворе 2024 год, официальная документация не так богата информацией, как хотелось бы. Но есть исходники, которые смело можно дербанить. В этом цикле статей я буду описывать свой опыт поиска нужной мне информации и её разбор.

В статье мы разберёмся с тем, как отобразить каталог не из проекта в project tool. 

Я занимаюсь разработкой плагина «Group File Template ​(GFT)​», GFT на Market, GitHub В своей предыдущей статье я описал, как им пользоваться. Весь мой опыт работы с плагинами крутится вокруг него. Поэтому в своём блоге буду рассказывать, как я делал тот или иной функционал этого плагина.

Итак, приступим. Плагин GFT я использую как Android-разработчик. Что это значит? Я работаю с проектом, который лежит в одном репозитории — в нём пишут свой код все Android-разработчики. Мы все имеем одну точку синхронизации — ветку develop. Поэтому, при актуальном develop разработчик имеет актуальные шаблоны для GFT.

Посмотрев статистику по плагину, можно увидеть, что его скачивают не только для AS, но и для других Jetbrains IDE.

Таких скачиваний немного, но и плагин не очень полезный для работы с большим количеством репозиторий. Допустим, у вас 100 репозиториев с проектами, одинаковой архитектурой и синтаксисом. Концепция «содержать шаблоны внутри проекта» для вас крайне не удобная. Ведь нужно содержать 100 одинаковых шаблонов в актуальном состоянии. Звучит как подвиг, достойный Геракла.

А значит, надо научить плагин сохранять шаблоны внутри IDE. Тогда можно будет держать шаблоны в одном месте.

Проблему обозначили, накидаем MVP.

План MVP:

1. При клике правой кнопкой мыши на шаблон GFT, в контекстном меню появляются кнопки «Copy Template» и «Move Template»

2. Перемещаем или копируем шаблон в каталог с IDE

3. При копировании даём возможность переименовать шаблон

4. Отображаем наши шаблоны в project tool.

План небольшой, фича простая. Ну, часа 4 работы, — подумал я и приступил.

День первый. Что такое каталог IDE?

На часах 20:10, классика, приступим. Создаем Action для перемещения шаблонов — MigrateTemplateAction : Action(). Нам нужны 2 кнопочки, значит регистрируем наш Action в plugin.xml 2 раза, с разным именем и ID.

<action        id="MigrateTemplateActionCopy"        class="com.arch.temp.actions.MigrateTemplateAction"        text="Copy Template">    <add-to-group group-id="ProjectViewPopupMenu" anchor="after" relative-to-action="CutCopyPasteGroup"/> </action>  <action        id="MigrateTemplateActionRemove"        class="com.arch.temp.actions.MigrateTemplateAction"        text="Move Template">    <add-to-group group-id="ProjectViewPopupMenu" anchor="after" relative-to-action="MigrateTemplateActionCopy"/> </action>

Мне показалось логичным запихнуть оба Action в блок — CutCopyPasteGroup.

В Action делаем так, чтобы наши кнопки показывались только при вызове контекстного меню на папке с шаблоном. Для этого переопределяем метод update, пишем наше условие и вуаля — всё работает!

override fun update(e: AnActionEvent) {    val project = e.project    val pathTemplate = e.getData(CommonDataKeys.VIRTUAL_FILE)?.path    val shortMainTemplate = File("$pathTemplate/$MAIN_SHORT_FILE_TEMPLATE")    val shirtTemplate = File("$pathTemplate/$MAIN FILE TEMPLATE")    e.presentation.isEnabledAndVisible = project != null && (shortMainTemplate.isFile || shortTemplate.isFile) }

Посмотрел на часы и подумал: «Пфф. Чёт, походу, быстрее сделаю».

Теперь давайте реализуем в нашем Action метод actionPerformed(actionEvent: AnActionEvent). Выглядит всё просто: мы нажимаем на «Copy Template» или «Move Template» и метод вызывается. 

Берём из actionEvent.getData(CommonDataKeys.VIRTUAL_FILE) VirtualFile каталога, по которому мы кликнули. Отлично! Первый путь, указывающий откуда перемещать, у нас есть. Далее, берём путь указывающий куда перемещать. Так, стоп, а откуда его брать? Что такое каталог в IDE?

Начинаем отвечать на вопросы:

• Что такое каталог IDE? Звучит как то, где лежат конфиг файлы самой IDE. Хотя тут я испытываю сомнения.

• Откуда брать? Ну, наверное, должен быть какой-нибудь путь, не на уровне project, а на уровне application.

Не понятно. Ладно. Значит что? Правильно, ставим брейкпоинт и начинаем шерстить всё, что примерно может соответствовать нашим вопросам. На часах 00:30. 

Нашёл чуть больше, чем ничего. Пару прикольных методов, например, File.separatorChar, он отдает разделитель в зависимости от OS компа. Полезно, но не то, что я искал. 

Лааааадно. Иду в документацию, почти ничего не нахожу. Всё не то. На часах 01:20. Мы проиграли эту битву, пора спать.

День второй. Scratch files.

Ночью мне не приснилось гениальное решение. Поэтому, шерстю форумы, блоги и натыкаюсь на Scratch files. 

Scratch-файлы — это полнофункциональные, работоспособные и отлаживаемые файлы, которые поддерживают подсветку синтаксиса, завершение кода и все другие функции для соответствующего типа файлов. Например, во время работы над одним проектом у вас может возникнуть идея метода, который позже можно будет использовать в другом проекте. Вы можете создать рабочий файл с черновиком метода, который не хранится в каталоге вашего проекта, но может быть открыт при работе над любым другим проектом.

Ура! Первая стоящая зацепка! Это же то, что я хочу сделать, ну прям точь-в-точь. Раньше я думал, что это Scratch-файлы — это временные файлы. Всякую требуху туда кидал: JSON из запроса покрутить, main функцию по быстрому вызвать. А оказывается, я миксером шурупы кручу.

Если Scratch-файлы не хранятся в нашем проекте, значит они хранятся где-то во внешнем каталоге. Начинаем наш сёрч, на часах 20:15. Тапаем дважды на Shift, вбиваем Scratch.

Находим 2 объекта: ScratchFileService и ScratchTreeStructureProvider. Заходим в ScratchFileService и находим метод getRootPath.

public @SystemIndependent @NotNull String getRootPath(@NotNull RootType rootType) {        return myRootPaths.get(rootType.getId()); }

Что мы видим: myRootPaths — это ConcurrentMap<String, String> myRootPaths = ConcurrentFactoryMap.createMap(ScratchFileServiceImpl::calcRootPath), из которого по rootType.Id вытаскивается путь. Лезем в calcRootPath.

private static @SystemIndependent @NotNull String calcRootPath(@NotNull String rootId) {  String path = System.getProperty(PathManager.PROPERTY_SCRATCH_PATH + "/" + rootId);  if (path != null && path.length() > 2 && path.charAt(0) == '\"') {        path = StringUtil.unquoteString(path);  }  return path != null ? FileUtil.toSystemIndependentName(path) :        FileUtil.toSystemIndependentName(PathManager.getScratchPath()) + "/" + rootId; }

Что видно? По каким-то свойствам, мы получаем путь к root-каталогу. PROPERTY_SCRATCH_PATH = «idea.scratch.path»

Свойства не обычные, к ним плюсуется какой-то rootId. К тому же, как подкаталог. 

Находим ScratchRootType extends RootType. RootType в конструкторе принимает myId и myDisplayName.

ScratchRootType() {       super("scratches", LangBundle.message("root.type.scratches")); }

RootId получен — это «scratches». Ещё мы видим, что ScratchRootType зарегистрирован в plugin.xml, значит надо не забыть сделать также.

<scratch.rootType implementation="com.intellij.ide.scratch.ScratchRootType"/>

У RootType находим метод getAllRootTypes(). Он возвращает все зарегистрированные реализации RootType.

Кайф, получается я могу отнаследоваться от RootType, зарегистрировать его — и у меня будет путь к моему каталогу с шаблонами. На часах 21:20 первые строки кода понеслись.

Создаю GFTemplateRootType: RootType(ROOT_ID, GFT_ROOT_NAME)и регистрирую его в plugin.xml.

<extensions defaultExtensionNs="com.intellij">    <scratch.rootType implementation="com.arch.temp.extension.GFTemplateRootType"/> </extensions>

Запускаю, вызываю getAllRootTypes(), вижу в списке GFTemplateRootType. Теперь для получения пути позаимствуем метод у ScratchFileServiceImpl.getInstance().getRootPath(rootType). Получаю путь указывающий куда класть шаблоны. Победа!!! Мы знаем точку А и точку Б.

Реализую логику в MigrateTemplateAction, делаю разделение по тексту кнопки. И внимательный читатель в недоумении «Серьезно? По тексту? У нас же есть уникальные ID!» Прикинь, я так и не нашёл, как из Action вытащить его ID (если ты что-то об этом знаешь, беги писать в комменты, добрый человек), это ещё час потраченный в пустую. Перед перемещением вызываем диалог для переименования шаблона.

И собственно всё — наши шаблоны сохраняются в IDE. Но мы пока не видим их в списке шаблонов. Понеслась! Добавляю в ListTemplateActionGroup дополнительный root каталог, в котором мы проверяем наличие шаблонов.

fun AnActionEvent.getListTemplate(): List<MainClassJson> {    val listTemplate = mutableListOf<MainClassJson>()      getData(CommonDataKeys.PROJECT)?.let {        val basePath = getBasePathTemplate()        listTemplate.addAll(getListMainClassTemplate(basePath))    }    val pathHomeTemplate = getRootPathTemplate()    listTemplate.addAll(getListMainClassTemplate(pathHomeTemplate))    return listTemplate }

Запуск и проверка.

Всё работает и даже создаёт всё корректно. На часах 00:40, награждаем себя шоколадкой и спать.

День третий/четвертый/пятый. База. 

Большую часть сделал. Остались пустяки — показать шаблоны в project tool. Все звёзды сложились так, что у Scratch файлов есть свой раздел.

Просто беру и всё, что есть в ScratchTreeStructureProvider, копирую себе. «Обмазываемся» брейкпоинтами, начинаем ювелирить: тут отрезать, сюда приделать, тут переделать. Что-то не работает, берём куски из других мест. Не буду томить, выдаю «Базу» как нам законнектиться с project tool.

Создаём класс TemplateProjectView и наследуемся от AbstractProjectViewPane или AbstractProjectViewPaneWithAsyncSupport.

Регистрируем TemplateProjectView класс в plugin.xml в разделе extension.

<extensions defaultExtensionNs="com.intellij">    <projectViewPane implementation="com.arch.temp.projectView.TemplateProjectView"/> </extensions>

Переопределяем методы и разбираем.

override fun getTitle() = GFT_HOME_TEMPLATES \\ Имя на ProjectViewPane  override fun getIcon() = AllIcons.General.ProjectTab \\ Иконка  override fun getId() = TEMPLATE_VIEW_ID \\ ID по которому можем узнать статус панели и обращаться к ней  override fun getWeight() = 111 \\ Расположение в выпадающем списке чем больше число тем ниже панель

Теперь мы можем увидеть пункт «GFT Templates» в выпадающем меню.

Идём дальше. Когда из списка мы выбираем наше ProjectView, вызывается createTree. Затем createStructure. Я это интерпретировал так, что вначале мы создаём канвас, а затем накидываем на него структуру.

override fun createStructure(): ProjectAbstractTreeStructureBase {    return ProjectViewPaneTreeStructure() }  override fun createTree(treeModel: DefaultTreeModel): ProjectViewTree {    return object : ProjectViewTree(treeModel) {        override fun toString(): String {            return title + " " + super.toString()        }    } }

Реализуем нашу структуру.

inner class ProjectViewPaneTreeStructure : ProjectTreeStructure(myProject, id), ProjectViewSettings {    override fun createRoot(project: Project, settings: ViewSettings): AbstractTreeNode<*> {        return TemplateViewProjectNode(project, settings)    }     override fun isShowLibraryContents() = false  }

Возвращаем в методе isShowLibraryContents false, для того чтобы не показывало вкладку с либами.

Есть похожие методы, они по умолчанию false: isShowScratchesAndConsoles, isShowModules и т. д.

Метод createRoot требует от нас реализацию некой AbstractTreeNode, из которой и состоит вся структура.

В AbstractTreeNode хранится вся необходимая информация для структуры: имя, цвет, иконка, её наследники (если это директория) и всё, всё, всё, что отвечает за отображение элемента.

Реализуем свою ProjectViewNode, для этого переопределяем следующие методы:

• canRepresent, contains. Срабатывают при нажатии SelectOpenedFile

• update. Обновляет представление ноды getChildren(): List<AbstractTreeNode<*>>. Здесь пишем всю логику того, что мы хотим показать.

Я решил накостылить и завёл два RootType: один это rootPath, второй projectPath (ну вот захотелось так, для единообразия). Я их получаю через RootType.getAllRootTypes(), по ID. 

В итоге у нас получается два пункта в структуре: Ide GFTemplates и Project GFTemplates.

Наполняем их, вытаскиваем путь. Это pathProject/template и rootPath/template.

Находим VirtualFile и рекурсивно пробежимся по дочерним элементам. Если это файл, то вернем PsiFileNode, если каталог, то PsiDirectoryNode.

Вот и всё. В структуре мы видим все наше дерево с файлами шаблонов из разных мест. УРА!

Тестируем. Для этого создаём новый шаблон. К несчастью, он не появился в структуре. Пробуем переходить по вкладкам — и неожиданно он появляется. Беда, структура не обновляется самостоятельно, а значит, не делает её принудительное обновление.

В главной ноде при вызове метода init регистрируем слушатель на обновления виртуальных файлов.

VirtualFileManager.getInstance().addAsyncFileListener({ events: List<VFileEvent?>? ->    val update = JBIterable.from(events)        .find { e: VFileEvent? ->            ProgressManager.checkCanceled()            val parent = getNewParent(e!!)            if (TemplateUtils.isTemplate(parent)) return@find true            if (!isDirectory(e)) return@find false            false        } != null    if (!update) null else object : AsyncFileListener.ChangeApplier {        override fun afterVfsChange() {            onUpdate.run()        }    } }, project)

Пишу логику на отслеживание того, что в директориях происходят изменения. Обновляем отображение. Запуск. Создаем шаблон — появился, фух! Кликаем на него и копируем, появляется копия в каталоге «Ide GFTemplates».

Кликаем в место где хотим создать шаблон, смотрим список, он отобразился, DONE!

Выводы:

Можно было не использовать ScratchFileServiceImpl и rootType? Скорей всего да, если сесть и разобраться, как зарегистрировать своё свойство и потом обращаться к нему из системы, то легко. Но, в погоне за скоростью реализации и слабым погружением в эту тему, имеем что имеем.

Возможно есть ещё какая-нибудь реализация и она удобнее. Я не нашёл, но чувствую, что есть.

Слабая документация рождает интерес достичь рабочей программы из кусков примера, который скрыт от понимания, а также вдохновляет делиться этим необычным опытом с вами. Мне понравилось! Да и фича вышла полезной. 

Кстати, если посмотреть доку по projectViewPane из кода, то можно увидеть, кто ещё его использовал.

Мы увидим чуть больше 10 плагинов. Теперь и с моим на борту =)

Надеюсь, моя статья была для тебя полезна. Не поленись поставить лайк и написать приятный коммент. Если есть неприятный, тоже пиши — обсудим. Удачи, не болей!

З.Ы. Если твой плагин работает с перемещением / копированием / созданием каталогов или файлов, лучше делать это через Virtual Files. Project tool подписан на их изменения, если использовать Java IO API, то отображение будет обновляться с задержкой.