How to create your own Velocity Widget

---

Polarion offers the possibility to create your own widgets that you can add in any LiveReport pages of your project. They enable you to report or show exactly the information which is needed in your project. In this post I will explain the basics of velocity widget development and an example of how you could create them.

I will go trough the following topics:

1. Available „programming“ languages and variables
2. Technical limitations
3. Velocity widget structure
4. Example

Available technolgies and variables

So first of all: which technologies and variables can I use to create a „velocity“ widget?

• Velocity
  … obviously. It’s a rather unknown scripting language with not that many functions. But it’s used to execute the server-side stuff like logics and accessing the API. Find all important information about it here: https://polarion.code.blog/2020/06/09/basics-teil-1-velocity/
• HTML
  As Polarion is a web application, we need to render the information with html.
• CSS
  And if we can use HTML, we can also use CSS to make the things look nice. But pay attention: Classes like „h2“ inherit the CSS of Polarion by default. So you have to create your own classes, if you want to use your own styles.
• Javascript
  And we can also use JS and also JQuery by default, to add a nice interactive user interface.
• Variables
  To access the internal API, we have standard variables available in velocity widgets.
  There are a few of it and they are described in the official Polarion SDK documents. I already described the „entry points“ in more depth in the „Rendering vs OpenAPI“ post: https://polarion.code.blog/2020/06/16/rendering-vs-open-api/

Technical limitations

Velocity widgets offer a great and fast way to implement widgets, that show specific data, diagramms etc. . What they can’t do, is editing data in Polarion. Therefore you would need an additional „Servlet“ (a java based extension on the server, that executes the editing) or you would have to create a Java widget in the first place.

So don’t wonder that your velocity widgets in live report pages won’t execute „writing“ methods of Polarion API classes.

Note: If you insist on creating a „writing“ velocity widget, you can still use the classic wiki pages, where the writing methods are available. But I wouldn’t recommend doing so, as it restricts your possibilities. Also I recommend to go for Java widgets/servlets, as you can debug them properly.
(It’s also possible to just write a kind of servlet in a classic wiki page and reference to it from your LiveReport pages).

Velocity widget structure

Velocity widgets can be deployed in the repository project- or server-wide in the folder ../.polarion/pages/widgets/.

A widget consists of a folder containing the following files:

• (resources) – Optional. Contains pictures or .js sources, that the widget might need.
• details.vm – Is the mouse over text in the widget sidebar in liveReport pages.
• description.vm – Allows to add additional information to the „About this Widget“ in the administration.
• icon.png – The icon shown in the widget panel in liveReport pages.
• parameters.vm – Contains the defined widget parameters, which can then be used in the „render.vm“.
• render.vm – Contains the main code of the widget.
• widget.properties – Contains the name and and tags, in which the widget will be sorted in the widget sidebar in liveReport pages.

Example

Enough of the theory now. I will create a very simple widget, to show it step-by-step.

The widget will render all work items of the current project.

Therefore we can simply start writing the widgets code in a „script block“ of a liveReport page. So lets first of all create a new report page and add a script block widget to it:

In this widget we can add our code. From scratch we can simply write HTML, Velocity and use the accessible variables. To use CSS or Javascript, we would have to put it in tags. To use CSS, we have to put it in <style> </style> tags. And to use JS, we have to put it in <script> </script> tags.

Now that we have the script block in our report page, we can start to create our widget. The same code you write here will later be transferred and runable in the widget. But I start writing code in the script block, as this is a great way to start the first implementation of a widget, because I can check instantly if it works.

I’ll start with a simple widget. You can paste this code in your script block and it should work in any system.

## Getting the actual project ID, this script block/widget is in
#set($projectId = $page.getReference().projectId())

## Get all work items of the project
#set($renderWIs = $transaction.workItems().search().query("project.id:$projectId"))

## Render all work items of the project
#foreach($workItem in $renderWIs)
	$workItem.render().withLinks()<br>
#end

Now that we have a working code example, let’s create a reusable widget out of it.

To do this, we’ll create a folder with the following files (you might simply reuse another widget from extension portal or OOTB Polarion):

And we will paste our code into the render.vm (which is basically a simple text file with „.vm“ ending) and save it.

Into the widget.properties, we’ll write the name of our widget and in which sections it should be categorized.

As icon.png we take any small picture, that should be shown in the widget sidebar.

This is already enough to now deploy the widget.

We now deploy the full folder in our repository under: ../.polarion/pages/widgets.

And voilà, you can now add this widget to any report page:

I hope this will help you to create your own great widgets!