Tutorial - Writing a JQL standalone gadget
On this page:
This tutorial shows you how to write a gadget that will load data from a JIRA JQL Query into the gadget window and allow the user to click on an item to load the issues content in their browser. For simplicity this tutorial we will pull data from a local installation of JIRA (http://localhost:8070) into a local installation of Confluence (http://localhost:8080/confluence) and using a gadget.xml file coming from a different web server, in this case they are being served by our SVN server . To adapt the tutorial to your environment simply change out the server name ("localhost") and ports ("8070" and "8080") as appropriate.
The reason this tutorial uses local installations of both Confluence and JIRA is because this gadget requires that you configure Confluence as an OAUTH consumer for JIRA. Therefore this tutorial requires that the reader be an Administrator on both Confluence and JIRA. Please refer to the installation guides for information on installing Confluence or JIRA.
Step 1. Create the Gadget Specification
- Copy the following code to create the basic XML file that will become your gadget specification:
- Paste the code into a text editor and save the file as jql-gadget.xml
Step 2. Update the Gadget Title and Other Descriptive Details
Update the values of the following attributes in the
<ModulePrefs>element of your gadget specification:
Enter 'JQL Gadget'.
Enter 'This gadget pulls content from a JIRA JQL Query and displays the results in the gadget window'.
Enter your own name.
Enter your own email address or remove this attribute.
- Update the value of the
categoriesparameter of the
gadget-directoryfeature to 'JIRA'. This controls which category your gadget appears in within the JIRA gadget directory. NOTE: Valid values are "JIRA", "Confluence", "FishEye", "Crucible", "Crowd", "Clover", "Bamboo", "Admin", "Charts", "External Content", and "Other".
The resulting XML should look something like this:
Step 3. Make the Gadget Available on a Server
Because you are developing a standalone gadget, you can host your gadget specification on any server that will make it available to a gadget container such as a Confluence page or the JIRA Dashboard. You can host the gadget xml file on any webserver at your disposal. If you want to use the same XML that I used you can follow along using the hosted files from our SVN server . NOTE: These files assume that you have JIRA running at http://localhost:8070 and Confluence running at http://localhost:8080/confluence.
Step 4. Add the Gadget to a Confluence Page for Testing
Your gadget can already do something: It can say 'Hello world!'. Test it by adding it to a Confluence page.
- Go to Confluence Administration and click 'External Gadgets'.
- The 'External Gadgets' screen appears, showing the list of gadgets available in the Macro Browser.
- Enter the Gadget Specification URL and click 'Add'.
- Edit a Confluence Page that you want to add your gadget to.
- Click the 'Insert/Edit Macro' button.
- Enter 'JQL' in the search box
- Highlight your gadget and click the 'Add' button to add the wiki markup for the gadget macro to the wiki page.
Step 5. Make the Gadget Do Something Useful
<Content>element in your gadget specification contains the working parts of the gadget. The
<Content>element consists of:
CDATAdeclaration, to prevent the XML parser from attempting to parse the gadget content. Include '
<![CDATA[GADGETDEV:' (without the quotes) at the beginning and '
]]>' (without the quotes) at the end of your
- Optional static HTML. When a dashboard renders the gadget, it will render this HTML.
- Optional CSS style sheets.
To start continue filling out the ModulePrefs to include a screenshot and thumbnail for the gadget - these are optional - but will make the gadget look better in the gadget directory.
We also need to add the settings to enable this gadget for OAUTH by adding this XML in the ModulePrefs tag
Now change the <content> of the gadget to look like this:
Check out the resulting XML in jql-gadget-step3.xml .
Step 6. Update the Gadget on the Server
- Follow the steps from 'Step 4' above to add this version of the gadget to your confluence instance and add it to the page for testing.
- If you make changes to the xml file you may need to restart Confluence to pick up the changes.
When you test the gadget you might see an error that says 'OAuth error: consumer_key_unknown'. This indicates that OAuth has not been configured between JIRA and Confluence. We will do this in the next step.
Step 7. Configure OAuth
- To configure OAuth log in to JIRA as an administrator.
- Scroll down to the 'System' section of the Administration options and click 'OAuth'
- Click 'Add OAuth Consumer' .
- Enter 'http://localhost:8080/confluence\* (http://localhost:8080/confluence*)' in the '*Consumer Base URL' field.
- Click 'Add'
- If you click into the new consumer you will see that it as been configured with the secret key that allows OAuth requests between the two servers.
Step 8. Test Working Gadget on Confluence Page
After configuring OAuth you should now be able to authorise the gadget for use by Confluence.
- Reload the page that contains the gadget.
- Click the 'Authorise this Gadget' link
- Click the 'Approve Access' button
- View the list of issues
Step 9. Make the Gadget Look Better
Check out the resulting XML in jql-gadget-step4.xml
Now that you have created a working gadget, you may like to look at some more advanced topics: