Bramble is based on Brackets
Brackets is at 1.0 and we're not stopping there. We have many feature ideas on our trello board that we're anxious to add and other innovative web development workflows that we're planning to build into Brackets. So take Brackets out for a spin and let us know how we can make it your favorite editor.
The text editor inside Brackets is based on CodeMirror—thanks to Marijn for taking our pull requests, implementing feature requests and fixing bugs! See Notes on CodeMirror for info on how we're using CodeMirror.
How to setup Bramble (Brackets) in your local machine
Step 1: Make sure you fork and clone Bramble.
$ git clone https://github.com/[yourusername]/brackets --recursive
Step 2: Install its dependencies
Navigate to the root of the directory you cloned and run:
$ npm install
Step 3: run the build
You can build Bramble by running the npm build task:
$ npm run build
Step 4: Run Bramble:
The easiest way to run Bramble is to simply use:
$ npm start
This starts an
http-server session on port 8000 for you to work with.
However, if you wish to run your own static server, there are several options available:
Assuming you have Bramble running on port
8000. Now you can visit http://localhost:8000/src.
NOTE 1: Bramble expects to be run in an iframe, which hosts its filesystem. For local
src/hosted.html instead of
src/index.html. To see how the remote end
should host Bramble's iframe, see
NOTE 2: Using
npm run build will overwrite contents in the
src/nls folder. These changes are necessary if you access Bramble using http://localhost:8000/src. After using Bramble, you can undo the changes by running
npm run unlocalize.
NOTE 3: To use Bramble in a production setting locally, you can run
npm run production and access Bramble at http://localhost:8000/dist
Optional Extension Loading
Bramble supports enabling and disabling various extensions via the URL and query params. A standard set of default extensions are always turned on:
You could disable QuickView and CSSCodeHints by loading Bramble with
on the URL.
In addition, you can enable other extra extensions:
You could enable JSLint and LESSSupport by loading Bramble with
on the URL
NOTE: you can combine
enableExtensions to mix loading/disabling extensions.
You should check src/utils/BrambleExtensionLoader.js for the most up-to-date version of these
After you have everything setup, you can now run the server you chose in the root of your local Bramble directory and see it in action by visiting http://localhost:8000/src.
Bramble IFrame API
Bramble is desinged to be run in an iframe, and the hosting web app to communicate with it
MessageChannel. In order to simplify this, a convenience API exists
with the editor, preview, etc.
Loading the API
The hosting app must include the Bramble IFrame API (i.e.,
dist/bramble.js). Note: in
development you can use
src/hosted.html, which does this). This script can either be used as
an AMD module, or as a browser global:
The Bramble module has a number of methods, properties, and events. During its lifetime, Bramble goes through a number of states, including:
Bramble.ERROR- Bramble is in an error state
Bramble.NOT_LOADED- Initial state,
Bramble.load()has not been called
Bramble.load()has been called, loading resources has begun
Bramble.MOUNTABLE- Loading is done and
Bramble.mount()can be begin, or is safe to start
Bramble.mount()is being called, mounting is in process
Bramble.mount()has finished, Bramble is fully ready
The current state of Bramble can be obtained by calling
Bramble.getReadyState(). There are
also a number of events you can listen for (i.e.,
Bramble is an
NOTE: in some browsers (e.g., Firefox) when the user is in "Private Browsing"
mode, the filesystem (i.e., IndexedDB) will be inaccessible, and an error
will be sent via the
error event (i.e.,
err.code === "EFILESYSTEMERROR"). This
is the same error that occurs when the filesystem is corrupt (see
The FileSystem is owned by the hosting application, and can be obtained at any time by calling:
var fs = Bramble;
fs instance can be used to setup the filesystem for the Bramble editor prior to
loading. You can access things like
WARNING: this will destroy data, and is meant to be used in the case that
the filesystem is corrupted (
err.code === "EFILESYSTEMERROR"), or for when an
app wants to allow a user to wipe their disk.
NOTE: you can turn this recovery behaviour on automatically by passing
in the options to
Once you have a reference to the
Bramble object, you use it to starting loading the editor:
// Start loading BrambleBramble;Bramble;
elem argument specifies which element in the DOM should be used to hold the iframe.
This element's contents will be replaced by the iframe. You can pass a selector, a reference
to an actual DOM element, or leave it blank, and
document.body will be used.
options object allows you to configure Bramble:
<String>a URL to use when loading the Bramble iframe (defaults to prod)
<String>the locale Brackets should use
<Boolean>whether to copy the window's location.search string to the iframe's url
<Object>with the following optional properties
<Array(String)>a list of extensions to enable
<Array(String)>a list of extensions to disable
<Boolean>whether to hide Bramble until it's fully loaded.
<Boolean>by default, UI state is kept between sessions. This disables it (and clears old values), and uses the defaults from Bramble.
<Boolean>whether to try and autorecover the filesystem on failure (see
<Boolean>whether to log debug info.
Bramble.load(), you can tell Bramble which project root directory
to open, and which file to load into the editor. NOTE: the optional
if provided, should be a relative path within the project root. Bramble will use this information
when it is ready to mount the filesystem. Use the
"ready" event to get access to the
// Setup the filesystem while Bramble is loadingvar fs = Bramble;Bramble;fs;
Bramble Instance Getters
Once the Bramble instance is created (e.g., via
ready event or
a number of read-only getters are available in order to access state information in the Bramble editor:
getID()- returns the iframe element's
idin the DOM
getIFrame()- returns a reference to the iframe that hosts Bramble
getFullPath()- returns the absolute path of the file currently being edited
getFilename()- returns the filename portion (i.e., no dir info) of the file currently being edited
getPreviewMode()- returns one of
"desktop", depending on current preview mode
falsedepending on whether the sidebar (file tree) is visible
getLayout()- returns an
Objectwith three integer properties:
firstPaneWidthrefers to the editor, where
secondPaneWidthis the preview.
getRootDir()- returns the project root directory to which Bramble is mounted
getTheme()- returns the name of the current theme.
getFontSize()- returns the current font size as a string (e.g.,
getWordWrap()- returns the current word wrap setting as a
Boolean(i.e., enabled or disabled).
falsedepending on whether or not there is a tutorial in the project (i.e., if
falsedepending on whether or not the preview browser is showing a tutorial or not.
NOTE: calling these getters before the
ready() callback on the bramble instance
won't do what you want.
Bramble Instance Methods
The Bramble instance has a number of methods you can call in order to interact with the
Bramble editor and preview, all of which take an optional
callback argument if you want
to be notified when the action completes:
undo([callback])- undo the last operation in the editor (waits for focus)
redo([callback])- redo the last operation that was undone in the editor (waits for focus)
increaseFontSize([callback])- increases the editor's font size
decreaseFontSize([callback])- decreases the edtior's font size
restoreFontSize([callback])- restores the editor's font size to normal
save([callback])- saves the current document
saveAll([callback])- saves all "dirty" documents
useHorizontalSplitView([callback])- splits the editor and preview horizontally
useVerticalSplitView([callback])- splits the editor and preview vertically (default)
find([callback])- opens the Find dialog to search within the current document
findInFiles([callback])- opens the Find in Files dialog to search in all project files
replace([callback])- opens the Replace dialog to replace text in the current document
replaceInFiles([callback])- opens the Replace In Files dialog to replace text in all project files
useLightTheme([callback])- sets the editor to use the light theme (default)
useDarkTheme([callback])- sets the editor to use the dark theme
showSidebar([callback])- opens the file tree sidebar
hideSidebar([callback])- hides the file tree sidebar
showStatusbar([callback])- enables and shows the statusbar
hideStatusbar([callback])- disables and hides the statusbar
refreshPreview([callback])- reloads the preview with the latest content in the editor and filesystem
useMobilePreview([callback])- uses a Mobile view in the preview, as it would look on a smartphone
useDesktopPreview([callback])- uses a Desktop view in the preview, as it would look on a desktop computer (default)
enableFullscreenPreview([callback])- shows a fullscreen preview of the current file
disableFullscreenPreview([callback])- turns off the fullscreen preview of the curent file
enableAutoUpdate([callback])- turns on auto-update for the preview (default)
disableAutoUpdate([callback])- turns off auto-update for the preview (manual reloads still work)
enableInspector([callback])- turns on the preview inspector (shows code for hovered/clicked element)
disableInspector([callback])- turns off the preview inspector (default)
enableWordWrap([callback])- turns on word wrap for the editor (default)
disableWordWrap([callback])- turns off word wrap for the editor
showTutorial([callback])- shows tutorial (i.e., tutorial.html) vs editor contents in preview
hideTutorial([callback])- stops showing tutorial (i.e., tutorial.html) and uses editor contents in preview
showUploadFilesDialog([callback])- shows the Upload Files dialog, allowing users to drag-and-drop, upload a file, or take a selfie.
addNewFile([options, callback])- adds a new text file, using the provided options, which can include:
Stringwith the complete filename to use;
Stringwith the new text file's data;
Stringwith the new file's extension;
Stringwith the basename to use when generating a new filename. NOTE: if you provide
addNewFolder([callback])- adds a new folder.
export([callback])- creates an archive
.zipfile of the entire project's filesystem, and downloads it to the browser.
Bramble Instance Events
The Bramble instance is also an
EventEmitter and raises
the following events:
"layout"- triggered whenever the sidebar, editor, or preview panes are changed. It includes an
Objectthat returns the same infor as the
"activeEditorChange"- triggered whenever the editor changes from one file to another. It includes an
Objectwith the current file's
"previewModeChange"- triggered whenever the preview mode is changed. It includes an
Objectwith the new
"sidebarChange"- triggered whenever the sidebar is hidden or shown. It includes an
visibleproperty set to
"themeChange"- triggered whenever the theme changes. It inclues an
themeproperty that indicates the new theme
"fontSizeChange"- triggered whenever the font size changes. It includes an
fontSizeproperty that indicates the new size (e.g.,
"wordWrapChange"- triggered whenever the word wrap value changes. It includes an
wordWrapproperty that indicates the new value (e.g.,
"tutorialAdded"- triggered when a new tutorial is added to the project
"tutorialRemoved"- triggered when an existing tutorial for the project is removed
"tutorialVisibilityChange"- triggered when the tutorial preview is turned on or off. It includes an
visibilityproperty that indicates whether the tutorial is visible.
"inspectorChange"- triggered whenever the inspector changes from enabled to disabled, or vice versa. It includes an
enabledproperty set to
There are also high-level events for changes to files:
"fileChange"- triggered whenever a file is created or updated within the project root. It includes the
filenameof the file that changed.
"fileDelete"- triggered whenever a file is deleted within the project root. It includes the
filenameof the file that was deleted.
"fileRename"- triggered whenever a file is renamed within the project root. It includes the
newFilenameof the file that was renamed.
"folderRename"- triggered whenever a folder is renamed within the project root. It includes an object that looks something like this:
oldPath: "/path/before/rename"newPath: "/path/after/rename"// Paths to all files contained inside the folder being renamedchildren: "relativeFilePath1" "relativeFilePath2" ...
NOTE: if you want to receive generic events for file system events, especially events across windows using the same file system, use fs.watch() instead.