Widget Palette

Table of Contents About this wiki page Widget Palette Initialization Providers Descriptors Populating the Widget Palette Adding a Widget to the Canvas Drag a widget from Widget Palette onto canvas Click on a widget from Widget Palette to select it and then click on canvas to add that widget to the current document

About this wiki page

This wiki page describes how some things work in the Widget Palette.

Widget Palette Initialization

The widget palette initializes the first time the visual editor initializes. The key files are:

• davinci/ve/palette/Palette.js
• davinci/ve/palette/PaletteItem.js

Providers

At application startup time, a good part of the initialization of the visual parts of the Widget Palette stems from a call within davinci/ve/palette/Palette.js, to:

• _addProviders()

which calls:

• new davinci.ve.palette.PaletteDescriptorProvider()

which creates a default "provider" that points to directory davinci/libs/dojo_1_4. (Presumably, we could offer an extension point where there could be different site-specific and/or user-specific directories where additional widgets could be found.)

Note that in Palette.js, there are two class variables, "providers" and "_providers":

// "providers" is a comma-separated string that contains a list of custom "providers",
// which appears to be locations for custom widget libraries. However, the custom
// provider feature isn't really working now.
// FIXME: Need to either get rid of "providers" or fix it to make it work.
//
// "_providers" is an array of objects that includes information about the default provider
// and any custom providers. In the current code, there is only the default provider,
// which points to davinci/libs/dojo_1_4.

Descriptors

The list of "descriptors" (dijit,dojox,html,OpenAjax) is initialized within:

• davinci/ve/HtmlWidgets.js

which contains the call to instantiate the widget palette:

new davinci.ve.palette.Palette()</code>

and then does an assignment to the "descriptors" property on the palette's instance object as follows:

this.palette.descriptors = "dijit,dojox,html,OpenAjax";

Populating the Widget Palette

The HTML user interface for the list of widgets is added to the Widget Palette each time a new document is added to the visual editor. The code path is:

davinci/ve/palette/Palette.js: _createPalette() 
forEach()          // loop through array of objects (each with own category) in current *.json file
davinci/ve/palette/Palette.js: addDescriptor()
forEach()          // loop through Palette.js's list of descriptors: dijit,dojox,html,OpenAjax
davinci/ve/palette/Palette.js: setContext()
davinci/ve/HtmlWidgets.js: setContext()
(dojo) constructor()
(dojo) _construct()
(dojo) _makeCtor()
davinci/ve/HTMLVisualEditor.js: constructor()
(dojo) _construct()
(dojo) _makeCtor()
davinci/ui/EditorContainer.js: setEditor()
davinci/Workbench.js: createEditor
davinci/Workbench.js: openEditor()
davinci/resource.js: createFile()

_createPalette() ends up being called in a double-loop:

• Outer loop: foreach on descriptors (dijit,dojox,html,OpenAjax), pull in *.json file for descriptor
• Inner loop: foreach object in the current *.json file (each with own palette category: Form, Layout, Dijit, HTML, Dojox, OpenAjax)

The HTML snippet for each given widget is created in:

• davinci/ve/palette/Palette.js: _createItem()

which makes a call to:

• new davinci.ve.palette.PaletteItem(opt); (foundin davinci/ve/palette/PaletteItem.js)

The machinery within dijit will invoke the buildRendering() and postCreate() methods, which actually set up the HTML snippet and set up event listeners (via this.connect(), which is a dijit wrapper function on dojo.connect()).

Adding a Widget to the Canvas

There are actually two ways to place a widget onto the canvas, described in sections below:

Drag a widget from Widget Palette onto canvas

• The key event setup logic is found in davinci/ve/palette/Palette.js. The _createItem() method in davinci/ve/palette/Palette.js sets up drag/drop behavior for each given widget via the following logic:

_createItem: function(opt){
  var node = new davinci.ve.palette.PaletteItem(opt);
  this.addChild(node);
  var ds = new davinci.edit.dnd.DragSource(node.domNode, "component", node);
  ...
  this.connect(ds, "onDragStart", "onDragStart"); // move start
  this.connect(ds, "onDragEnd", "onDragEnd"); // move end
  ...
}

• The event handler for the drag-start event is onDragstart() in Palette.js, which calls CreateTool(data.data) to set up the drag and create a "tool" object, and then this._context.setActiveTool(tool).
• For the drag-end event, the first mouseup handler is in Context.js, which then invokes the mouseup handler for the current "tool", which ultimately calls createWidget() within widget.js. The call stack for the createWidget() call is as follows:

davinci/ve/widget.js: createWidget()
(?)()
withDoc()
davinci/ve/tools/CreateTool.js: _create()
davinci/ve/tools/CreateTool.js: create()
davinci/ve/tools/CreateTool.js: onMouseUp()
davinci/edit/Context.js: onMouseUp() // calls onMouseUp function for the "active tool"

Click on a widget from Widget Palette to select it and then click on canvas to add that widget to the current document

• The key event setup logic is found in davinci/ve/palette/PaletteItem.js, with its itemMouseDownHandler() and itemMouseUpHandler() routines. One of the key things done in itemMouseUpHandler() is this call, which establishes the currently selected widget as the "active tool" such that if you click on the canvas, you get an instance of that widget:

this.palette._context.setActiveTool(tool);

• The mouseup handler logic for this case is the same as for the drag case.