# Enaml Workbench Developer Crash Course

This document is a short introduction to the Enaml Workbench plugin framework. It is intended for developers of plugin applications that need to get up and running with the framework in a short amount of time. The Workbench framework is not large, and a good developer can be comfortable with it in an afternoon.

This document covers the concepts, terminology, workflow, and the core plugins and classes of the framework. The accompanying example demonstrates the various parts of the framework with a simple plugin application which allows the user to toggle between a handful of sample views.

## Concepts

Writing large applications is hard. Writing large UI applications is harder. Writing large UI applications which can be safetly extended at runtime by other developers is a recipe for hair loss. There are several difficult issues which must be addressed when developing such applications, some of the most notable are:

Registration

  How does user code get dynamically registered and unregistered at runtime?

Life Cyle

  When and how should user code be loaded and run? How and when and how should it be unloaded and stopped?

Dependencies

  How does the application get started without requiring all user code to be available at startup? How does the application avoid loading external dependencies until they are actually required to do work?

Notifications

  How can various parts of the application be notified when user code is registered and unregistered?

User Interfaces

  How can the application be flexible enough to allow user code to add user interface elements to the window at runtime, without clobbering or interfering with the existing user interface elements?

Flexibility

  How can an application be designed in a way where it may be extended to support future use cases which have not yet been conceived?

Ease of Use

  How can all of these difficult problems be solved in such a way that a good developer can be comfortable developing with the application in an afternoon?

The Enaml Workbench framework attempts to solve these problems by providing a set of low-level components which can be used to develop high-level plugin applications. Think of it as a mini-Eclipse framework for Enaml.

Unlike Eclipse however, the Enaml Workbench framework strives to be compact and efficient. Following the “less is more” mantra, it seeks to provide only the core low-level features required for generic plugin applications. It is intended that the core development team for a large application will build domain specific abstractions on top of the core workbench pieces which will then used to assemble the final application.

## Terminology

Before continuuing with the crash course, the following terminology is introduced and used throughout the rest of the document.

Workbench

  The core framework object which manages the registration of plugin manifests and the creation of plugin objects. It acts as the central registry and primary communication hub for the various parts of a plugin application.

Plugin Manifest

  An object which declares a plugin and its public behavior. It does not provide an implementation of that behavior.

Plugin

  An object which can be dynamically loaded and unloaded from a workbench. It is the implementation of the behavior defined by its plugin manifest. This term is often overload to also indicate the collection of manifest, plugin, extension points, and extensions. That is, ‘plugin’ can refer to the actual plugin instance, or the entire package of related objects written by the developer.

Extension Point

  A declaration in a plugin manifest which advertises that other plugins may contribute functionality to this plugin through extensions. It defines the interface to which an extension must conform in order to be useful to the plugin which declares the extension point.

Extension

  A contribution to the extension point of a plugin. An extension adds functionality and behavior to an existing application by implementing the interface required by a given extension point.

## Workflow

Using the workbench framework is relatively straightforward and has only a few conceptual steps.

0. Define the classes which implement your application business logic.

1. If your application will create a plugin which contribute extensions to an extension point, define the extension classes and ensure that they implement the interface required by the extension point. The extension classes should interact with the business logic classes to expose their functionality to the rest of the application.

2. If your application will create a plugin which defines new extension points, define a Plugin subclasses which will implement the extension point behavior by interacting with the extensions contributed to the extension point by other plugins.

3. Create a PluginManifest for each plugin defined by your application. The manifest will declare the extension points provided by the plugin as well as the extensions it contributes to other extension points. If needed, it will supply a factory to create the custom Plugin object.

4. Create an instance of Workbench or one of its subclasses.

5. Register the plugin manifests required by your application with the workbench. Only the plugins required for startup need to be registered. Additional manifest can be added and removed dynamically at runtime.

6. Start the application. How this is done is application dependent.

