SWP Gadgets Reference

SWA Gadgets Reference

Version 0.9.0

SWA defines a number of reusable UI gadgets as listed in the index below.

Index

 

swa:ClassPropertyTreeGadget
A gadget displaying a mixed class/property tree. The tree can publish events whenever the user selects a class or property.
Arguments
  • arg:classSelectedEvent(xsd:string): The name of the event to publish when the selected class has changed.
  • arg:editable(xsd:boolean): [Optional] True to have buttons to create classes and properties appear under the tree.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceSelectedEvent(xsd:string): The name of the event to fire if the selected class has changed, but for gadgets that display instances.
  • arg:rootClass(rdfs:Class): The root class of the tree.
  • arg:treeId(xsd:string): [Optional] The (optional) id of the tree, in case someone needs to access it programmatically.

 

swa:ClassTreeGadget
A gadget displaying a class tree. The tree can publish events whenever the user selects a class.
Arguments
  • arg:classSelectedEvent(xsd:string): The name of the event to publish when the selected class has changed.
  • arg:classTreeDataProvider(swa:TreeDataProvider): An optional data provider for the class tree. If not specified, it will use swa:ClassTreeDataProvider.
  • arg:editable(xsd:boolean): [Optional] True to have a button to create classes appear under the tree.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:refreshEvent(xsd:string): [Optional] The name of an event that causes the tree to refresh itself.
  • arg:resourceSelectedEvent(xsd:string): The name of the event to fire if the selected class has changed, but for gadgets that display instances.
  • arg:rootClass(rdfs:Class): The root class of the tree.
  • arg:treeId(xsd:string): [Optional] The (optional) id of the tree, in case someone needs to access it programmatically.
  • arg:uiElementId(xsd:string): [Optional] HTML element ID for a containing element

 

swa:FacetedSearchGadget
Presents a free-text search field as well as a list of properties that can be used to drive faceted search.
Arguments
  • arg:classSelectedEvent(xsd:string): [Optional] The name of an event that shall control which class is displayed as root class.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceType(rdfs:Class): The class to search instances of.
  • arg:searchEvent(xsd:string): [Optional] The name of an event that shall be posted when the search has been updated. This can be used to link this with a results gadget. The data payload of these events will is the URI of a session graph that holds the search:Search object to run – there can only be one such instance in that graph.

 

swa:FormSearchGadget
A form-based search gadget that provides input widgets for search filters (facet values).

Implementation note: The gadget creates a session graph at start-up and reuses that graph for the duration of its existence. Whenever the user clicks the search button, the content of that session graph is completely replaced with a new instance of search:Search, before the search event is published.

Arguments
  • arg:classSelectedEvent(xsd:string): [Optional] The name of an event that shall control which class is displayed as root class.
  • arg:footerPlugin(swa:SearchFormFooterPlugin): [Optional] An SWP element to appear in the lower right corner.
  • arg:formId(xsd:string): [Optional] The id that shall be used for the new form. The system will generate a unique new id if left blank.
  • arg:hideGlobalSearch(xsd:boolean): [Optional] True to suppress global text search. By default a text field will appear on the top of the form, allowing users to search across all string properties of the given resources. However, this may be slow and can therefore be disabled. If the class being searched over defines swa:textSearchProperties, then the text search will only operate on those explicitly enumerated properties – even if arg:hideGlobalSearch is true.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceType(rdfs:Class): The class to search instances of.
  • arg:searchButtonHandler(xsd:string): [Optional] The name of a JavaScript function to handle the click event for the Search button.
  • arg:searchEvent(xsd:string): [Optional] The name of an event that shall be posted when the search has been updated. This can be used to link this with a results gadget. The data payload of these events will is the URI of a session graph that holds the search:Search object to run – there can only be one such instance in that graph.
  • arg:suppressActions(xsd:boolean): [Optional] If true, the drop down menu with actions will not appear.
  • arg:suppressKeyPropertiesSelection(xsd:boolean): [Optional] True to disable the check boxes for selecting the result columns.
  • arg:typeSelectable(xsd:boolean): [Optional] True to allow users to switch to the search class using a drop down box.

 

swa:GridSearchResultsGadget
A search results gadget that renders the matching resources and possibly their key properties in a grid (currently using jqGrid).
Arguments
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceSelectedEvent(xsd:string): The name of an event to publish when the user clicks on a result. The data payload of this event is the URI of the resource.
  • arg:rowNumCookie(xsd:string): [Optional] The name of a cookie remembering the number of rows.
  • arg:searchEvent(xsd:string): [Optional] The name of the event to list to when a search has been triggered. If left blank, then a default event name will be used consistently across all search views.

 

swa:InstancesGridGadget
A gadget that displays the instances of a given class (?resourceType) in a grid. The gadget has an auto-complete box under the grid.
Arguments
  • arg:classSelectedEvent(xsd:string): The name of the event to subscribe to so that the instances can be reloaded whenever the class changes.
  • arg:directInstancesOnly(xsd:boolean): [Optional] True to only display the direct instances of the class, i.e. instances of subclasses will not be displayed.
  • arg:editable(xsd:boolean): [Optional] True to have a button to create classes appear under the tree.
  • arg:instanceSelectedEvent(xsd:string): The name of the event to fire if the selected instance has changed.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceType(rdfs:Class): The class of instances to display.

 

