https://protegewiki.stanford.edu/api.php?action=feedcontributions&user=Han&feedformat=atomProtege Wiki - User contributions [en]2024-03-29T05:29:22ZUser contributionsMediaWiki 1.27.7https://protegewiki.stanford.edu/index.php?title=PropertyFormPortlet&diff=10161PropertyFormPortlet2011-06-24T13:47:42Z<p>Han: </p>
<hr />
<div><p style="padding:0; margin:0; font-size:1.9em; font-weight:bold; word-spacing:-2px;">Form Based Editing in WebProtege</p><br />
<br />
<br />
__TOC__<br />
<br />
'''Learn more about how the layout configuration works in WebProtege by following this [[WebProtegeLayoutConfig|tutorial]]'''.<br />
<br />
= Examples of form editing widgets =<br />
<br />
The <code>PropertyFieldPortlet</code> (<code>edu.stanford.bmir.protege.web.client.ui.portlet.propertyForm.PropertyFieldPortlet</code>) supports the '''form-based editing''' in WebProtege. The portlet allows the association of a property with an editing widget. There are different types of editing widgets: text field, text area, check box, radio box, combo box, html, instance table, etc. This feature is similar to the form-based editing support in Protege 3.x. The editing widgets can be organized in tabs. <br />
<br />
An example of the ''PropertyFieldPortlet'' is shown below:<br />
<br />
[[File:PropertyFormPortlet.png]]<br />
<br />
The example shows the tab structure of the portlet. There are examples of a '''instance textfield''' widget (ICD title), '''text fields''' (code, sorting label), '''instance table''' (definition and external definition) and '''drop-down list''' (editorial status). <br />
<br />
Other examples of editing widgets ('''check box''', '''radio box''', '''combo box''', '''BioPortal reference widget''') are shown in the figure below:<br />
<br />
[[File:Editingwidgets.png]]<br />
<br />
= Types of property editing widgets =<br />
<br />
One or more property editing widgets can be added to a ''PropertyFormPortlet''. The types of widgets are enumerated below:<br />
<br />
* '''textfield''' - editing of string values in a text field<br />
* '''textarea''' - editing of string values in a text area<br />
* '''combobox''' - editing of simple or instance values using a drop-down list<br />
* '''htmleditor''' - editing of string values using an HTML editor<br />
* '''multitextfield''' - editing of string multi-values (for properties with multiple cardinality)<br />
<br />
* '''htmlMessage''' - embed some HTML text or an external HTML into the portlet<br />
* '''classselect''' - widget to set a class as the value of a property. Class is selected from a class tree<br />
* '''propertyselect''' - widget to select a property using a property tree<br />
* '''externalreference''' - widget to create a reference to an external ontology or terminology stored in BioPortal<br />
<br />
Instance widgets (useful for reified instances):<br />
* '''instancetextfield''' - if the the property value is an instance, shows in a text field one of the properties of the value instance<br />
* '''instancecheckbox''' - show as checkboxes an instance value set (multiple cardinality)<br />
* '''instanceradiobutton''' - show as radio box an instance value set (single cardinality)<br />
* '''grid''' - shows an instance table widget similar to the rich client (single or multiple cardinality)<br />
<br />
'''Note.''' The list of available widgets will be extended as needed. The name of the widgets might also change in future releases.<br />
<br />
<br />
= Configuration of the property editing widgets =<br />
<br />
Unfortunately the only way to configure the widgets in a ''PropertyFieldPortlet'' is to edit the [[WebProtegeLayoutConfig|layout configuration XML file]]. We are working on creating a user interface that would simplify the configuration process. Until then, please bear with us.<br />
<br />
Each widget has [http://protegewiki.stanford.edu/wiki/WebProtegeLayoutConfig#Pre-configuring_the_WebProtege_layout properties] associated to it in form of <code>key:value</code> pairs that control the configuration of the widget.<br />
<br />
Below is an example of configuring the ''PropertyFieldPortlet'' to display for the ''rdfs:label'' a ''multitextfield'' widget and for the ''rdfs:comment'' uses a ''textarea'' widget.<br />
<br />
<pre><br />
<portlet><br />
<name>edu.stanford.bmir.protege.web.client.ui.portlet.propertyForm.PropertyFieldPortlet</name><br />
<height>200</height><br />
<width>0</width><br />
<properties><br />
<entry><br />
<string>tabs</string><br />
<list><br />
<map><br />
<entry><br />
<string>title</string><br />
<string>Metadata</string><br />
</entry> <br />
<entry><br />
<string>http://www.w3.org/2000/01/rdf-schema#label</string><br />
<map><br />
<entry><br />
<string>name</string><br />
<string>http://www.w3.org/2000/01/rdf-schema#label</string><br />
</entry><br />
<entry><br />
<string>label</string><br />
<string>Label</string><br />
</entry><br />
<entry><br />
<string>component_type</string><br />
<string>multitextfield</string><br />
</entry><br />
<entry><br />
<string>index</string><br />
<string>0</string><br />
</entry><br />
</map><br />
</entry><br />
<entry><br />
<string>http://www.w3.org/2000/01/rdf-schema#comment</string><br />
<map><br />
<entry><br />
<string>name</string><br />
<string>http://www.w3.org/2000/01/rdf-schema#comment</string><br />
</entry><br />
<entry><br />
<string>label</string><br />
<string>Comment</string><br />
</entry><br />
<entry><br />
<string>component_type</string><br />
<string>textarea</string><br />
</entry><br />
<entry><br />
<string>index</string><br />
<string>1</string><br />
</entry><br />
</map><br />
</entry> <br />
</map> <br />
</list><br />
</entry><br />
</properties><br />
</portlet><br />
</pre><br />
<br />
<br />
The '''component_type''' is one of the types specified in the section above. The first entry in the property of the tabs (E.g. <code><nowiki><string>http://www.w3.org/2000/01/rdf-schema#label</string><br />
</nowiki></code>) is the property name to which the widget is associated. The '''name''' property must point to a unique name for the widget. The '''label''' property sets the display label in front of the widget. '''index''' specifies on what position in the tab should the widget be placed (0 - top, 1- below 0, etc.).<br />
<br />
Different widgets have additional supported properties. Some of them support the '''read_only''' property, which can be used to make a widget read-only (in the first figure, ICD 10 code). The ''grid'' widget (a.k.a ''Instance Table Widget'') has properties for setting the columns in the table, their width, their type, etc.<br />
<br />
More documentation about the properties of the widgets will be added as requested by the users.<br />
<br />
<br />
= Examples =<br />
<br />
The easiest way to create the XML configuration for a ''PropertyFieldPortlet'' is to start with an existing example and change it. <br />
<br />
We have some example using this portlet here:<br />
<br />
http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who/war/projectConfigurations/configuration_ICD.xml<br />
http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who/war/projectConfigurations/configuration_example_property_field_portlet.xml<br />
<br />
[[Category:WebProtege documentation]]</div>Hanhttps://protegewiki.stanford.edu/index.php?title=WebProtegeLayoutConfig&diff=10160WebProtegeLayoutConfig2011-06-24T13:47:12Z<p>Han: </p>
<hr />
<div><p style="padding:0; margin:0; font-size:1.9em; font-weight:bold; word-spacing:-2px;">WebProtege Layout Configuration</p><br />
<br />
<br />
__TOC__<br />
<br />
<br />
= The WebProtege layout =<br />
<br />
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.<br />
<br />
The WebProtege user interface layout is composed of '''tabs''', e.g. ''Classes Tab'', ''Individuals Tab'', ''Change History Tab'', ''Notes and Discussions tab'', etc.<br />
<br />
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.<br />
<br />
<br />
[[File:Webprotege_layout.png]]<br />
<br />
<br />
= Adding new tabs and portlets from the user interface =<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
<br />
= Pre-configuring the WebProtege layout =<br />
<br />
The configuration of the WebProtege layout is declarative through a XML file. The default configuration xml file is located in <code>war/projectConfigurations/configuration.xml</code>. 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:<br />
<br />
<pre><br />
<tab><br />
<name>edu.stanford.bmir.protege.web.client.ui.ontology.classes.ClassesTab</name><br />
<label>Classes</label><br />
<columns><br />
<column> <br />
<width>0.33</width><br />
<portlets><br />
<portlet><br />
<name>edu.stanford.bmir.protege.web.client.ui.ontology.classes.ClassTreePortlet</name><br />
<height>600</height><br />
<width>200</width><br />
</portlet><br />
</portlets><br />
</column><br />
<column><br />
<width>0.66</width><br />
<portlets><br />
<portlet><br />
<name>edu.stanford.bmir.protege.web.client.ui.ontology.notes.NotesPortlet</name><br />
<height>0</height><br />
<width>0</width><br />
</portlet><br />
<portlet><br />
<name>edu.stanford.bmir.protege.web.client.ui.ontology.restrictions.RestrictionsPortlet</name><br />
<height>0</height><br />
<width>0</width><br />
</portlet><br />
<portlet><br />
<name>edu.stanford.bmir.protege.web.client.ui.ontology.classes.AllPropertiesPortlet</name><br />
<height>200</height><br />
<width>0</width><br />
</portlet><br />
</portlets><br />
</column><br />
</columns><br />
<controllingPortlet reference="../columns/column/portlets/portlet"/><br />
</tab><br />
</pre><br />
<br />
<br />
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%.<br />
<br />
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.<br />
<br />
The template of a project configuration XML file is:<br />
<br />
<pre><br />
<project><br />
<tabs><br />
<tab><br />
<name>my.tab.class.name</name><br />
<label>My tab label</label><br />
<columns><br />
<column><br />
<portlets><br />
<portlet><br />
<name>my.portlet.class.name</name><br />
... (other portlet properties)<br />
</portlet><br />
.... (other portlets) <br />
</portlets><br />
</column><br />
... (other columns)<br />
</columns><br />
<controllingPortlet reference="../columns/column/portlets/portlet"/><br />
</tab><br />
... (other tabs)<br />
</tabs> <br />
</project><br />
</pre><br />
<br />
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.<br />
<br />
The project, tabs and portlets can also have any number of properties associated to them. The properties are of the form: <code>key:value</code> where <code>key</code> is any string and <code>value</code> can be many things (string, boolean, integer, maps, lists, etc.). The properties are defined in a <code>properties</code> tag:<br />
<br />
<pre><br />
<properties><br />
<entry><br />
<string>label</string><br />
<string>My Classes</string><br />
</entry><br />
</properties><br />
</pre><br />
<br />
<br />
= Adding your own tab or portlet in the configuration file =<br />
<br />
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.<br />
<br />
For example, to add the change history portlet to a tab, insert the following lines in the configuration file:<br />
<br />
<pre><br />
<portlet><br />
<name>edu.stanford.bmir.protege.web.client.ui.ontology.changes.ChangeSummaryPortlet</name><br />
<height>600</height><br />
</portlet><br />
</pre><br />
<br />
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.<br />
To create a custom tab, you can just add in the XML configuration file a <code>edu.stanford.bmir.protege.web.client.ui.tab.UserDefinedTab</code> and add whatever portlets you need in it. Don't forget to specify the controlling portlet!<br />
<br />
<br />
= Project and user - specific configurations =<br />
<br />
It is possible to define a ''project'' and a ''project and user'' specific layout configuration. <br />
<br />
The default layout configuration for any project in WebProtege is given by the <code>war/projectConfigurations/configuration.xml</code> file.<br />
<br />
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:<br />
<br />
configuration_MyProjectName.xml<br />
<br />
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: <code>configuration_Collaborative Pizza.xml</code> that contains the custom layout (e.g. you hide some tabs, add new portlets, etc.)<br />
<br />
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:<br />
<br />
configuration_MyProjectName_UserName.xml<br />
<br />
For example, to define a custom layout for ''Collaborative Pizza'' for user ''Guest'', then create a configuration file called: <code>configuration_Collaborative Pizza_Guest.xml</code><br />
<br />
'''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.<br />
<br />
<br />
= Form-based editing =<br />
<br />
The [[PropertyFormPortlet]] supports the form-based editing of property values, similar to the forms available in Protege 3.x. This feature allows the configuration of the UI for domain experts.<br />
The form-based editing is documented [[PropertyFormPortlet|here]].<br />
<br />
<br />
= Additional configurations =<br />
<br />
== Hide the ontology toolbar ==<br />
<br />
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:<br />
<br />
<pre><br />
<properties><br />
<entry><br />
<string>showOntologyToolbar</string><br />
<boolean>false</boolean><br />
</entry><br />
<!-- (other properties...) --><br />
</properties><br />
</pre><br />
<br />
Default is to show the ontology toolbar.<br />
<br />
== Make the tabs not closable ==<br />
<br />
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:<br />
<br />
<pre><br />
<properties><br />
<entry><br />
<string>closable</string><br />
<boolean>false</boolean><br />
</entry><br />
<!-- (other properties...) --><br />
</properties><br />
</pre><br />
<br />
== Show only a branch in the class tree ==<br />
<br />
If you want to restrict the class tree the one branch, add in the ''Class Tree portlet'' the following property:<br />
<br />
<pre><br />
<properties><br />
<entry><br />
<string>topClass</string><br />
<string>http://who.int/icd#ICDCategory</string> <!-- (add the full name of the top level class) --><br />
</entry><br />
<!-- (other properties...) --><br />
</properties><br />
</pre><br />
<br />
== Show the individuals of a predefined class in a portlet ==<br />
<br />
Sometimes it is useful to browse the individuals of a predefined class. For the Individual List portlet, add the following property:<br />
<br />
<pre><br />
<properties><br />
<entry><br />
<string>showOnlyClass</string><br />
<string>http://pizza.edu#Country</string> <!-- (add the full name of the class) --><br />
</entry><br />
<!-- (other properties...) --><br />
</properties><br />
</pre><br />
<br />
<br />
'''Note'''. Other properties are available, and we are in the process of documenting them.<br />
<br />
<br />
= Available tabs and portlets =<br />
<br />
To add a tab or a portlet in the configuration file, you need to know their full Java class name.<br />
<br />
Below is a list as of June, 15, 2010.<br />
<br />
== Tabs ==<br />
<br />
<pre><br />
edu.stanford.bmir.protege.web.client.ui.ontology.classes.ClassesTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.properties.PropertiesTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.individuals.IndividualsTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.hierarchy.ManageHierarchyTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.metadata.MetadataTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.notes.NotesTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.notes.OntologyNotesTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.reviews.ReviewsTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.changeanalysis.ChangeAnalysisTab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.search.OtherTerminologiesTab<br />
edu.stanford.bmir.protege.web.client.ui.tab.UserDefinedTab<br />
</pre><br />
<br />
== Portlets ==<br />
<br />
<pre><br />
-- Classes --<br />
edu.stanford.bmir.protege.web.client.ui.ontology.classes.ClassTreePortlet - shows the class tree<br />
edu.stanford.bmir.protege.web.client.ui.ontology.hierarchy.ManageHierarchyPortlet - manage hierarchy operations: move in hierarchy, add/remove parents, retire<br />
edu.stanford.bmir.protege.web.client.ui.ontology.restrictions.RestrictionsPortlet - shows the class conditions and restrictions<br />
edu.stanford.bmir.protege.web.client.ui.ontology.classes.SuperclassesPortlet - shows the direct parents of a class<br />
<br />
-- Properties --<br />
edu.stanford.bmir.protege.web.client.ui.ontology.properties.PropertiesTreePortlet - the property tree<br />
edu.stanford.bmir.protege.web.client.ui.ontology.classes.AllPropertiesPortlet - shows the annotation properties (and own slots in frames), and other properties attached to the selected entity<br />
edu.stanford.bmir.protege.web.client.ui.ontology.classes.PropertiesViewPortlet - shows the classes that are in the domain of the selected class (similar to the rich client)<br />
edu.stanford.bmir.protege.web.client.ui.portlet.propertyForm.PropertyFieldPortlet - form-based editing; see additional page for documentation<br />
<br />
-- Individuals --<br />
edu.stanford.bmir.protege.web.client.ui.ontology.individuals.IndividualsListPortlet - shows the list of individuals of a class<br />
<br />
-- Changes --<br />
edu.stanford.bmir.protege.web.client.ui.ontology.changes.ChangesPortlet - shows the list of changes for the selected entity<br />
edu.stanford.bmir.protege.web.client.ui.ontology.changes.ChangeSummaryPortlet - shows the list of all changes in the ontology<br />
edu.stanford.bmir.protege.web.client.ui.ontology.changeanalysis.ChangeTreePortlet - shows the class tree with the number of changes attached to each node<br />
edu.stanford.bmir.protege.web.client.ui.ontology.changeanalysis.ChangeTablePortlet - shows the changes of the selected entity and supports filtering of authors<br />
<br />
<br />
<br />
-- Notes and discussions --<br />
edu.stanford.bmir.protege.web.client.ui.ontology.notes.NotesPortlet - shows in a table format all notes attached to the selected entity (deprecated by the NotesTreePortlet)<br />
edu.stanford.bmir.protege.web.client.ui.ontology.notes.NotesTreePortlet - shows in a threaded view the notes attached to the selected entity<br />
edu.stanford.bmir.protege.web.client.ui.ontology.reviews.ReviewsPortlet - request and add reviews to an entity<br />
<br />
-- Metadata --<br />
edu.stanford.bmir.protege.web.client.ui.ontology.metadata.ImportsTreePortlet - shows the ontology imports tree<br />
edu.stanford.bmir.protege.web.client.ui.ontology.metadata.AnnotationsPortlet - shows the ontology annotations<br />
edu.stanford.bmir.protege.web.client.ui.ontology.metadata.MetricsPortlet - shows the metrics of an ontology (expensive operation)<br />
edu.stanford.bmir.protege.web.client.ui.ontology.home.OntologiesPortlet - shows the list of available ontologies<br />
<br />
-- Other --<br />
edu.stanford.bmir.protege.web.client.ui.portlet.html.HtmlMessagePortlet - allows the embedding of any HTML in the UI of a tab<br />
edu.stanford.bmir.protege.web.client.ui.ontology.search.BioPortalSearchPortlet - supports searches in BioPortal<br />
edu.stanford.bmir.protege.web.client.ui.ontology.changes.WatchedEntitiesPortlet - watch entities and get email notifications on changes<br />
<br />
</pre><br />
<br />
= Examples =<br />
<br />
You can find examples of XML configuration files here:<br />
<br />
http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who/war/projectConfigurations/<br />
<br />
[[Category:WebProtege documentation]]</div>Han