Writing our first Brackets plugin

Brackets is a free open source editor from Adobe that web developers love because of their killer feature Extract from PSD files. Brackets supports a JS-based plugin extension system. I would like to tell you about the process of developing one of these plugins.

Brackets comes with a small number of out-of-the-box plugins. For this reason, the first thing new users usually do is to install additional extensions. But after a while, you probably catch yourself thinking “if only Brackets had a function ...”. Fortunately, Brackets is an open source editor. It is itself a web application: it is built on our favorite technologies (HTML, CSS, JS) and if you are a web developer, you can help its development by writing an extension. And it is much easier than you could imagine.

Hello world

Strictly speaking, the extension is nothing more than a folder containing a JS file named main.js, which is executed when Brackets starts. You can find the folder with extensions by selecting the menu item “Help - Show extensions directory”.
')
Open the folder with extensions and inside / user create a new folder “myFirstExtension”. Inside this folder, create a file main.js. For a quick start, try inserting a simple HelloWorld code:

define(function (require, exports, module) { console.log('Hello myFirstExtension!'); }); 

Restart Brackets through the Debug - Reload menu and invoke the developer tools (F12 or Debug - Show Developer Tools) to see the result of your extension.

JavaScript modules in Brackets work like CommonJS modules. Understanding this process is beyond the scope of this tutorial, but all we need to know is that all the code in the body of the anonymous function inside define () is executed when the application is started.

Hello alert

Most likely you would like to make an extension that would execute some code not during Brackets loading, but when the user selects a menu item. This behavior is implemented using the command manager. Like almost everything in Brackets, the command manager itself is a module. To access the module, simply call brackets.getModule ().

 define(function (require, exports, module) { var CommandManager = brackets.getModule('command/CommandManager'); // ,       function handleHelloWorld() { window.alert('Hello, world!'); } // -,  ,   ID   handleHelloWorld var COMMAND_ID = 'helloworld.sayhello'; // package-style    var COMMAND_NAME = 'Hello World'; CommandManager.register(COMMAND_NAME, COMMAND_ID, handleHelloWorld); // -,         var Menus = brackets.getModule('command/Menus'); var fileMenu = Menus.getMenu(Menus.AppMenuBar.FILE_MENU); fileMenu.addMenuItem(COMMAND_ID); }); 

Hello document

Now let's try to do something conditionally useful. Brackets has a great Extract function that allows you to cut images, get CSS properties and copy text directly from a PSD file. However, the text is transmitted in the form of HTML entities, which is not always convenient.

 &# 1052;&# 1086;&# 1080; &# 1082;&# 1085;&# 1080;&# 1075;&# 1080; 

Let's try to write an extension that will convert these characters into plain text. We will decode using the JS-function .

In Brackets, open files are represented as instances of the Document class. To get a link to the current document (the file opened by the user for editing), we must use the EditorManager module.

 function handleDecodeHtml() { var editor = EditorManager.getFocusedEditor(); //   var selectedText = editor.getSelectedText(); //    var newText = decodeHtmlEntity(selectedText); //  var selection = editor.getSelection(); editor.document.replaceRange(newText, selection.start, selection.end); //  } 

ReplaceRange adds, replaces or deletes text. If a range is specified, the text in this range will be replaced with a new one. If the third argument is not specified, then the new text will be inserted without replacing the selection.

That's all. It remains to "register" in the "Edit" menu, in the context menu and add hotkeys.

 define(function (require, exports, module) { var CommandManager = brackets.getModule('command/CommandManager'); var Menus = brackets.getModule('command/Menus'); var Menu = Menus.getMenu(Menus.AppMenuBar.EDIT_MENU); //  "" var ContextMenu = Menus.getContextMenu(Menus.ContextMenuIds.EDITOR_MENU); var KeyManager = brackets.getModule('command/KeyBindingManager'); // ... var COMMAND_ID = 'decodehtmlentity.convert'; CommandManager.register('Decode HTML Entity', COMMAND_ID, handleDecodeHtml); Menu.addMenuItem(COMMAND_ID); KeyManager.addBinding(COMMAND_ID, 'Ctrl-Alt-D'); // Ctrl    CMD  Mac ContextMenu.addMenuItem(COMMAND_ID); }); 

Hello publishing

To publish an application , you need to add package.json to the folder with main.js. The package format is pretty simple and will be familiar to those who have experience with Node.js and npm.

 { "name": "brackets.decode-html-entity", "title": "Decode HTML Entity", "description": "This extension uses to decode any HTML-encoded string.", "version": "0.1.0", "engines": { "brackets": ">=1.7.0" }, "license": "MIT", "i18n": ["en", "ru"], "package-i18n": { "ru": { "description": "     HTML-." } } } 

Archive the folder with the extension (there is a “Download ZIP” button on the githaba), log in to the brackets-registry site and publish your extension by downloading the zip file to the registry.

The source code of the plugin is available on gitbach .