Implementing a Custom Browser Area

As mentioned above, the initialize() method typically creates and displays the area's initial browser. This procedure can be divided into the following steps:

1. Create browser model.
2. Add the created browser to the area's visible browsers.
3. Give the browser focus.
4. Update the browser's items, that is its content.

In this example you add a browser of type DefaultSearchBrowserModel, which is the same kind of browser which is used by the default browser area. The DefaultSearchBrowserModel class implements the SearchBrowserModel interface, and offers not only the functionality for displaying items in different fashions, but also the simple search, advanced search dialogs,and item activation.

This browser requires a main type of type ObjectTemplate to be passed as constructor parameter.

Creating a new instance with main type set to Item looks like this:

BrowserModel browserModel = new DefaultSearchBrowserModel(UISessionUtils.getCurrentSession().getTypeService().getObjectTemplate("Item"));

When you created the browser, you need to tell the area to show it, so you add it to the area's visible browsers:

this.addVisibleBrowser(browserModel);

Finally give our browser focus and make sure its content is updated:

this.setFocusedBrowser(browserModel);
	browserModel.updateItems();

The complete initialize method now looks like this with some minor things added:

@Override
public void initialize()
{
	BrowserModel browserModel = null;
	if(this.browsers == null || this.browsers.isEmpty())
	{
		browserModel = new DefaultSearchBrowserModel( UISessionUtils.getCurrentSession().getTypeService().getObjectTemplate("Item") );
	}
	else
	{
		browserModel = this.browsers.get(0);
	}
	this.addVisibleBrowser(browserModel);
	this.setFocusedBrowser(browserModel);

	browserModel.updateItems();
}

In order for a browser area to be notified of and react on browser events it needs to register a BrowserModelListener with the browsers it is managing. Depending on what kind of browsers your browser area support, the getBrowserListener() method needs to return an adequate browser listener. The following UML diagram shows the browser model hierarchy. The required corresponding browser model listener is shown beside each browser model.

Your custom browser area supports search browsers, so the listener needs to implement the SearchBrowserModelListener interface.

You use the DefaultSearchContextBrowserModelListener shipped with the cockpit framework. Writing your own browser model listener isn't a subject of this article, but the users who wish to write their own browser model listeners, this class can serve as a good starting point.

Creating and returning a DefaultSearchContextBrowserModelListener is easy. You need to pass the browser area as constructor parameter. This is important, since the listener needs to be able to access the browser area, for example in order to minimize a browser. To see how the method is implemented, the following The Complete Class CustomBrowserArea.java section.

If you want to be able to save queries and do not need to provide some custom behavior when doing so this method only needs to notify the registered BrowserAreaListeners that a query should be saved. You need to use the following line of code:

@Override
public void saveQuery(final BrowserModel browserModel)
{
	this.fireBrowserQuerySaved(browserModel)
}

The complete code looks like this:

CustomBrowserArea.java

public class CustomBrowserArea extends AbstractBrowserArea
{
	private boolean initialized = false;
	private BrowserModelListener browserListener = null;

	@Override
	public BrowserModelListener getBrowserListener()
	{
		// always return the same listener
		if(this.browserListener == null)
		{
			// create a new browser model listener and pass this browser area as parameter
			this.browserListener = new DefaultSearchContextBrowserModelListener(this);
		}
		return this.browserListener;
	}

	@Override
	public void initialize()
	{
		// only initialize once
		if(!this.initialized)
		{			
			BrowserModel browserModel = null;
			if(this.browsers == null || this.browsers.isEmpty())
			{
				// area has no browsers, so create a new one
				browserModel = new DefaultSearchBrowserModel( UISessionUtils.getCurrentSession().getTypeService().getObjectTemplate("Item") );
			}
			else
			{
				// area already has a browser, so use the first one
				browserModel = this.browsers.get(0);
			}
			// show browser
			this.addVisibleBrowser(browserModel);

			// give browser focus
			this.setFocusedBrowser(browserModel);

			// make sure browser is updated
			browserModel.updateItems();
		}
	}

	@Override
	public void saveQuery(final BrowserModel browserModel)
	{
		// pass on the event to any registered browser area listeners
		this.fireBrowserQuerySaved(browserModel);
	}

}

When extending the AbstractBrowserArea all methods needed in order to notify the browser area listeners are already provided. Their names typically correspond to the names of the methods in the BrowserAreaListener interface, with the added prefix "fire". Let's take item activation as an example.

When an item is activated in a browser, the corresponding browser notifies its registered BrowserModelListeners. In your case it is the listener returned by your browser area's getBrowserListener() method, by calling their itemActivated(final TypedObject item) method. Now, typically the area does not need to do anything itself, but merely acts as a proxy, forwarding the event to the perspective. This is done by calling fireItemActivated(final TypedObject item).

To sum it up, the flow looks like this:

1. Item is activated in browser.
2. For each registered browser model listener, the browser calls the itemActivated(final TypedObject item) method.
3. The browser model listener passes the event on to the registered browser area listeners e.g. perspective by calling fireItemActivated(item).