Bazaar Explorer logo Bazaar Explorer - Version Control for Human Beings

Extending and Customizing Bazaar Explorer

Overview

Note

Many of the customization features outlined below were introduced in 1.0beta. Please upgrade if you wish to use a feature not available in earlier versions.

It’s easy to customise Bazaar Explorer so that the commands you need and web sites you use are available at your fingertips. Many extension types are supported including:

  • Editors
  • Toolbars
  • Tools
  • Logos.

More generally, Bazaar Explorer can be extended with Accessories. Your personal extensions are stored in your Wallet. To see all of the configurable objects supported, use the File ‣ Accessories dialog.

Your wallet contains a file for each extension type. Click on the links under the Wallet tab in the Accessories dialog for basic instructions. Additional help is provided below.

Configuring editors

Items in the Working Tree browser may be either opened or edited. Opening a file runs the application configured at the operating system level to open files of that type. For a HTML file, this is usually a web browser like Firefox. When developing content though, you often want to edit a web page or image instead of viewing them. To support this, Bazaar Explorer lets you configure custom editor applications.

Note

By default, clicking an item in the status report edits it and double-clicking an item in the Working Tree browser opens it. To launch an editor on double-click instead, change the relevant preference under the Behavior tab in your preferences.

Editors are configured in a file called editors.conf. General instructions are provided at the top of the file with that name stored in your wallet. In a nutshell, editors.conf is a file in INI format where keys are file extensions and values are editor application names. For example:

[DEFAULT]

png, gif = gimp

Editors can be configured globally or per desktop environment. Browse the predefined editors using the Accessories dialog for examples.

Configuring toolbars

Extending an existing toolbar

Toolbars are stored in a file called toolbars.xml. To extend an existing toolbar, simply add a folder with a title matching an existing toolbar name. Your new toolbar items will be appended to the existing toolbar.

Adding actions to all toolbars

If you want to add an action to all toolbars, add items to folders called toolset:prefix and toolset:suffix. These items are prepended and appended to all toolbars respectively.

Replacing existing toolbars and toolsets

If you want to completely replace the contents of an existing folder (rather than append items to that folder), add the existing="replace" parameter to the folder. For example, if your want Open to be the only action appended to every toolbar, add this into your toolbars.xml file:

<folder title="toolset:suffix" existing="replace"  >
  <action name="Open" />
</folder>

Kind-specific toolbars

These are stored in folders called kind:xxx. The supported kind names are given below.

Kind Description
welcome The welcome page
repository A shared repository
virtual-repository A directory searched for nested bzr locations
branch A normal branch
bound-branch A branch bound to another (heavyweight checkout)
checkout A working tree linked to a separate branch

Predefined actions

Most toolbars simply reference existing menu actions. Here are the action names you can use in toolbars.

Menu Action names
File Open, Open_Location, Accessories, Close, Quit
Edit Preferences
View Refresh
Bazaar Add, Diff, Commit, All_Commands, Plugins
Bazaar/Start Initialize, Branch, Checkout
Bazaar/Collaborate Pull, Merge, Update, Push, Send, Tag, Export
Bazaar/Explore Log, Browse, Info, System_Info, System_Log
Bazaar/Work Conflicts, Switch, Bind, Unbind, Revert, Uncommit
Bookmarks Add_Bookmark, Edit_Bookmarks, Refresh_Bookmarks
Tools Add_Tool, Edit_Tools, Refresh_Tools
Settings Rules, Locations, Credentials
Settings/Configuration Configuration, Branch_Configuration
Settings/Ignores Ignores, Working_Tree_Ignores
Help Help_Contents, Welcome, Get_Help_Online, Translate_This_Application, Report_a_Problem

There are also 4 special actions for the submenus within the Bazaar menu: Start, Collaborate, Explore, Work.

Creating new toolbars

To create a completely new toolbar, simply add a folder with the name of the toolbar you want as the title. After restarting Explorer, your new toolbar will be available for selection in the Preferences dialog (or Tools dialog on Windows).

Custom tools

You may also create your own tools and add them to toolbars. The suggested way to do this is to configure a tool in your toolbox and copy-and-paste from one file (tools.xml) into another (toolbars.xml). See below for details.

Configuring Tools

Use the Tools ‣ Add Tool dialog to add Tools. These can be accessed from either:

  • your Toolbox (above the Working Tree Browser)
  • the Tools menu.

Each tool has a:

  • title - the label that appears in the Toolbox and Tools menu
  • category - either bzr command, web site or local application
  • action - the command to execute or URL to open
  • icon - a (hopefully relevant) image.

The following tool categories are supported:

  • bzr - run bazaar command, either directly, if the command is from qbzr or bzr gtk, or via qrun
  • bzr-exec - As ‘bzr’ except that commands run via qrun are run immediately, without any prompting
  • link - open URL
  • application - run local application
  • shell - run shell command

Within the action (labelled Command on the dialog), placeholders are permitted:

  • root - the root of the location (branch, checkout or repository)
  • selected - a space separated list of paths (relative to root)
  • wt_selected - a space separated list of paths selected in the working tree (relative to root)
  • filename - first selected item filename (relative to root)
  • dirname - first selected item directory name (relative to root)
  • basename - first selected item basename (relative to dirname)
  • EDITOR - preferred editor path and options
  • BZR_LOG - path to .bzr.log file
  • branch_root - the root of the branch (for a checkout or branch)

Placeholders are included using the format %(name)s. To include a real % in an action, use %%.

Note

Placeholder values containing spaces ought to be quoted for you so there is no need to surround placeholders with double quotes.

Adding bzr commands

If a bzr command you use isn’t already on the menus, add a tool to access it. If the command you specify looks like a QBzr or Bzr-Gtk command, it will be run directly. Otherwise, the command is run via the qrun dialog. Here are some examples.

Command Actual command
heads bzr qrun –uimode heads
log -r-10.. bzr qrun –umode log -r10..
qlog . :parent bzr qlog . :parent
qrun –category loom bzr qrun –category loom
gmissing bzr gmissing

Note

If you specify a qbzr command, remember to use the --uimode option to keep the dialog open.

Adding web sites

These can be really useful for accessing bug trackers, Continuous Integration tool status pages, documentation, etc.

Adding local applications

These can be good for launching helper applications like profilers, IDEs, modelling tools, etc.

Note

It would be nice to support make, ant, etc. here. That may work via launching a shell each time. Patches welcome.

Organizing tools into folders

Having added tools, you can edit tools.xml (via Tools ‣ Manage Tools ‣ Edit My Tools) and organize them into folders, re-order them, etc.

Custom icons

Bazaar Explorer comes with the Tango icon set which provides many icons for your tools. If you want to add a custom icon for a tool or folder, create a logos directory within your wallet and put 16x16 png files in there. An icon called foo.png is available via the logical name logos/foo.

Configuring hats

You can define extensions that only apply to selected projects by putting them into a “hat”. A hat is simply a folder under .bazaar/explorer/hats (or the equivalent location on Windows) titled xxx and containing the various configuration files for each extension type, e.g. tools.xml.

Numerous sample hats are provided out-of-the-box. You can browse these using the Hats tab on the Accessories dialog.

If you want to give your hat a custom icon, add a file called icon.png at the top level within your hat’s folder.

Sharing extensions with others

If your customizations may be useful to others, it’s easy to package them up and share them. There are 3 ways you can do this:

  1. Publish a project-specific hat as a branch on a hosting site (like Launchpad) and tell other developers on your project about it.
  2. Package your extensions as a Bazaar plugin.
  3. Submit your extensions to the Bazaar Explorer Developers as a predefined accessories that all users will have the option of enabling. See the Clothes tab within the Accessories dialog for samples of these.

To package as a plugin, simply put your extensions within an explorer directory within a normal Bazaar plugin. Don’t forget to ensure bzr will find the plugin by also creating an __init__.py file in the top level of your plugin. See http://doc.bazaar.canonical.com/plugins/en/plugin-development.html for more general details on creating a Bazaar plugin.