Skip to main content

Widget plugin

A widget plugin is a type of plugin that allows you to create custom display elements for use in a page or view. You can use a widget plugin to display data from a case or dataset in a chart, on a map, or in any other format where you want to support some kind of user interaction.

You create a widget plugin by writing your own JavaScript, HTML, and CSS. For Grexx Platform developers with sufficient experience of high-code web development, using a widget plugin provides high levels of flexibility. However, adding custom code to your application also comes with the risk of unintended consequences - including pages that no longer load, performance issues, and data loss. For these reasons, we do not recommend creating your own widget plugins if you do not already have a good understanding of JavaScript, HTML, and CSS.

Tip:

If you do not want to create your own widget plugin, you can import ready-made plugins from Grexx Marketplace. You can also use template and tile widgets to create simple custom display elements using HTML, CSS, and standard template functions.

Interact with your application​

To interact with your application from your widget plugin, use the Grexx Platform JavaScript library. For example, you can use the JavaScript library to:

  • Fetch rows from a dataset.
  • Load a saved template.
  • Display an activity form (in a modal dialog).
  • Upload a file.
  • Submit an activity.

To view the Grexx Platform JavaScript library documentation, append docs/api/js to the URL of any of your application environments. For example, https://my-site-dev.grexx.today/docs/api/js

The API considers all of the following to be equal, so ensure your code supports this:

  • []
  • [{}]
  • [{"A":{}}]
  • null

Restrictions​

Other ways of calling Grexx functions should not be used. This includes using the parent and window\.gx variables, making your own ajax or websocket calls, and any other method that is not part of the API described above.

Grexx Platform's content security policy means it is not possible to:

  • Use inline styles, such as <span style="color:blue;">blue?</span>.
  • Use inline JavaScript, such as <span onclick="setColorToBlue()">blue?</span>.
  • Retrieve data, requests, styles, scripts, fonts, or images from a source other than the current domain.
  • Use eval() or new Function() to run "dynamic" JavaScript.

For security reasons, the following thread-blocking components are not permitted in widget plugins:

  • prompt
  • alert
  • confirm

Libraries​

To use JQuery and other libraries in your widget plugin:

  • Add the library to your Studio from Plugins & Libraries > Frontend libraries. Add the direct CDN link to the JavaScript files and/or CSS files fields.
  • When you create or edit the widget plugin, select the relevant libraries from the pluginLibrary picklist.

If an external library does not work with CORS (cross-origin resource sharing), edit the library in your Studio and enable the Disable CORS option.