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:

Velocity Widget 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:

Add Script Block Widget

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.

Widget Code in Script Block
## 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):

Polarion Widget Files

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.

widget.properties

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:

Example Widget

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

Published by PolarionDude

Dude who does Polarion - if Polarion would be a verb.

6 thoughts on “How to create your own Velocity Widget

  1. Hi, great and very helpful blog!
    What I’d like to do is to store a JETdb document (e.g. from MS Access) as a LiveDoc attachment. Then to create a Velocity+SQL widget which would check some entries in the attached db, compare it with work items content (e.g. ID, title, some custom fields) from the LiveDoc and generate some report. Would it be possible at all without writing java widget or java based extension? Thanks for any info.

    Like

    1. Hello kubsztal,

      I don’t think that this is possible with velocity only. Atleast I don’t believe, that you can open/read a JETdb with Velocity.
      So I would assume on the first glance, that you have to create a java widget.
      You can find a slide deck to advantages/disadvantages of the technologies in this official post of Siemens und “Breakout-Session 2”: https://blogs.sw.siemens.com/polarion/recap-german-polarion-autumn-meeting-2020/
      https://view.highspot.com/viewer/5fc4d35ba4dfa01398ff3cc9

      Kind regards,
      Florian

      Like

      1. Hi Florian,

        thank you for the links. Indeed, java extension seems to be the way to go. I also found UCanAccess JDBC driver which allows reading from and writing to Access DBs – should be very helpful.

        Best regards, Kubsztal

        Like

  2. Hi Florian,

    I’ve got something up and running eventually. I’m able to access M$ Access database file from stand-alone Java application using UCanAccess JDBC driver and I can extract all needed info from Live Docs and Work Items in my Polarion Java extension. What I’m not able to do is to access the database directly from the extension: the JDBC driver is not loaded. Do you know if this is possible at all? Or is there a way to load external JDBC driver during starting Polarion server that it’d be later accessible to my extension?

    Thanks.

    Like

  3. Hi Florian,
    yeah, I should involve myself in Polarion community a little bit more often, I think… Nevertheless, I found the solution: including required libs as source code and explicitly loading UcanaccessDriver class solved the issue 🙂
    Best regards, Kubsztal

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create your website with WordPress.com
Get started
%d bloggers like this: