Revision as of 15:57, June 15, 2010

WebProtege Layout Configuration

Page still under construction!

The WebProtege layout

The layout of WebProtege is configurable, and it can be easily adapted to different project requirements. The user interface layout is specified declaratively in a XML file. The layout can also be made specific for a project, or specific to a project and user.

The WebProtege user interface layout is composed of tabs, e.g. Classes Tab, Individuals Tab, Change History Tab, Notes and Discussions tab, etc.

Each tab can contain several portlets that are grouped in a column layout and make up the tab layout. For example, the Classes Tab shows on the first column a Class Tree portlet, and in the second column shows a properties portlet, a restriction portlet and a notes portlet.

Adding new tabs and portlets from the user interface

To add a predefined tab in the user interface, use the Add tab menu in the ontology toolbar (top right corner). To add portlets to a tab, use the menu Add content to this tab menu in the toolbar.

Note. It is possible to store the configuration by clicking on a Save Layout button, but in the current WebProtege release it is disabled. We will restore the functionality in one of the next WebProtege releases.

Pre-configuring the WebProtege layout

The configuration of the WebProtege layout is declarative through a XML file. The default configuration xml file is located in war/projectConfigurations/configuration.xml. The XML file contains spells out the layout of a project in terms of tabs and portlets. The example for the layout of the configuration of the Classes Tab is shown below:

<tab>
    <name>edu.stanford.bmir.protege.web.client.ui.ontology.classes.ClassesTab</name>
    <label>Classes</label>
    <columns>
      <column>      
        <width>0.33</width>
        <portlets>
          <portlet>
            <name>edu.stanford.bmir.protege.web.client.ui.ontology.classes.ClassTreePortlet</name>
            <height>600</height>
            <width>200</width>
          </portlet>
        </portlets>
      </column>
      <column>
        <width>0.66</width>
        <portlets>
          <portlet>
            <name>edu.stanford.bmir.protege.web.client.ui.ontology.notes.NotesPortlet</name>
            <height>0</height>
            <width>0</width>
          </portlet>
          <portlet>
            <name>edu.stanford.bmir.protege.web.client.ui.ontology.restrictions.RestrictionsPortlet</name>
            <height>0</height>
            <width>0</width>
          </portlet>
          <portlet>
            <name>edu.stanford.bmir.protege.web.client.ui.ontology.classes.AllPropertiesPortlet</name>
            <height>200</height>
            <width>0</width>
          </portlet>
        </portlets>
      </column>
    </columns>
    <controllingPortlet reference="../columns/column/portlets/portlet"/>
  </tab>

A tab is split into columns. The Classes Tab is split into two columns: the class tree column spans 33% of the layout, and the other column spans 66%.

Each tab should have a controlling portlet. The controlling portlet sets the selection for the rest of the portlets in a tab. For example, in the Classes Tab, the controlling portlet is the class tree portlet. This means that whenever the user selects a class in the class tree, that selection is transmitted to the other portlets in the tab to update their display.

The template of a project configuration XML file is:

<project>
<tabs>
  <tab>
    <name>my.tab.class.name</name>
    <label>My tab label</label>
    <columns>
      <column>
        <portlets>
          <portlet>
            <name>my.portlet.class.name</name>
             ... (other portlet properties)
          </portlet>
            .... (other portlets)        
        </portlets>
      </column>
       ... (other columns)
    </columns>
    <controllingPortlet reference="../columns/column/portlets/portlet"/>
  </tab>
   ... (other tabs)
  </tabs>  
</project>

If you want to create a custom configuration.xml file, it is a good idea to start from an existing one (e.g. the default configuration in the WebProtege distribution) and adapt it.

The project, tabs and portlets can also have any number of properties associated to them. The properties are of the form: key:value where key is any string and value can be many things (string, boolean, integer, maps, lists, etc.). The properties are defined in a properties tag:

<properties>
   <entry>
      <string>label</string>
      <string>My Classes</string>
   </entry>
</properties>

Adding your own tab or portlet in the configuration file

It is quite straightforward to add a pre-existing tab or portlet to the XML configuration file. First, find the class name of the tab or portlet that you want to add (the list at the end of this wiki page should help), and then insert the <tab> or <portlet> structure in the appropriate place in the configuration file.

For example, to add the change history portlet to a tab, insert the following lines in the configuration file:

<portlet>
  <name>edu.stanford.bmir.protege.web.client.ui.ontology.changes.ChangeSummaryPortlet</name>
  <height>600</height>
</portlet>

Sometimes, you would like to aggregate some portlets in a dummy tab. This corresponds in the user interface to the Add tab -> Add your own tab menu. To create a custom tab, you can just add in the XML configuration file a edu.stanford.bmir.protege.web.client.ui.tab.UserDefinedTab and add whatever portlets you need in it. Don't forget to specify the controlling portlet!

Project and user - specific configurations

It is possible to define a project and a project and user specific layout configuration.

The default layout configuration for any project in WebProtege is given by the war/projectConfigurations/configuration.xml file.

If you want to define a custom layout for one of the projects in WebProtege, then add a new configuration XML file in the same directory as the default one, and name it:

configuration_MyProjectName.xml

For example, if you want to create a specific configuration file for the project Collaborative Pizza (the name of the project is defined in the metaproject), then you would create a file: configuration_Collaborative Pizza.xml that contains the custom layout (e.g. you hide some tabs, add new portlets, etc.)

If you want to create a specific configuration for a user and a project (the user and project name are defined in the metaproject), then create a new configuration file and call it:

configuration_MyProjectName_UserName.xml

For example, to define a custom layout for Collaborative Pizza for user Guest, then create a configuration file called: configuration_Collaborative Pizza_Guest.xml

Note: When the Save Layout function will be enabled in WebProtege, it will be much easier to create these configurations directly from the UI, rather than editing the XML file.

Additional configurations

Hide the ontology toolbar

This is useful, if you don't want users to change the layout (e.g., add tabs or portles). Add for the <project> the following property:

<properties>
  <entry>
      <string>showOntologyToolbar</string>
      <boolean>false</boolean>  </entry>
  <!-- (other properties...) -->
</properties>

Default is to show the ontology toolbar.

Make the tabs not closable

Tabs have by default a close icon (the little X icon in the tab title). If you want to make a tab un-closable, add to the tab the following property:

<properties>
  <entry>
      <string>closable</string>
      <boolean>false</boolean>
  <!-- (other properties...) -->
</properties>

Show only a branch in the class tree

If you want to restrict the class tree the one branch, add in the Class Tree portlet the following property:

<properties>
  <entry>
    <string>topClass</string>
    <string>http://who.int/icd#ICDCategory</string>  <!-- (add the full name of the top level class) -->
  </entry>
  <!-- (other properties...) -->
</properties>

Show the individuals of a predefined class in a portlet

Sometimes it is useful to browse the individuals of a predefined class. For the Individual List portlet, add the following property:

<properties>
  <entry>
    <string>showOnlyClass</string>
    <string>http://pizza.edu#Country</string>  <!-- (add the full name of the class) -->
  </entry>
  <!-- (other properties...) -->
</properties>

Note. Other properties are available, and we are in the process of documenting them.