HTML Widgets

The default SanteDB user interfaces (for SanteEMR, SanteGuard, SanteMPI, etc.) all provide UI extension points through widgets. A widget is a custom portlet which is rendered inside of another context.

For example, if you wanted to collect setup information related to your particular SanteDB based project on the initial configuration of the SanteDB software, you could create a widget to extend the configuration system rather than re-writing or forking the entire configuration system.

In order to configure a widget the following things must be present:

1. The root element must be a <div> in the http://www.w3.org/1999/xhtml namespace

2. The file must be XHTML (well formed XML)

3. The namespace http://santedb.org/applet must be declared

4. If the widget requires a custom controller, the controller must be loaded using oc-lazy-load attribute on the root element.

5. The widget must be declared with the widget element (see below for an example).

<div xmlns="http://www.w3.org/1999/xhtml" 
  xmlns:sdb="http://santedb.org/applet"
>
  <sdb:widget name="org.example.widget" type="Tab" order="10" context="org.santedb.configuration">
    <sdb:demand>1.3.6.1</sdb:demand>
    <sdb:icon>fas fa-cog</sdb:icon>
    <sdb:guard>!scopedObject.tag</sdb:guard>
    <sdb:description lang="en">Example Widget</sdb:description>
  </sdb:widget>
  <div>
    Hello {{ scopedObject.name.Legal | name }}
  </div>
</div>

Widget Configuration

The contents of the <sdb:widget/> element control the widget's rendering and visibility.

Property	Description	Example
@name	The name of the widget	org.widgets.mywidget
@type	The type of widget (tab or panel)	Tab | Panel
@order	The preferred / default order of the widget	10
@context	The widget context (where the widget is rendered)	org.santedb.configuration
@altViews	Alternate views the widget supports. These are exposed to the widget in {{panel.view}}	None - No Alternate Views Edit - Shows a pencil in widget Settings - Shows cog in widget
@priority	Used to override the default implementations of core widgets. The widget identifier with the highest priority is the one that is displayed.	priority="100"
icon	The icon for the widget	fas fa-cog
demand	The permission(s) needed to enable/view the widget.
guard	A guard condition when the widget should appear

Widget Contexts

There are several contexts in which widgets appear.

Context	Type	Description
org.santedb.config.init	Tab	Allows addition of configuration panels on initial configuration screen.
org.santedb.config	Tab	Allows addition of configuration panels to the configuration screen.
org.santedb.patient	Tab	Allows addition of a tab on the patient profile screen.
org.santedb.place	Tab	Allows addition of tabs on the place profile screen
org.santedb.user	Tab	Allows addition of tabs on the user profile screen
org.santedb.patient.demographics	Panel	One or more panels to appear in the "demographics" tab of the patient screen.
org.santedb.mdm	Panel	One or more panels to appear in the Master Data Management tab

Scoped Object

All widgets are passed a scopedObject reference in JavaScript which can be used to access the primary focal object of the context where the widget appears. For example, if your widget context is org.santedb.patient, then the scopedObject would be the patient which is currently being viewed.

Widget Controllers

Due to the manner in which widgets are loaded (at render time), the use of <sdb:script> does not work. It is therefore required to use the oc-lazy-load AngularJS component to load the controllers you require. For example, to add a custom controller:

<div xmlns="http://www.w3.org/1999/xhtml" 
  xmlns:sdb="http://santedb.org/applet"
  oc-lazy-load="{ name: 'ExampleWidgetController', files: ['/org.example/controllers/widget.js'] }"
>
  <sdb:widget name="org.example.widget" type="Tab" order="10" context="org.santedb.configuration">
    <!-- Truncated for space -->
  </sdb:widget>
  <div ng-controller="ExampleWidgetController">
  </div>
</div>

Hosting Widgets

You can add your own widget extension points by adding one of the two widget hosting panels to your user interface. The two controls are widget-panels and widget-tabs which will render panels or tabs depending on your context.

<widget-panels context-name="'my.sample.panels'" scoped-object="currentPatient"/>
<widget-tabs context-name="'my.sample.tabs'" scoped-object="currentPatient"/>