WebProtegeImplementationGuide

From Protege Wiki

Jump to: navigation, search

WebProtégé Implementation Guide

Contents


Go to main WebProtege Developer's Guide

Go to to main WebProtégé page


Selection model in WebProtege

The user interface of WebProtege is composed of tabs, and tabs are filled with portlets. A portlet usually display the content of an entity. For example, the RestrictionsPortlet displays the restrictions of the current entity. Each tab usually has a controlling portlet which provides the selection for the other portlets in the tab. For example, the controlling portlet in the Classes Tab is the class tree portlet. This means that whenever the user selects a class in the class tree portlet, that selection is propagated to the other portlets in the tab, so that they can update their display.

WebProtege also has a global selection model. If the selection has changed in the controlling portlet of a tab, this selection will be also propagated to the other tabs. E.g., if your Classes Tab currently displays the class Pizza, and you switch to the Individuals tab, this will also display the class Pizza and its individuals.

The controlling portlet is marked with an antenna icon in the titlebar of the portlet.

The controlling portlet can be set:

  • in the user interface, by clicking on the Configure icon in the titlebar of the portlet.
  • in the code, by calling on the portlet instance: setAsControllingPortlet(), or by calling on a tab instance: setControllingPortlet(final EntityPortlet newControllingPortlet).


Creating your own WebProtege tab or portlet

Before you start, please take a look at the page describing how the WebProtege user interface is configured using the XML configuration file. You may also read the page on how to configure the forms in WebProtege, if you are interested in creating a form widget.


Create a tab

If you are interested in creating a generic tab that is just a dummy container for some (useful) portlets, then there is no need to create any new code. Just add to the project configuration file a

 edu.stanford.bmir.protege.web.client.ui.tab.UserDefinedTab

and add whatever portlets you need in it (in the XML configuration file). Don't forget to specify the controlling portlet! This is the most common case. Read more about how to configure the tab in the XML file here.


If however, you would like to add some communication logic between the portlets in the tab (e.g. look at the implementation of the IndividualsTab), or your tab is custom in any other way, then you can implement your own tab as following:

1. Create a subclass of edu.stanford.bmir.protege.web.client.ui.tab.AbstractTab. You will need to implement at least one of the constructors, most likely the public MyTab(final Project project) which will call the super constructor.

2. To customize the tab, override the public void setup() method. Make sure that you call the super.setup() that builds the actual UI (adds portlets, etc.), otherwise, there will be nothing to show in your tab. If you want to access the portlets that you have added in your tab in the XML configuration file, you can call:

 myPortlet = (MyPortlet) getPortletByClassName(MyPortlet.class.getName());

A good example on how to create your own WebProtege tab is the IndividualsTab.

3. You need to add your tab to the edu.stanford.bmir.protege.web.client.ui.generated.UIFactory. Edit the method createTab and add the constructor of your own tab as a else case, just like the others. If you want your tab to show up in the toolbar menu "Add tab", then you also need to add your tab to the getAvailableTabNames, but this is optional.

Note: We plan to automate the generation of the UIFactory class, but until then, please edit it manually.


Create a portlet

Portlet are usually used to show some content of the selected entity. E.g. the ChangesPortlet shows the change history of a particular entity (that is selected in the controlling portlet of the tab). So, the portlet has a current entity. But, if your porlet is not related to an entity, then you can just ignore all the entity methods.

The interface for all portlets is the EntityPortlet. All methods in this interface are documented and should be self-explanatory.

Here are some of the main methods to implement:

1. Create a subclass of edu.stanford.bmir.protege.web.client.ui.portlet.AbstractEntityPortlet. You will need to implement at least one of the constructors, usually the MyPortlet(project project). Don't forget to call the super(project).

2. Implement the initialize() method that is called to build the user interface of the portlet.

3. Implement the reload method, which is called when the user has clicked on the Reload icon in the titlebar of your portlet, or if the selection of the controlling portlet has changed, and your portlet has now a new entity to display. Call the getEntity method to find out which entity you need to display now.

Usually you don't need to override the getEntity method, which returns the current displayed entity, or the setEntity, which is called when the selection in the controlling portlet has changed, or some other piece of code calls explicitly this method (usually it is enough if you just override reload).

Other methods, such as onLogin, onLogout or onPermissionsChanged are called on the obvious events, and you may override them, if your portlet needs to take some action as a result of these events.

4. You need to add your portlet to the edu.stanford.bmir.protege.web.client.ui.generated.UIFactory. Edit the method createPortlet and add the constructor of your own portlet as a else case, just like the others. If you want your portlet to show up in the toolbar menu "Add content to this tab", then you also need to add your tab to the getAvailablePortletNames, but this is optional.

Note: We plan to automate the generation of the UIFactory class, but until then, please edit it manually.

An example of a portlet is the BioPortalSearchPortlet.


Troubleshooting

In case the project configuration does not load, it may be that:

(1): there is an error in the XML configuration of the project, then you will likely see an xstream error in the server logs, which also indicates the line in XML file with the error; or

(2): your portlet or tab could was not compiled, if you used your own package name (the ones in edu.stanford.bmir.protege.web.client.* are automatically included). If you use your own package name, your portlet/tab needs to be in its own module, and your module needs to inherit the webprotege module (thank you to Karl Hammar for this contribution!). See the GWT documentation on inheriting modules.


Go to main WebProtege Developer's Guide

Go to to main WebProtégé page

Personal tools