PhenoTips » Developer Guide » User Interface extensions: creating your own widgets

User Interface extensions: creating your own widgets

User Interface extensions: creating your own widgets

XWiki's User interface extension module and Skin extension Plugin (see also the tutorial) provide excellent support for custom widgets to be developed and inserted at various points in the user interface. The user interface extension code should be written in one of the supported scripting languages, and can access the platform's APIs. Please consult these resources before attempting to develop a UI widget for PhenoTips.

How to write a UI widget for PhenoTips

We have simplified the process for creating PhenoTips widgets using XWiki's extension support by providing a widget creation form and template. 

Create the widget

Widget developers (who should be both administrators and advanced users of the system) will have access to the administration section called UIX under the PhenoTips administration category. In this section, a form is displayed for creating new extensions, and all existing extensions are listed. The form prompts for an extension name and generates an extension document where the developer can write the widget's code using a supported scripting language. Among these, Velocity is recommended, for simplicity.

The extension has the org.phenotips.patientSheet.section.none extension point by default, which means it will be listed in the Patient form structure administration section and can be dragged and dropped to any section of the patient form for activation. You may change the extension point by choosing any of the available ones (please see the list of extension points below).

Make it pretty: add CSS

The generated extension document comes with a text box for CSS to be applied to the widget. Note that the widget will already inherit all the styling active in the pages where it is inserted. To use additional styling, write the CSS code in the dedicated box and activate it by inserting the following line in a {{velocity}} block in the widget code:

$xwiki.ssx.use("PhenoTips.<Name of the extension page>")

For advanced usage of stylesheet extensions, please read the tutorial.

Make it interactive: add JavaScript

Another box is provided with the extension for JavaScript code that should be used by the widget. Several libraries are bundled with the platform and can be used in the code. To use additional scripts, write the JavaScript code in the dedicated box and activate it by inserting the following line in a {{velocity}} block in the widget code:

$xwiki.jsx.use("PhenoTips.<Name of the extension page>")

For advanced usage of JavaScript extensions, please read the tutorial.

List of available extension points

In the patient form

org.phenotips.patientSheet.before
Extensions plugged into the patient form before the content of the actual form. An example of such an extension that is provided by default is the "Access rights management" widget displayed on the top right of the page, between the title and the first section.
org.phenotips.patientSheet.after
Extensions plugged into the patient form after the content of the actual form.
org.phenotips.patientSheet.content

The extensions that plug into this extension point are in fact sections in the patient form (e.g. "Patient information", "Measurements", etc). This extension point ignores the extension's content and requires the extension to present the following parameters:

  • title: the section's title
  • enabled: true|false, defaults to true; disabled sections do not show up in the form
  • order: where in the form will this section be displayed

It is recommended to use the Administration interface for form structure to define and manage sections. When creating a new section from the administration interface, it will automatically generate a new extension point org.phenotips.patientSheet.section.<identifier-of-your-new-section>, where other extensions can be plugged in.

A number of sections are predefined in the system and generate their own extension points, listed below.

  • org.phenotips.patientSheet.section.patient-info
  • org.phenotips.patientSheet.section.family-info
  • org.phenotips.patientSheet.section.prenatal-info
  • org.phenotips.patientSheet.section.medical-history
  • org.phenotips.patientSheet.section.measurement-info
  • org.phenotips.patientSheet.section.phenotype-info
  • org.phenotips.patientSheet.section.diagnosis-info
  • org.phenotips.patientSheet.section.molecular-genetics-info
  • org.phenotips.patientSheet.section.variant-info
  • org.phenotips.patientSheet.section.additional-files

The extensions plugged into these extension points must have a content which will be displayed in the form, and the parameters title, enabled, required, order defined similarly as above. Note that for these extensions, unlike for sections, the title is only displayed in the administration section, and not used in the patient form when displaying the extension.

org.phenotips.patientSheet.section.none
A special extension point used by the Administration interface for form structure to list all extensions that were prepared for display in the patient form but that were not yet assigned to a section. 

In the general UI

All the following extension points display the extension's content and ignore its parameters.

org.xwiki.platform.header.top
Extension point provided by default by the XWiki platform, for extensions to be displayed at the top of the banner. 
org.phenotips.header.top:<space name>
Extensions to be displayed at the top of the banner for a specific space. The topmost menu is an example of such an extension. If no extension is defined for a given space, the default XWiki top menu is displayed.

org.xwiki.platform.header.bottom
Extension point provided by default by the XWiki platform, for extensions to be displayed at the bottom of the banner. 
org.phenotips.header.bottom:<space name>
Extensions to be displayed at the bottom of the banner for a specific space. The toolbar with breadcrumbs, a "New patient record" tool and a "Quick patient search" widget displayed on any patient's page is an example of such an extension.

org.xwiki.platform.main.top
Extension point provided by default by the XWiki platform, for extensions to be displayed under the banner and before the content. 
org.phenotips.main.top:<space name>
Extensions to be displayed under the banner and before the content for a specific space. If no extension is defined for a given space, the default XWiki content menu is displayed.

org.xwiki.platform.content.top
Extension point provided by default by the XWiki platform, for extensions to be displayed at the top of the content zone. 
org.phenotips.content.top:<space name>
Extensions to be displayed at the top of the content zone for a specific space. The menu displayed on the right side of the patient form is an example of such an extension. If no extension is defined for a given space, the default XWiki breadcrumbs are displayed.

You can add your own extension points

Your UIExtension can define its own extension points, where other extensions can plug in. Here is an example of velocity code to include in your extension in order to make it an entry point for others:

{{velocity}}
#foreach ($extension in $services.uix.getExtensions("my.new.extension.point"))
 #if ($extension.getParameters().get('parameter_name') == 'expected_value')

 {{html clean=false}}$services.rendering.render($e.execute(), 'xhtml/1.0'){{/html}}
 #end
#end
{{/velocity}}