bg-tree-view-toolbar package

2020-09 Update

This project uses the bg-atom-utils npm package which now installs a number of extensions to the atom.* API objects. I think that they are unlikely to cause problems, but if you experience any, please take the time to create an issue on this package to let me know. I am very interested in addressing any issues quickly.

Summary

This adds a toolbar to the top of the Atom tree-view. It comes with some builtin buttons that can to turned on/off in this package's settings page. You can also add your own buttons by using one of its APIs in your own package or in your init.js.

This package also includes a number of enhancements to the bundled tree-view package. Those should be a part of that package and I have made PR on that project for at least one of them but it looks like it will take some time for it to be accepted if ever. So any enhancement that patches the tree-view code at runtime can be turned on/off in this package's setting page under the 'Dynamic Patches' section. Note that some of these new tree-view features add configuration settings to the tree-view settings page so go there to configure those features once they are enabled on this page.

This package includes a CSS style that makes the color of the selected tree item highlight change when the tree view has the focus so that you can more easily tell where the focus is in your workspace. That is not controllable through a setting, but you could change it by overriding it in your styles.less file.

Commands

This package provides the following commands. The commands that manipulate the included buttons are only active when the toolbar is shown.

Note that the 'shown' state of the toolbar refers to whether it is shown when the tree-view is visible. It maybe 'shown' even if the tree view tab is not activate and therefore neither the tree view nor the toolbar would be visible.

Included Buttons

btnBarCfg (gear icon on upper right)

Opens the settings view to this window to configure and learn about the toolbar

btnHidden '.*'

Toggles the 'tree-view.hideIgnoredNames' configuration to hide and reveal hidden files in the tree view.

btnColAll '1st Lvl'

This is similar to collapses-all except it keeps the first level expanded. This is useful when your tree view has only one project node. collapse-all results in only that one node being shown but that is not very interesting.

btnTrack 'Auto Track'

This controls whether the tree selection changes to reflect the active editor pane as you focus different tabs. This relies on a change I submitted in March 2020 to the tree-view project and I am releasing this package before I know if it will be accepted. If the tree-view package you have does not have this change, this button will not be enabled even if its configuration is enabled.

fontGroup

This is a group of buttons that change the font size and line spacing of the items in the tree view. This has the effect of zooming in and out to make the tradeoff of seeing more of your project and each item being easier to read.

The commands that these buttons execute are provided by the [bg-ui-font-sizer] package so these buttons will not be visible unless you have installed that package.

Adding Additional Buttons

A service is exposed so that you can control the toolbar and add/remove buttons. The service is available not only via the Atom service hub controlled by package.json but also via the bg.BGAtomPlugin.get('bg-atom-tree-view-toolbar').view... global entrypoint accessible in the console or init.js (See bg-atom-utils npm package). That allows easily using the service in the init.js file so that you can customize your personal editor without the overhead of making and maintaining an atom package.

The examples below illustrate a trivial button that alerts a message when clicked. To see examples of more functional buttons, look and the lib/treeViewButtons.js to see how the builtin buttons are created using the BGDOM component library.

The Toolbar Service API

<srv>.isShown()

return true if the toolbar is attached to the tree view (not whether you can see it at this time)

<srv>.show()

attach the toolbar to the tree view

<srv>.hide()

remove the toolbar from the tree view

<srv>.getTreeView()

returns a reference to the tree-view object

<srv>.addButton(btnName, button)

add a new button with a unique name

• <btnNam> : names follow the rules of JS variable names
• <button> : the button object follows the REDOM style of components. It can be specified as one of these...
  • html string. It should have one top level node. A DOM Node will be created using outerHTML (conceptually)
  • a DOM Node. create it any way you like
  • any JS object that has a .el property that is a DOM Node. This style is compatible with REDOM and bg-atom-redom npm pacakges.

<srv>.getButton(btnName)

return the button. This might be a DOM node or a JS object that has a .el prop which is a DOM node.