Points 0 - 3 require the most mental effort. The framework provides a few pre- defined plugins and Workbench subclasses (described later) which make the last few steps of the process more-or-less trivial.

The important takeaway here is that the application business logic should be defined first, and then be bundled up as extensions and extension points to expose that logic to various other parts of the application. This design pattern forces a strong separation between logical components. And while it requires a bit more up-front work, it results in better code reuse and a more maintainable and extensible code base.

## Core Classes

This section covers the core classes of the workbench framework.

### Workbench

The Workbench class acts as the fundamental registry and manager object for all the other parts of the plugin framework. As a central hub, it’s usually possible to access any object of interest in the application by starting with a reference to the workbench object.

The core Workbench class can be imported from enaml.workbench.api.

The core Workbench class may be used directly, though application developers will typically create a subclass to register default plugins on startup. A perfect example of this is the UIWorkbench subclass which registers the ‘enaml.workbench.core’ and ‘enaml.workbench.ui’ plugins when started.

The following methods on a Workbench are of particular interest:

register

  This method is used to register a PluginManifest instance with the workbench. This is the one-and-only way to contribute plugins to an application, whether during initialization or later at runtime.

unregister

  This method is used to unregister a plugin manifest which was previously added to the workbench with a call to register. This is the one-and- only way to remove plugins from the workbench application.

get_plugin

  This method is used to query for, and lazily create, the plugin object for a given manifest. The plugin object will be created the first time this method is called. Future calls will return the cached plugin object.

get_extension_point

  This method will return the extension point declared by a plugin. The extension point can be queried for contributed extensions at runtime.

### PluginManifest

The PluginManifest class is used to describe a plugin in terms of its extension points and extensions. It also defines a globally unique identifier for the plugin along with an optional factory function which can be used to create the underlying plugin instance when needed.

The PluginManifest class can be imported from enaml.workbench.api.

The PluginManifest class is a declarative class and defines the following attributes of interest:

id

  This is a globally unique identifier which identifies both the manifest and the plugin which will be created for it. It should be a string in dot-separated form, typically ‘org.pkg.module.name’. It also serves as the enclosing namespace for the identifiers of its extension points and extensions. The global uniqueness of this identifier is enforced.

factory

  A callable which takes no arguments and returns an instance of Plugin. For most use-cases, this factory can be ignored. The default factory will create an instance of the default Plugin class which is suitable for the frequent case of a plugin providing nothing but extensions to the extension points of other plugins.

Since this class is declarative, children may be defined on it. In particular, a plugin’s extension points and extensions are defined by declaring children of type ExtensionPoint and Extension on the plugin manifest.

### Plugin

The Plugin class is what does the actual work for implementing the behaviors defined by extension points. It acts as a sort of manager, ensuring that the extensions which were contributed to a given extension point are invoked properly and in accordance with interface defined by the extension point.

Well-behaved plugins also react appropriately when extensions are added or removed from one of their extension points at runtime.

The Plugin class can be imported from enaml.workbench.api.

It will be uncommon for most end-user developers to ever need to create a custom plugin class. That job is reserved for core application developers which actually define how the application can be extended. That said, there are two methods on a plugin which will be of interest to developers:

start

  This method will be called by the workbench after it creates the plugin. The default implementation does nothing and can be ignored by subclasses which do not need life-cycle behavior.

stop

  This method will be called by the workbench when the plugin is removed. The default implementation does nothing and can be ignored by subclasses which do not need life-cycle behavior.

### ExtensionPoint

The ExtensionPoint class is used to publicly declare a point to which extensions can be contributed to the plugin. Is is declared as the child of a PluginManifest.

The ExtensionPoint class can be imported from enaml.workbench.api.

The ExtensionPoint class is a declarative class and defines the following attributes of interest:

id

  The unique identifier for the extension point. It should be simple string with no dots. The fully qualified id of the extension point will be formed by dot-joining the id of the parent plugin manifest with this id.

