IExternalUrlEditor discovery and roles

Defining an URL editor in blueprint

URL-editors must be exported as an OSGi service with an urlEditorRole service property like follows. Multiple editors can propagate the same role. Consuming applications should therefore provide users with a selection possiblity.

 <bp:service id="sampleUrlEditorService"
             interface="org.clazzes.sketch.entities.service.IExternalUrlEditor"
             ref="sampleUrlEditor">
   <bp:service-properties>
      <bp:entry key="urlEditorRole" value="org.example.path::SampleEditor"/>
   </bp:service-properties>
 </bp:service>

Discovery of registered URL editors

All IExternalURlEditor services are registered by the ExternalUrlEditorRegistry provided by the serializable-entities bundle. All IExternalUrlEditor instances for a given urlEditorRole my be discovered by the following URL (locale information is optional)

/sketch-url-editors/org.example.path::SampleEditor?locale=de

This URL returns a JSON array in the following form:

[{"urlPrefix":"/pegelonline-data/data","editorUrl":"/pegelonline-data/donau.html","label":"Pegelonline Donau"},
 {"urlPrefix":"/tasprog/tpTimeSeries","editorUrl":"/tasprog-url-editor/","label":"TASPROG time-dependent time series"}]

Whereby urlPrefix is the leading section of all data-retrieving urls (providing JSON-streams) and editorUrl denotes an url which provides a graphical user interface in html/javascript (for usage, see below). label is a human-readable description of the editor, which may be displayed as a caption if a selection of editors is provided.

Communication between URL editor and a consuming application

A URL editor provides the user with a graphical user interface to select which data is to be provided as a JSON-stream by the data-URL. The editor is conceived as a standalone application hosted under a different url to the consuming application, which should embed the editor using an IFRAME. The components communicate via fields and events in an invisible form embedded in the URL editor's html (org.clazzes.gwt.extras.iframe.ForeignForm).

To ensure the communication to work, the consuming application must know the id of the form and fields used by the URL editor to transmit information, and implement SubmitHandler to catch the form's submit-events. It can then call the getValue(String) or setValue(String,String) methods to exchange data with the editor.

Known URL editor roles