The ELN Editor API Reference
The Notebook Object Interface
The NOb is the data standard used by the notebook client and editors to pass information back and forth. A NOb consists of key-value pairs. There are several mandatory key-value pairs. (These values are of interest to the notebook client and engine for managing NObs.) User-defined key-value pairs can also be added.A NOb has three defined operations. The get method returns a value object given a key. The put method lets you assign a new value to the key. The remove method deletes a key-value pair (mandatory keys will be set to their default values by the remove method). The Java definitions for these methods are shown below.
public interface INOb {
public Object get(String key);
public Object put(String key, Object value);
public void remove(String key);
}
The table below is a list of all mandatory key-value pairs.
| "authorName" | a string identifying the author | string |
| "objectID" | a notebook engine specific object identifier | string |
| "dateTime" | the date and time as returned by the toGMTstring method of the Java Date object | string |
| "label" | a user-defined summary of the NOb. Useful for searching on non-text NObs | string |
| "dataType" | the MIME type/sub type of the NOb data | string |
| "data" | a string or byte array containing the data | string or byte [] |
| "dataRef" | if the data value is null, the dataRef value is a URL pointing to the data itself | string |
| "description" | A text description of the NOb - PNNL only required | string |
The values of all mandatory key-value pairs, except "data", are guaranteed to be non-null. The default value of all mandatory pairs is the empty string - "". The "data" value can be set to null to indicate that the data is stored externally, pointed to by "dataRef".
The Notebook Client Interface
The INBClient interface consists of the single method - Save. This method is a callback that allows your editor to send a NOb back to the client when you're done gathering user input. Here's the definition:
public interface INBClient {
public void Save(INOb saveNOb);
}
The Editor Interface
The editor interface defines only four methods. The getIcon() and getLabel() methods are called by the client to get a Java Image and String, respectively, suitable for display in a menu, button bar, etc., of available editors. The Launch() method is called when your editor should gather user input. If Launch() is called with a null object, you should created a new NOb. If the parameter is an existing NOb, you should edit it. setClient() is called to provide you with a reference to the notebook client (so you can call the client's Save() method when you are finished creating/editing a NOb). setClient() will be called before the first time Launch() is called. Here's the editor interface definition:
public interface INBEditor {
public Image getIcon();
public String getLabel();
public void Launch(INOb aNOb);
public void setClient(INBClient aClient);
}
Note that there is no limit to the number of NObs you can return (i.e. the number of times you can call Save) once your editor has been Launch()ed.
A Sample Editor
The SDK contains source for four sample editors. The TextEditor is very simple editor that allows users to enter free-form text. The Text Editor class is defined to inherit the notebook editor interface:
public class TextEditor extends JFrame implements INBEditor{
It also extends JFrame. (The display of the TextEditor is shown in the lower-right corner of the picture at the top of this page.)
The getLabel() method returns an obvious string:
public String getLabel() {
return "Text Editor";
}
The setClient() sets a static reference to the client:
public void setClient(INBClient aClient){
theClient = aClient;
}
The Launch() method is also fairly simple. It calls the createDisplay() method to create the user interface, complete with text input box, a toolbar for cut/copy/paste buttons, and the Add and Cancel buttons . It then sets a static reference to the NOb parameter. If that NOb is not null, the "data" field is check and the contents are put into the box, if the "data" field is empty then the "datRef" field is checked.
public void Launch(INOb aNOb) {
createDisplay();
mTheNOb = aNOb; // Passed in NOb may contain text to be edited
if(mTheNOb != null) {
// Check for data - if empty read the file in data ref
String dataRef;
String data = (String)aNOb.get("data");
if (data != null) {
mTextEditor.setText(data);
} else {
dataRef = (String)aNOb.get("dataRef");
mTextEditor.setText("data is in dataRef");
}
}
// Set the frame to visible
setVisible(true);
}
Once the user interface is created, the user can enter and edit text as they wish. When they are done, they can click one of the buttons, which results in an ActionEvent. If the user selected "Add", the editor must copy the text in the text box into the existing (edit mode) NOb or a new NOb. The editor also sets the NOb's datatype to "text/plain". The editor then calls the Save() method of the notebook client to return the NOb. The editor then closes itself down.
If the "Cancel" button was selected, the TextEditor simply closes its window and quits without changing or creating a NOb. The code for the response to a click of the "Add" button is shown below:
public void AddButton_actionPerformed(ActionEvent e) {
// if no NOb was passed into Launch() instantiate a fresh one.
if (mTheNOb == null) {
mTheNOb = new NOb();
}
// store the entered text in the data field
mTheNOb.put("data", mTextEditor.getText());
mTheNOb.put("dataType", "text/plain"); // store the MIME type
mTheNOb.put("label", "Plain Text"); // a label
mTheNOb.put("editor", "eln.editors.TextEditor");
mTheClient.Save((INOb)mTheNOb); // call the save() method in the client
dispose();
} // AddButton_actionPerformed
Note that your editor doesn't have to provide values for the "objectID", "authorName", or "dateTime" keys. These are provided by the notebook client and engine. (A good TextEditor might provide a value for the "label" key, perhaps just the first sentence from the text box.)
Other Sample Editors
The HTMLEditor is very similar to the TextEditor. It doesn't yet provide any special HTML editing functionality, but it does set the "dataType" of returned NObs to "text/HTML".The FileUpload editor uses a standard java jfc FileDialog to let the user select a file for upload. Instead of copying the file data into the NOb, this editor sets the "data" key to null and the "dataRef" key to have a value of the form "file://...".
Use eqn editor or publisher here.
You can read the source of these editors to learn more about how they function.
A Simple Client for Testing
***** SDK - test client stuff ****** The SDK contains a simple notebook client that you can use for testing. Once you create your editor, simply put it in your classpath and run the test client:java eln.test.NBClient(Sample classpath: c:\java\lib;.;.\eln\editors ). You should see a window similar to the one shown at the top of this page, with a button showing for your editor. Clicking on this button should launch your editor. The test client prints diagnostic strings as it runs. When your editor saves a NOb, the test client will print a summary of the NOb's content. The should allow you to confirm that your editor runs correctly and that you are correctly saving data into the NOb. **************