Declarative children of an extension point do not have any meaning as far as the workbench framework is concerned.

### Extension

The Extension class is used to pubclicly declare the contribution a plugin provides to the extension point of another plugin. It is declared as the child of a PluginManifest.

The Extension class can be imported from enaml.workbench.api.

The Extension class is a declarative class and defines the following attributes of interest:

id

  The unique identifier for the extension. It should be simple string with no dots. The fully qualified id of the extension will be formed by dot-joining the id of the parent plugin manifest with this id.

point

  The fully qualified id of the extension point to which the extension is contributing.

rank

  An optional integer to rank the extension among other extensions contributed to the same extension point. The semantics of how the rank value is used is specified by a given extension point.

factory

  An optional callable which is used to create the implementation object for an extension. The semantics of the call signature and return value are specified by a given extension point.

Declarative children of an Extension are allowed, and their semantic meaning are defined by a given extension point. For example, the extension point ‘enaml.workbench.core.commands’ allows extension commands to be defined as declarative children of the extension.

## Core Plugin

The section covers the workbench core plugin.

The core plugin is a pre-defined plugin supplied by the workbench framework. It provides non-ui related functionality that is useful across a wide variety of applications. It must be explicitly registered with a workbench in order to be used.

The CoreManifest class can be imported from enaml.workbench.core.api. It is a declarative enamldef and so must be imported from within an Enaml imports context.

The id for the core plugin is ‘enaml.workbench.core’ and it declares the following extension points:

‘commands’

  Extensions to this point may contribute Command objects which can be invoked via the invoke_command method of the CorePlugin instance. Commands can be provided by declaring them as children of the Extension and/or by declaring a factory function which takes the workbench as an argument and returns a list of Command instances.

### Command

A Command object is used to declare that a plugin can take some action when invoked by a user. It is declared as the child of an Extension which contributes to the ‘enaml.workbench.core.commands’ extension point.

The Command class can be imported from enaml.workbench.core.api.

The Command class is a declarative class and defines the following attributes of interest:

id

  The globally unique identifier for the command. This should be a dot-separated string. The global uniqueness is enforced.

handler

  A callable object which implements the command behavior. It must accept a single argument which is an instance of ExecutionEvent.

### ExecutionEvent

An ExecutionEvent is an object which is passed to a Command handler when it is invoked by the framework. User code will never directly create an ExecutionEvent.

An ExecutionEvent has the following attributes of interest:

command

  The Command object which is being invoked.

workbench

  A reference to the workbench which owns the command.

parameters

  A dictionary of user-supplied parameters to the command.

trigger

  The user object which triggered the command.

## UI Plugin

This section covers the workbench ui plugin.

The ui plugin is a pre-defined plugin supplied by the workbench framework. It provides ui-related functionality which is common to a large swath of UI applications. It must be explicity registered with a workbench in order to be used.

The UIManifest class can be imported from enaml.workbench.ui.api. It is a declarative enamldef and so must be imported from within an Enaml imports context.

The id of the ui plugin is ‘enaml.workbench.ui’ and it declares the following extension points:

‘application_factory’

  An Extension to this point can be used to provide a custom application object for the workbench. The extension factory should accept no arguments and return an Application instance. The highest ranking extension will be chosen to create the application.

‘window_factory’

  An Extension to this point can be used to provide a custom main window for the workbench. The extension factory should accept the workbench as an argument and return a WorkbenchWindow instance. The highest ranking extension will be chosen to create the window.

‘branding’

  An Extension to this point can be used to provide a custom window title and icon to the primary workbench window. A Branding object can be declared as the child of the extension, or created by the extension factory function which accepts the workbench as an argument. The highest ranking extension will be chosen to provide the branding.

‘actions’

  Extensions to this point can be used to provide menu items and action items to be added to the primary workbench window menu bar. The extension can declare child MenuItem and ActionItem instances as well as provide a factory function which returns a list of the same.

