Common Components
This topic is to discuss common components that may be used by the IDE and editors inside the IDE. We will first enumerate all the components we currently have and then discuss merging and refactoring them into a common components package. Please add new components and elaborate on the details (including API doc, usage info, code pointers and screenshots) here for discussion at our next meeting.
Proposed components to be contributed
From the Haifa team (freedom, modeleditor, formeditor)
Property (Pane/Dialog)
Detailed description of properties dialog framework:
Properties Dialog
Pallete
"List creator"
A widget for use in dialogs or elsewhere, that lets the user build a list of n values.
From the YSL team (pageeditor)
Commands (dojoy.edit.commands)
Command
"Command" represents an undoable modification to a model being edited and must implement execute() and undo() methods for doing and undoing the modification.
Typically you should implement your own command class per your modification type.
Or, alternatively, you may instantiate dojoy.edit.Command with execute() and undo() methods overridden, as like:
var command = new dojoy.edit.Command({
execute: function(){
// make your change
},
undo: function(){
// undo your change
}
});
CommandStack
execute() and undo() methods of commands should be performed only via CommandStack, which manages lists of commands for undoing and redoing.
var commandStack = new dojoy.edit.commands.CommandStack();
var command = new your.package.YourCommand();
commandStack.execute(command);
You can call undo() and redo() methods of CommadStack for undoing or redoing the most recent command.
CompoundCommand
CompoundCommand packs multiple commands into a single undo unit.
Its execute() method executes commands in the order they are added (and in the reverse order on undo()).
For example, the following code executes YourCommandA and YourCommandB, which is undoable at a time.
var command = new dojoy.edit.CompoundCommand();
command.add(new your.package.YourCommandA());
command.add(new your.package.YourCommandB());
commandStack.execute(command);
Actions (dojoy.edit.actions)
Action
"Action" represents a task invoked by a menu item and/or a toolbar button and must implement run(), isEnabled() and matchShortcut().
You may implement your action subclassing dojoy.edit.actions.Action for reusing its generic implementation of matchShortcut().
run() method performs its task and isEnabled() method is called to check if the action can be run in the current context.
A "context" is passed to both methods which is an editor dependent object.
You should provide "label" and optional "iconClass" properties for your command, which will be used for corresponding properties of a menu item and/or a toolbar button when the action is installed.
You may also specify optional "shortcut" property with an object containing "keyCode" (or an array of key code, "keyCodes") and optional boolean members, "ctrlKey" and "altKey", which is used in matchShortcut() to check if an event matches to the shortcut key assigned to the action.
ActionGroup
ActionGroup contains one or more actions and updates a menu (by updateMenu()) or a toolbar (by updateToolbar()) with the actions (including installation of actions for the first time).
Both updateMenu() and updateToolbar() methods take the second parameter for the context object (editor dependent) and the optional third parameter for an option object (with boolean members, "showDisabled" for a menu item and "showLabel" for a toolbar button).
You may subclass dojoy.edit.action.ActionGroup with _actions private member (an array of actions) initialized for your actions or instantiate dojoy.edit.action.ActionGroup with an array of actions passed as the constructor parameter, as like:
var actionGroup = new dojoy.edit.actions.ActionGroup([
new your.package.YourActionA(),
new your.package.YourActionB()]);
actionGroup.updateMenu(menu, context, {showDisabled: true});
actionGroup.updateToolbar(toolbar, context, {showLabel: true});
Your editor's key event handler may call getAction() method of an ActionGroup with a key event object to see if it has an action with a shortcut key matching to the key event.
GlobalActions
GlobalActions is an ActionGroup implementation for "undo" and "redo" actions, which call CommandStack's undo()/redo() methods.
Dialog Components (dojoy.edit.dialogs)
PropertyGrid
PropertyGrid consists of a grid and a toolbar and lists elements of a string array (single column) or a object array (multi-columns).
You may add and remove a element using the toolbar icons and change the values with inline editors (text box, combo box or check box).
The data (array) is set by setData() and the editing result is obtained by getData().
You may specify "valueLabel" property for a single column version for a string array:
var stringArray = ["...", "...", "..."];
var propertyGrid = new dojoy.edit.dialogs.PropertyGrid({
valueLabel: "URL", style: "width: 300px;"});
propertyGrid.setData(stringArray);
While you must specify "properties" property, a map of properties (or columns) with optional label, type, possible values and width, for a multi-columns:
var objectArray = [
{httpEquiv: "...", content: "..."},
{name: "...", content: "..."},
{...}];
var properties = {
httpEquiv: {label: "HTTP Equiv", type: "string" width: "auto"},
name: {label: "Name", type: "string", width: "auto"},
content: {label: "Content", type: "string", width: "auto"}};
var propertyGrid = new dojoy.edit.dialogs.PropertyGrid({
properties: properties, style: "width: 300px;"});
propertyGrid.setData(objectArray);
When you specify "type" of a property (column) to "boolean", a check box is used to change the value, instead of a text box.
When you specify "values" with a string array, a combo box is used to select from the options.
From the China team (assemble, floweditor)
"Collapsable" split pane
Others?
From the Raleigh team
Code editor
File picker
Lets you choose a file from the file system with "type ahead" path competion
Other points to make the UI more consistent