swa:MapSearchResultsGadget
A Map that can be used to browse the results of a given search. When the user changes the bounding box (by scrolling and zooming), a new search is executed to find the matching markers. A click on a marker will publish the resource selection event.

Note: This gadget is only officially supported if the query graph is backed by a Solr index. The required range queries would be potentially too slow for a pure RDF store.

Arguments
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceSelectedEvent(xsd:string): The name of an event to publish when the user clicks on a result. The data payload of this event is the URI of the resource.
  • arg:searchEvent(xsd:string): [Optional] The name of the event to list to when a search has been triggered. If left blank, then a default event name will be used consistently across all search views.

 

swa:SearchFormGadget
Deprecated (with TopBraid 4.3): Please migrate to swa:GridSearchResultsGadget and swa:FormSearchGadget.
Arguments
  • arg:classSelectedEvent(xsd:string): The name of the event to subscribe to so that the form can be reloaded whenever the class changes.
  • arg:footerPlugin(swa:SearchFormFooterPlugin): [Optional] An SWP element to appear in the lower right corner.
  • arg:formId(xsd:string): [Optional]
  • arg:instanceSelectedEvent(xsd:string): The name of the event to fire if the user has clicked on an instance in the results grid.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceType(rdfs:Class): The class of instances being searched.
  • arg:resultsId(xsd:string): The id of the matching SearchResultsGridGadget.
  • arg:searchButtonHandler(xsd:string): [Optional] The name of a JavaScript function to handle the click event for the Search button.
  • arg:searchResultsGeneratedEvent(xsd:string): [Optional] The name of an event to fire after search results are generated for the results grid.
  • arg:typeSelectable(xsd:boolean): [Optional] True to allow users to switch to the search class using a drop down box.

 

swa:SearchResultsGridGadget
Deprecated (with TopBraid 4.3): Please migrate to swa:GridSearchResultsGadget and swa:FormSearchGadget.
Arguments
  • arg:id(xsd:string): The id of the grid – needed by the search form.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element

 

swa:SummarySearchResultsGadget
Displays the search results in a vertical arrangement of up to 10-50 resource, using their summary view.
Arguments
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resourceSelectedEvent(xsd:string): The name of an event to publish when the user clicks on a result. The data payload of this event is the URI of the resource.
  • arg:searchEvent(xsd:string): [Optional] The name of the event to list to when a search has been triggered. If left blank, then a default event name will be used consistently across all search views.

 

swa:SwitchableFormGadget
A gadget consisting of a view form that can be switched to edit mode by the user.
Arguments
  • arg:allowHistoryMode(xsd:boolean): [Optional] True to have a “Show history” check box show up in view mode. This mode is currently only supported by the teamwork framework, not general SWA.
  • arg:allowLogMessage(xsd:boolean): [Optional] True to provide an option to enter a log message when saving changes.
  • arg:editing(xsd:boolean): [Optional] True to start in editing mode.
  • arg:footerPlugin(swa:SwitchableFormFooterPlugin): [Optional] An optional component to show up in the lower right corner.
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:readOnly(xsd:boolean): [Optional] True to disallow switching to edit mode.
  • arg:resource(rdfs:Resource): The resource to display.
  • arg:resourceSelectedEvent(xsd:string): The name of the event to subscribe to so that the window can be reloaded if the resource changes. The event will also be re-published whenever the user follows a hyperlink on the form. The data payload of the event needs to be the URI of a resource.
  • arg:showResourceActions(xsd:boolean): [Optional] True to also display a button to run ResourceActions.
  • arg:showURI(xsd:boolean): [Optional] True to include the URI of the resource in the header.

 

swa:ViewFormGadget
A gadget consisting of a viewable form for a given resource. The resource can either be specified statically, or by subscribing to an event.
Arguments
  • arg:parentUIElementId(xsd:string): [Optional] HTML element ID for a containing element
  • arg:resource(rdfs:Resource): The resource to display.
  • arg:resourceSelectedEvent(xsd:string): The name of the event to subscribe to so that the window can be reloaded if the resource changes. The event will also be re-published whenever the user follows a hyperlink on the form. The data payload of the event needs to be the URI of a resource.

Gadget Interactions

A gadget should only interact with other gadgets through an event hub. SWA uses the event hub supported by the OpenSocial standard, which in turn relies on the OpenAjaxHub specification.

In a nutshell, if you want gadget A in your application to change its state wheneverthe user does something in gadget B, then gadget B should publish an event to the hub(using gadgets.Hub.publish()) and gadget A can “listen” to those events(via gadgets.Hub.subscribe()). Instead of using these JavaSctipt functions directly, you should use the same patterns employed by the pre-defined gadgets of the SWA library as illustrated by the following example (swadoc:EventsExample). 

1   <swa:FullScreenBorderLayout><swa:Window
2       arg:layoutPanel="west"
3       arg:title="Event Publisher">
4       <button onclick="{= swa:publishEvent(&quot;testEvent&quot;, &quot;'World' + Math.random()&quot;) }">Click to Send Event</button>
5     </swa:Window>
6   <swa:Window arg:layoutPanel="center"
7       arg:title="Event Subscriber">
8       <swa:Subscribe arg:code="$('#label').html(data)"
9           arg:event="testEvent"/>
10      <span>Hello&nbsp;</span>
11      <span id="label"/>
12    </swa:Window>
13  </swa:FullScreenBorderLayout>