• <btnName> : names follow the rules of JS variable names
• <return value>: returns what was passed into addButton except that html strings will be returned as their realized DOM Node.

<srv>.removeButton(btnName)

remove the named button

• <btnNam> : names follow the rules of JS variable names

<srv>.isButtonEnabled(btnName)

buttons that are added to the toolbar can be turned on and off. This is useful for user preferences and dynamically turning off some buttons to make room for others based on what the user is doing.

• <btnNam> : names follow the rules of JS variable names

<srv>.enableButton(btnName, onoff)

turn the named button on(true) or off(false)

• <btnNam> : names follow the rules of JS variable names
• <onoff> : true means the button will be on/enabled, false == off/disabled

init.js Example

You can try this right now by copying this code into your inti.js

• open your init.js (edit menu -> 'Init Script...'), copy the text below into the file, then restart Atom (window:reload command)
• note atom might assume you want a .coffee file. You can safe as and rename it to .js if you want

In init.js ...

toolbar = bg.BGAtomPlugin.get("bg-tree-view-toolbar").getViewV1();
toolbar.addButton(
    'f1',
    '<button class="btn">F1</button>'
)
toolbar.getButton('f1').onclick = ()=>{
    const tv = toolbar.getTreeView();
    atom.commands.dispatch(tv, 'tree-view:collapse-all');
}

Dev Console Example ...

Open the dev console (cntr-shift-i or window:toggle-dev-tools command) and you can experiment with the toolbar API in real time. After you type bg.BGAtomPlugin.get("bg-tree-view-toolbar").getViewV1(). autocomplete will show you what is available.

Create an f1 button...

toolbar = bg.BGAtomPlugin.get("bg-tree-view-toolbar");
toolbar.addButton('f1', '<button class="btn">F1</button>')
toolbar.getButton('f1').onclick = ()=>{alert('Hello World')}

Then to remove the f1 button...

toolbar.removeButton('f1')

Atom Service Example:

In your package's package.json...

...
"consumedServices": {
	"bg-tree-view-toolbar": {
	"versions": {
	  "^1.0.0": "consumeTreeViewToolbar"
	}
  }
},
...

In your package's JS file referenced in package.json's "main" property...

...
    consumeTreeViewToolbar(toolbarService) {
		toolbarService.addButton(
			'f1',
			'<button class="btn">F1</button>'
		)
		toolbarService.getButton('f1').onclick = ()=>{alert('Hello World')}
	}
...

Customizing the Toolbar Style

You can change a lot about the toolbar by styling it differently in your styles.less file. The default styling is in the ./styles/bg-tree-view-toolbar.less file in this project's pacakge folder (typically that will be ~/.atom/pacakges/bg-tree-view-toolbar). You can copy all or part of that file to your ~/.atom/styles.less file to make changes.

The general structure is this...

div.bg-tree-view-toolbar {
	// attributes for the bar container

    .btn {
        // default attributes for all buttons inside the (The .btn class is used by atom for all standard button styling)
    }

	.<buttonName> {
		// styling for a specific button. See the Included Buttons section for the names.
	}

Hacking Tip

If you want to play around with this package in ways that are not exposed through the commands, open devtools console (window:toggle-dev-tools) and explore the bg... global variable. Start typing the bg... to see what mechanisms are available to explore.

• bg.BGAtomPlugins.logStatus() : list the packages that use the BGPlugin style
• bg.BGAtomPlugins.get(pkgName) : get a reference to a package plugin instance to explore
• bg.PolyfillObjectMixin.logStatus() : list the Atom polyfills that are installed (these add features to Atom API)

When you complete a command that returns an object, it will be logged in the console where you can expand it to explore its current state. You can autocomplete further to navigate to the sub-objects and if you assign an object to a variable in the console, you can invoke its methods and see what they do.

> pkg = bg.BGAtomPlugin.get('<packageName>')
> pkg.addCommand(...)