\\

!1 Widget Development and Deployment QuickStart Guide

\\

[{TableOfContents}]
!2 How to write and deploy a custom Widget
%%information
This guide provides general hints for widget development. PTC recommends verifying specific requirements and compatibility with your Codebeamer version.%!
!3 Prerequisites

Before starting~, make sure that the following are installed:

* At least Java JDK 1.8 (Oracle or OpenJDK).
* Eclipse IDE~, this guide uses Eclipse Luna. Check whether the Eclipse installation has [Eclipse Maven Integration|https://projects.eclipse.org/projects/technology.m2e].
* Download the example project from [here|CB:/displayDocument/demo-widget.zip?doc_id=64914393]. Extract the {{.zip}} file to a folder.
* Copy the {{cb.jar}} file from {{CODEBEAMER~_HOME/tomcat/webapps/cb/WEB~-INF/lib/cb.jar}} to a folder.
!3 Set up the Development Environment
!4 Step 1. Import the project

Open Eclipse and choose the ''File'' __► __''Import...'' menu option:

[!Step 1 import the project.png#4345a09fe567194b3da4aa466b57d387!]

Choose Existing Maven Projects~, and select the extracted project:

[!Choose Existing Maven Projects.png#0e1c35f6a6e4f2d60f8b92541449397c!]

[!Choose Existing Maven Projects2.png#e70bddb056a27e22f4da57319f058cb8!]

When the import is successful~, then the project appears on the left side:

[!project appears on the left side.png#61bdeae49c5c783edecc6efacb8296f7!]

!4 Step 2. Rewrite the path of {{cb.jar}}

The Maven build process will download all the dependencies~, but the path to {{cb.jar}} have to be set manually. Its standard location is {{CODEBEAMER~_HOME/tomcat/webapps/cb/WEB~-INF/lib/cb.jar}}.

[!Step 2. Rewrite the path.png#85e43bee79a18b7ed4a9e97bf2f82d52!]

!3 Build the code

This example project contains a simple Widget~, which has a single field:

[!Build the code.png#5476be16f11b5076a98999ec5217bf0b!]

And renders this field as text:

[!renders this field as text.png#2601f73ec713517d6618d2f1c75d517b!]

First right click on the {{pom.xml}} file~, and choose ''Run As'' ► ''Maven build...''

[!mceclip115aa8f425c6.png#c2c5eedb84e419f3c5483ef1f39cb4e6!]\\

Type "''clean install"'' into the ''Goals'' field and click on __~[Run~]__.

[!clean install.png#759d100aaaa13662277bbb850a9fde6f!]

The console tab should display something like this:

[!console tab.png#27c4a93c4bfd8482b1e2685b5158745f!]

The ''target'' directory contains the compiled jar file:

[!target directory.png#a44e653e1a6b3f9ff6df8fc3c01646c8!]

!3 Deploy the Widget
!4 Step 1. Stop the running codebeamer instance

See [Starting/Stopping Codebeamer|WIKIPAGE:8689#section-Starting%2FStopping+codeBeamer].

!4 __Step 2. Copy the Widget jar file__

Copy the jar file created by the Maven build process ({{demo~-widget~-0.0.1.jar}}) to {{CODEBEAMER~_HOME/tomcat/webapps/cb/WEB~-INF/lib}}.

[!Step 2. Copy the Widget jar file.png#6a20bf24b97c1721c43bc3336788f9c4!]

!4 Step 3. Start the Codebeamer instance

See [Starting/Stopping Codebeamer|WIKIPAGE:8689#section-Starting%2FStopping+codeBeamer].

!4 Step 4. Verify that the Widget is deployed

When properly deployed~, the Widget shows up in the proper category on Widget Browser:

[!Step 4. Verify that the Widget is deployed.png#1d1632a465be518494c09c9f6792928c!]

!3 Troubleshooting & Important Notes
!4 i18n of labels

Every widget needs a couple of labels to render properly which need to be specified in the {{my~-ApplicationResources.properties}} file inside the {{src/main/resources}} folder. See [Widget Development Documentation|WIKIPAGE:1469179] for more details

Our recommended format for name and description:

* ''dashboard.X.widget.name'' ~- Widget~'s name label on Widget Browser.
* ''dashboard.X.widget.short.description'' ~- Widget~'s description on Widget Browser.

Mandatory format for attribute labels:

* ''widget.editor.field.label.X''

If the {{my~-ApplicationResources.properties}} file is already in use for other purposes~, merge the widget~-related labels into that file~! (Its expected location is {{CODEBEAMER~_HOME/tomcat/webapps/cb/WEB~-INF/lclasses}})

!4 Widget not recognized

codebeamer application uses Spring annotations to discover Widgets. If the widget does not show up in the Widget Browser~, then double check these:

* {{Widget}} class and constructor of {{Widget}} class have the Jackson annotations like in the demo project.
* {{WidgetInformation}} class has {{@Component}} annotation.
* {{Renderer}} classes have {{@Component}} annotation and a unique {{@Qualifier}}__.__
* Constructor of {{Renderer}} classes have {{@Autowired}} annotation.
* {{WidgetFactory}} class has {{@Component}} annotation and a unique {{@Qualifier}}__.__
* Constructor of {{Renderer}} classes have {{@Autowired}} annotation. {{Renderer}} parameters reference the correct {{@Qualifiers}}.
* {{getInjectableValues}} method in {{WidgetFactory}} class use the same identifiers as {{@JacksonInject}} annotations on the {{Widget}} constructor.
!4 Widget not available
%%information
Custom widgets for codebeamer are currently not supported on [codebeamer X|https://intland.com/codebeamer-x/].%!

If a Dashboard contains a Widget~, which is not present in the system~, then codebeamer shows the following error:


%%(background-color:#ffffff;)[!widgetnotavailable.png#a160f6fc5240ed3fa69d83a9a0b4410b!]%!

\\
Double check that the correct jar file is in {{CODEBEAMER~_HOME/tomcat/webapps/cb/WEB~-INF/lib}}.