‘workspaces’

  Extensions to this point can be used to provide workspaces which can be readily swapped to provide the main content for the workbench window. The extension factory function should accep the workbench as an argument and return an instance of Workspace.

‘autostart’

  Extensions to this point can be used to provide the id of a plugin which should be started preemptively on application startup. The extension should declare children of type Autostart. The plugins will be started in order of extension rank. Warning - abusing this facility can cause drastic slowdowns in application startup time. Only use it if you are absolutely sure your plugin must be loaded on startup.

The plugin declares the following extensions:

‘default_application_factory’

  This contributes to the ‘enaml.workbench.ui.application_factory’ extension point and provides a default instance of a QtApplication.

‘default_window_factory’

  This contributes to the ‘enaml.workbench.ui.window_factory’ extension point and provides a default instance of a WorkbenchWindow.

‘default_commands’

  This contributes to the ‘enaml.workbench.core.commands’ extension point and provides the default command for the plugin (described later).

The plugin provides the following commands:

‘enaml.workbench.ui.close_window’

  This command will close the primary application window. It takes no parameters.

‘enaml.workbench.ui.close_workspace’

  This command will close the currently active workspace. It takes no parameters.

‘enaml.workbench.ui.select_workspace’

  This command will select and activate a new workspace. It takes a single ‘workspace’ parameter which is the fully qualified id of the extension point which contributes the workspace of interest.

### WorkbenchWindow

The WorkbenchWindow is an enamldef subclass of the Enaml MainWindow widget. It is used by the ui plugin to bind to the internal ui window model which drives the runtime dynamism of the window.

The will be cases where a developer wishes to create a custom workbench window for one reason or another. This can be done subclassing the plain WorkbenchWindow and writing a plugin which contributes a factory to the ‘enaml.workbench.ui.window_factory’ class.

The WorkbenchWindow class can be imported from enaml.workbench.ui.api.

### Branding

The Branding class is a declarative class which can be used to apply a custom window title and window icon to the primary application window. This is a declarative class which can be defined as the child of an extension, or returned from the factory of an extension which contributes to the ‘enaml.workbench.ui.branding’ extension point.

The Branding class can be imported from enaml.workbench.ui.api.

It has the following attributes of interest:

title

  The string to use as the primary title of the main window.

icon

  The icon to use for the icon of the main window and taskbar.

### MenuItem

The MenuItem class is a declarative class which can be used to declare a menu in the primary window menu bar.

The MenuItem class can be imported from enaml.workbench.ui.api.

It has the following attributes of interest:

path

  A “/” separated path to the location of this item in the menu bar. This path must be unique for the menu bar, and the parent path must exist in the menu bar. The last token in the path is the id of this menu item with respect to its siblings. For example, if the path for the item is ‘/foo/bar/baz’, then ‘/foo/bar’ is the path for the parent menu, and ‘baz’ is the id of the menu with respect to its siblings. The parent menu need not be defined by the same extension which defines the menu. That is, one plugin can contribute a sub-menu to a menu defined by another plugin.

group

  The name of the item group defined by the parent menu to which this menu item should be added. For a top-level menu item, the empty group is automatically implied.

before

  The id of the sibling item before which this menu item should appear. The sibling must exist in the same group as this menu item.

after

  The id of the sibling item after which this menu item should appear. This sibling must exist in the same group as this menu item.

label

  The text to diplay as the label for the menu.

visible

  Whether or not the menu is visible.

enabled

  Whether or not the menu is enabled.

A MenuItem can define conceptual groups in which other plugins may contribute other menu items and action items. A group is defined by declaring a child ItemGroup object on the menu item. The group will appear on screen in the order in which they were declared. There is an implicit group with an empty identifier into which all unclassified items are added. The implicit group will always appear visually last on the screen.

### ItemGroup

The ItemGroup class is a declarative class used to form a logical and visual group of items in a menu. It is declared as a child of a MenuItem and provides a concrete advertisement by the author of a MenuItem that it expects other MenuItem and ActionItem instances to be added to that point in the Menu.

The ItemGroup class can be imported from enaml.workbench.ui.api.

It has the following attributes of interest:

id

  The identifier of the group within the menu. It must be unique among all other group siblings defined for the menu item.

visible

  Whether or not the items in the group are visible.

enabled

  Whether or not the items in the group are enabled.

exclusive

  Whether or not neighboring checkable action items in the group should behave as exclusive checkable items.

### ActionItem

The ActionItem class is used to declare a triggerable item in a menu. It is declared as a child of a plugin Extension object.

The ActionItem class can be imported from enaml.workbench.ui.api.

It has the following attributes of interest:

path

  A “/” separated path to the location of this item in the menu bar. This path must be unique for the menu bar, and the parent path must exist in the menu bar. The last token in the path is the id of this action item with respect to its siblings. For example, if the path for the item is ‘/foo/bar/baz’, then ‘/foo/bar’ is the path for the parent menu, and ‘baz’ is the id of the action with respect to its siblings. The parent menu need not be defined by the same extension which defines the action. That is, one plugin can contribute an action to a menu defined by another plugin.

group

  The name of the item group defined by the parent menu to which this action item should be added.

before

  The id of the sibling item before which this action item should appear. The sibling must exist in the same group as this action item.

after

  The id of the sibling item after which this action item should appear. This sibling must exist in the same group as this action item.

command

  The identifier of the Command object which should be invoked when this action item is triggered by the user.

parameters

  The dictionary of parameters which should be passed to the command when it is invoked.

label

  The text to diplay as the label for the action.

shortcut

  The keyboard shortcut which should be bound to trigger action item.

visible

  Whether or not the action is visible.

enabled

  Whether or not the action is enabled.

checkable

  Whether or not the action is checkable.

checked

  Whether or not the action is checked.

icon

  The icon to display next to the action.

tool_tip

  The tool tip text to display when the user hovers over the action.

status_tip

  The text to display in the status bar when the user hovers over the action.

### Workspace

The Workspace class is a declarative class which is used to supply the central window content for a ui workbench application. It contains the attributes and method which are necessary for the ui plugin to be able to dynamically switch workspaces at runtime. The application developer will typically create a custom workspace class for each one of the views that will be shown in the workbench.

The Workspace class is declarative to allow the developer to fully leverage the Enaml language in the course of defining their workspace. It will typically be declared as the child of any object.

The Workspace class can be imported from enaml.workbench.ui.api.

It has the following attributes of interest:

window_title

  This is text which will be added to the window title in addition to the title text which is supplied by a branding extension.

content

  This is an Enaml Container widget which will be used as the primary window content. It should be created during the workspace ‘start’ method and will be destroyed by the framework automatically when the workspace is stopped.

It has the following methods of interest:

start

  This method is called when the UI plugin starts the workspace. This can be used to load content or any other resource which should exist for the life of the workspace.

stop

  This method is called when the UI plugin closes the workspace. This should be used to release any resources acquired during the lifetime of the workspace. The content Container will be destroyed automatically after this method returns.

### Autostart

The Autostart class is a declarative class which is used to supply the plugin id for a plugin which should be automatically started on application startup.

The Autostart class can be imported from enaml.workbench.ui.api.

It has the following attributes of interest.

plugin_id

  This is the id of the plugin to start on application startup. The manifest for the plugin must be registered before the ui plugin is started.

## UI Workbench

The UIWorkbench class is a simple sublass of Workbench for creating ui applications. This class will automatically register the pre-defined ‘core’ and ‘ui’ workbench plugins when it is started.

The UIWorkbench class can be imported from enaml.workbench.ui.api.

It has the following methods of interest:

run

  This method will load the core and ui plugins and start the main application event loop. This is a blocking call which will return when the application event loop exits.