Developing Plug-Ins - Dashboard Panel Fragments

This tutorial is brought to you by Jan Thielemann from evenos GmbH (www.evenos-consulting.de). If you have questions, criticism or improvement suggestions, feel free to visit me (Jan.thielemann) or write me an email

Goal of this tutorial

Dashboard Panels are a greate way to improve the usability of the webui. You can give relevant information or quick access to important functions for users right from the main page. The goal of this tutorial is to show how you can create a custom Dashboard Panel and deploy it via a fragment-project. See http://wiki.idempiere.org/en/OSGi#Fragments

Prerequisites

Before you start, it's a good idea to take a look at Create a Feature-Project, Developing Plug-Ins without affecting the trunk and Get your Plug-Ins running.

tl;dr

https://www.youtube.com/watch?v=ivMTpXpTMqE

The workflow

Create a new fragment

Start by creating a new Fragment-Project. To do this, go to File>New>Other and select Fragment Project from the Plug-in Development section. Select Equinox as the OSGi framework, enter a name and a location and hit next.

Here you have to select the execution environment you want. Also select org.adempiere.ui.zk as the Host Plug-in and click on finish. Once eclipse created the fragment for you, create a new package like org.adempiere.webui.dashboard in the src folder. Create a new class and call it what you like. Normally Dashboard Panels start with "DP" so call it "DPMypanel" or so. Also create a new folder at the top level of your fragment and call it zul. In this folder create a new file and call it what you like but it has to have ".zul" as the file extension.

Now open the MANIFEST.MF and go to the dependencies tab. Here you select all additional plug-ins on which your fragment depends. This is for example necessary if you have a plug-in where you have custom model classes which you want to use in your dashboard panel. On the runtime tab, you have to make the previously created package available. Add it to the exported packages section. Also add the zul folder to the classpath section. Go to the build tab and add "." as a library if it's not already there. Also add the "src" folder. In the Binary Build section, make sure that your ".zul" and the manifest are both checked.

Create a Dashboard Panel

Now open the class you created. This one should inherit from DashboardPanel. In the default constructor, first make a call to super. Then you are free to do what you want. Create your custom layout, add buttons and tables or what you need. You can set a fixed heigth for the dashboard panel or let it calculate it's content size by itself but then the panel could be larger than the browser window.

The next step is to open your .zul file which you created. Here you specify the path to the class:

<?xml version="1.0" encoding="UTF-8"?>
<window use="org.adempiere.webui.dashboard.DPMyPanel"/>

Install the fragment

To install the fragment, you can follow the tutorial Create a Feature-Project. For Dashboard Panel Fragments there is some additional work to do. After you installed the fragment or a custom feature via p2 or the Apache Felix Web Console, you have to search the org.adempiere.ui.zk bundle and refresh it.

The refresh of the ui.zk bundle is necessary. Otherwise, the fragment with the Dashboard Panel will stay in the state installed. If you have done everything right, the state should now be resolved (or fragment in Felix).

Remember to activate the Dashboard content by logging in as SuperUser / System and add your dashboard using the menu Dashboard Content Edit.