Monday Feb 26, 2007
In the previous part, we explored the XML multiview, Book example and looking at how the sample works by starting off with DataObject. This part continues the discussion about the Book example to show how it provides custom views for the multiviews. So if you have not seen Part 1, you may want to go through it now.
Contents
- Introduction
- Toolbar view
- Constructing the node tree
- Section inner panels
- Panel Factory
Introduction
Each multiview elements can have any arbitrary swing UI. In XML multiview, the UI is divided into sections to enable displaying of sections according to the XML tags. Construction of UI is in two parts: one: provide the node structure of the entire view, two: implement the individual sections. The node structure holds up the whole UI.
Toolbar view
We will look at the BookToolBarMVElement class. This class essentially implements the node structure, creates and attaches section panels to the nodes. 
The class extends ToolBarMultiviewElement, which extends AbstractMultiViewElement of Multiview API to provide support for XmlMultiViewDataObject which is the dataobject here. The ToolBarDesignEditor is a special class which inherits the TopComponent indirectly. The ToolBarDesignEditor also implements ExplorerManager.Provider and co-ordinates Node selection. The ToolBarDesignEditor is divided into two: contentView, where the section panel goes and errorPane where the validation errors are shown. The PanelFactory belongs to XML Multiview and is a factory for creating different section panels for different XML tags.
Constructing the node tree
Each section view as the one above, constructs the Node structure. The Nodes API is used to build the structure with sections, section containers attached to them. There is a root node at line 48, which has children nodes. These root children carry the actual nodes as you can see at line 62. The Book Node and the Chapter Nodes are inner classes in this BookToolBarMVElement class and they extend AbstractNode. You basically build the sections out of section panels or section containers. Section panels hold the content for individual nodes (like for Book, in above figure) and Section containers hold many section panels, which in turn hold contents from single nodes (for Chapter, in above figure). So there are two things here: build your own node structure and add them to the root node and construct section panels and section containers and attach them to the node. The actual visual which should be displayed as part of each section, comes from SectionInnerPanels, which we will see next. Before that let's look at the remaining part of the puzzle: Attaching the view to the ToolBarDesignEditor and opening a section.
While opening the SectionPanel note that we need to supply the proper element (Book, in this case) so that the SectionInnerPanel gets this object for processing. You can override the validateView() method to implement the validation while creating new tags and editing the existing ones here. But you can also supply validation in the section inner panel, which would give more control over the individual UI fields as they are local and accessible there.
Section inner panels
The section inner panels are the actual UI elements that are shown on the multiview element.
The BookPanel extends from the SectionInnerPanel, which is essentially extends from JPanel. So you could create a JPanel and create all UI elements using GUI builder and later change the super class to SectionInnerPanel. Note the constructor of BookPanel. It accepts the SectionView associated with this panel from the previous ToolBarDesignEditor. It also accepts the data object and the tag object, which is specific to the current panel. These are actually supplied by PanelFactory (which we will see next). So the ToolBarMVElement creates node structure and attaches the section panels and section containers, and Panel Factory invokes a particular SectionInner Panel upon getting a particular XML Tag object (which is basically a model object). In Section inner panel, you can set a particular validate method to your UI fields such as textfields and radio buttons. The line 44 shows one such example. XML multiview supports validation handling of most of the component except for most notably components : JList and JTable. For these components, we need to implement the validation and hook it to the existing validation mechanism. It us upto us, how we parse the data from the given data object and assign the data to the UI fields. This is done in the constructor.
The setValue() method is a callback method and is called by the XML Multiview API. This callback is invoked on the focus lost event handling of the UI fields after validating them. So this way, user edited data gets stored in the model. We need to provide the implementation for this method if we want to use two way sync. The documentChanged() method handles the validation error display task. For each UI field, we can specify the validation messages upon checking what failed. For example, at line 61, the emptyness of Book title field is checked and appropriate error message is picked up from the bundle and is shown using the methods provided by SectionView.
How this view (section inner panel) notifies the data object that view has changed? Through *UIChange() methods. There are startUIChange(), signalUIChange() and endUIChange() methods. Out of these, only endUIChange() is useful most of the time, we want to notify when user completes his udpates and the validation is succeeded. You may also note that the signalUIChange() method is deprecated. So this calls the modelUpdatedFromUI() method on the data object which will trigger the whole synchronization process as discussed in Part 1.
Panel Factory
This is the last piece (finally 
).
Factory design pattern is used here to create and return various section inner panels depending upon what key is passed. The key is one element in the model (or it is a XML tag). We need to create this panel factory to create and return our inner panels depending upon the model keys and Section view correctly embeds them and shows them.
This is end of Part 2 of this series. In this, we discussed how to provide custom UI sections to embed in the multiview elements. The next part shows how to add another multiview element and show a graph view of book and chapters using Visual Library 2.0. See you soon!
Disclaimer: The modules described here are purely experimental so no guaranties. Use at your own risk.
Sunday Feb 25, 2007
Introduction
In NetBeans, to represent a file visually, you can use Multiview API to have multiple sectioned views. XML multiview builds top of this API and adds support for XML based data model. You can see the XML multiview in action while editing the web.xml in any Web application created inside NetBeans. Here is the screenshot: 
Still not a standard API
XML multiview API is not a standard API now, but in future it may be included as a standard API.
Please note that both these APIs are still under development and they are subjected to change until they are published as stable APIs.
Please vote to the issue #107858 if you are using XML multiview in your development. More votes, more is the chance that one day XML multiview will become a stable API and be part of the official NetBeans platform.
If we want to use these APIs now, then we need to depend on the current implementation version. (You might know that every NetBeans module API specifies two kinds of version information: specification version and the implementation version.) If we depend upon the implementation version rather than the published specification version, there is quite a good chance that we will face some issues during deployment and providing updates.
Book example
With that let's get started. For this we will use the Geertjan's book example and extend it to integrate the Visual library to display Book and its chapters in a graph. First, download the Book sample project from his update center, or download it here. Unzip and open the project in NetBeans 5.5 IDE. When you run the project and open the abc.story file (from file menu), you can see the multiview in action.
Update : The Book multiview example is updated to run on the latest NetBeans 6.7 IDE. Please download it from here. Thanks to 'JS' from the comment section from this blog.
This book example, is part of the NetBeans source and it is a test project in automated unit tests for XML multiview module. This example was used by Geertjan to illustrate how the multiview looks. If you have the 5.5 sources, you can find this project under <sources_root>/xml/multiview/test/unit. So this project contains the necessary support files and some additional code for the unit tests.
Digging deep into the example
The following picture shows the BookMVEditorSample project view with relevant files highlighted.
In this sample, the file abc.story is the XML file for which the XML multiview editor is written. A new filetype support is added to this file to make NetBeans understand this file as some XML file. The advantage is getting XML editing support and DataObject support. There is a tutorial which explains how to add filetype support for an arbitrary file such as jar manifest file. BookDataLoader.java, BookDataNode.java, BookDataObject.java, BookResolver.java and layer.xml files are created when the new filetype support is added. The dataloader is a loader which creates dataobject from the FileObject. The datanode provides the view for the file. For example, you can set an icon for the file to show in the treeview, when this file is displayed in the explorer view such as Project view. The resolver file adds a MIME type support. the layer.xml file is the metafile for the whole module and it has the registration for the new filetype as below:
Book.java and Chapter.java are model classes. These hold the marshalled XML data. In the original example, these classes are generated using schema2beans library. Because of the loose coupling between XML multiview and the model used, we can use JAXB stubs too in place of these.
Setting dependency for the project
As I mentioned earlier, the XML multiview extends the basic Multiview API. And as XML multiview API is not a standard API, the Book sample depends on the implementation version of it. You can do that for your project by adding a dependency and choosing the implementation version in the 'Edit dependency' dialog as below: 
XML multiview provides two types of built-in views : Toolbar view and TreePanelView. And there are base classes to implement these views. BookToolBarMVElement implements the toolbar view, while BookTreePanelMVElement implements a treepanel view. (refer the above projectview figure). The web.xml view is a toolbar view. The book example has code for both toolbar view and treepanelview (as you can see both files,BookToolBarMVElement and BookTreePanelMVElement are present). We will use toolbar view, which will enable us to implement a visual graph in one of the multiview.
MultiView code
The BookDataObject is the starting point. The new filetype wizard will generate this file. For adding multiview support, this file extended to have multiview specific code. Specifically, the dataobject is changed to extend the XMLMultiViewDataObject, instead of UniDataObject as shown below.
Customizing the DataObject
Extend the constructor
Parse Document
Model synchronizer is the one which takes care of two way synchronization between the view and the XML file. We add CheckXMLCookie and ValidateXMLCookie to the existing list of cookies to make use of the XML support provided by the NetBeans platform. The parseDocument() method is of current interest.
Construct MultiView Description
As this example uses schema2beans library for generating the model, you see it used here in this method shown above. The Book is the root tag. The call to Book.createGraph(), will result in parsing the whole XML file and constructing a XML graph objects with the data filled in. If we plan to use some other library to generate the model, then here is the first place to edit.
Next, the DesignView is the multiview descriptor class which constructs a multiview. We can see that this class constructs a toolbar view by returning BookToolBarMVElement at line 110. Note how the dataobject (model, in our case) is passed to the actual MVElement.
Now, return this DesignView in the overridden method 'getMultiViewDesc()' as above. Note that if we want, the TreePanelView instead of the toolbar view, here is the place to change.
Attach multiview section to a XML element
By default, the XML Multiview API provides the XML file view. We need to tell the API to open up a particular multiview section for particular XML tag. The showElement() does this.
Model Synchronization
The model synchronization is handled by extending the ModelSynchronizer class as follows:
You need to return true from mayUpdateData() to tell the API that you need synchronization and this model synchronization should be called to do that. The updateDataFromModel() method does the actual sync. It takes the model object and calls the write() method of BaseBean, which is part of schema2beans. Again, this is the place to change if we want to use other derived model classes such as from JAXB. In the original book example, there are two errors: first, the call to the datacache is commented out at line 173, which turns off the sync altogether and second, the updateDataFromModel() is overridden wrongly. The filelock object is of the type: org.openide.filesystems.FileLock and not java.nio.channels.FileLock. If you have downloaded this example from my blog link, you have these errors fixed already.
Connect model synchronizer to the rest
The above code calls the model synchronizer when needed. This call usually originates from the view.
This is the end of Part 1 of this series. In this, we explored what is XML multiview and how to start implementing one for a custom XML file. The next part shows how we can actually provide the UI in the multiview elements.
Disclaimer: The modules described here are purely experimental so no guaranties. Use at your own risk.
Sunday Feb 11, 2007
The existing link for the Visual Library (graph module) javadoc is kind of different than the usual one. Also, this is outdated, it does not list the new classes for example: TwoStateHoverProvider. Here are the zip files generated from the sources. org.netbeans.visual and org.netbeans.util
If you want to use, ust download them to the local folder and unzip or import them to the IDE itself so that when you place the cursor on any related class, and chose Tools/Javadoc Index Search, the javadoc browser shows the javadoc inside the IDE itself.
