MONK : Component Creation Guide
This page last changed on Jan 21, 2009 by amitku.
Components are currently located under trunk/tools in the SVN file system, and are categorized into folders based on what part of MONK they interact with (e.g. chunks, collections, worksets, analysis).
Components reside in their own folder, which, at a minimum, contains an HTML file and a JS file.
The head should link to all the files required by the component. The minimum requirements are: the monkcheck.js file (in trunk/resources/js) and the component's own JS file. The CSS and JS files from Ext JS should be included as well (if your component makes use of them).
The head is the place where the component gets initialized. This is typically accomplished with code snippet below:
You will have weird problems if the component is not created in the <head>. Typical error messages point to <body> and complain about missing functions in the firebug.
Sample code snippet is below
The body should include any visual and functional elements that aren't created dynamically.
All components should be created as classes under the Monk.component namespace. In addition, the component should extend the Workbench.component.Component class.
Use the following code as a guide for component creation. It is taken from the chunk viewer component. For your own component, replace COMPONENT_NAME with your component's name.
In order for the workbench to recognize your component, you need to add it to the list of components (called "plugins" in the file) at trunk/apps/resources/js/monkFeatures.js.
To set a custom icon for a tool, place a file called '/docs/getting-started/workbench/icon.gif' into the tools directory.
The handle method of every component gets called when a Monk.event is sent to the Workbench.component.Manager. Using the event's instanceOf method, you can determine the type of event, and whether it applies to your component.
The notify method is the counterpart of handle. Components use it to send out events to other components, via the Workbench.component.Manager.
By default, this method returns true. If your component requires certain conditions to be met before the Workflow Application moves to the next step in the toolset, you can specify those here. If the component is not valid, this method should return a string containing the details of the error.
When extending Workbench.component.Component, make sure to include the following property:
This is required in order for the correct window to be associated with the component (as each component is contained within an IFRAME).
This property is no longer necessary, as it has been superseded by the label in monkFeature.js (see here).
This property is no longer necessary, as it has been superseded by the description in monkFeature.js (see here).
The Collection is the set of texts which are available for the workbench. They are accessible through the Monk.data.collection.getMetaDataHierarchy method. The Collection is an array and has the following structure:
Note that the Collection in its entirety is huge, and so initially contains only the top-level works for each collection. To get the workparts of a work, you need to call Monk.data.chunk.getWorkInfo(collectionId, workId).
See CollectionManager Calls for a list of possible calls. However, you shouldn't need to make these calls directly, as they are encapsulated in the Monk.data namespace. You can find the calls at trunk/resources/js/data.js.
As these calls are all AJAX, the standard procedure is to make the call, then handle the event that gets sent out when the server response is received. Typically, the data accompanying the event will contain the server response.
When testing locally, make sure you have the proxy set properly as detailed in the MONK workbench quick start guide.
The Data Manager is used to store and process user data, primarily the workset and analysis results. It is located at trunk/resources/data-manager.js, and can be accessed from your component using the static class Monk.component.dataManager. The Data Manager is too large to get into with any kind of detail here. However, some important methods are getWorkset and setWorkset, and initializeProgressDialog (which is used in conjunction with workset saving to run an analysis).
The Messenger is used to send messages to the user. It is located at trunk/resources/js/messenger.js, and can be accessed from your component using the static class Monk.component.messenger. You can call the following methods to display various types of messages: show, progress, alert, wait, confirm, prompt, and growl. These methods all take a 'target' parameter, which determines whether the message should be displayed in your component, or in the workbench itself (except for growl which can only be displayed in the workbench).
As this class is essentially a wrapper for the Ext.Msg class, see the Ext docs for more info on each type of message.
For information on how to put your component into a Toolset, see the Workflow Application.
The Workbench.component.Manager has an array which keeps track of the focus history of component windows. Those windows which have been focused on (i.e. clicked on) recently will be toward the beginning of the array.
In most cases you can ignore the focus history entirely. However, there may be certain instances where you'll want to interact with it. You can force your component to be added to the beginning of the focus history array by by calling Workbench.component.manager.handleFocus(this) from within your component code. Currently, this is only used in chunk viewer components, along with the related hasFocusPriority method, in order to determine if the component should handle an event. See the trunk/tools/chunk/chunk-viewer/chunk-viewer.js for details.
There are several files which you should be aware of when designing your component.
Located at trunk/apps/resources/js/monkFeatures.js, this is the base feature class for our Workbench. Most importantly, it contains the list of components (called "plugins" in the file) which will be available to the user. You need to add your component to this list.
Located at trunk/resources/js/data.js, this file is used for all data calls to the server (e.g. loading/saving worksets, getting chunks, etc.). All calls produce an event upon completion, so handle those in your component to work with the results.
This file also contains the Monk.data.collection.getMetaDataHierarchy method. Use this to get the list of available collections, and their works.
Located at trunk/resources/js/data-manager.js, this class handles all the management of user data. Currently it keeps track of the user's workset and related settings. A global instance of this class is available as Monk.component.dataManager.
Located at trunk/resources/js/event.js, this file lists all the potential events that components can produce/consume. Any new events should be defined here.
Located at trunk/apps/workflow/resources/js/workflowFeature.js, this file contains the definitions for the default toolsets (around line 140). The format is fairly straightforward and the 'layouts' parameters are optional.
The label of the toolset is "Search And Browse", it has two steps -the first step has the searchAndbrowse tool alongside a result summary tool and the second step comprises of the result summary tool and advanced viewer. A gotcha to notice is that
In order to facilitate future code modification and reuse, make sure to document the properties and methods of your component.
We are using the jsdoc-toolkit for documentation. It uses a style similar to javadoc, and has the similar benefit of generating HTML documentation from the code.
Here is a simple example of a documented method:
See the jsdoc-toolkit website for the list of possible tags and in order to download the files necessary to generate the HTML documentation.
The generator is a Java app, run from the command line. Here is some sample code (in Windows) for producing documentation:
This is run from the jsdoc-toolkit folder. Use -d to set the output directory. Include a space separated list of files and/or directories to document. Detailed instructions can be found in the accompanying readme.
When using the Workbench.extend method, use the @lends tag directly under it in order to associate the extended methods with your component:
Namespaces are documented like so:
What does a component need in order to be noticed?
What does a component need in order to be self-contained?
What does a component need in order to exist?
What does a component need in order to post events?
What does a component need in order to listen for events?
What form do events take?
|Document generated by Confluence on May 06, 2009 09:24|