Creating a Gadget for WSO2 Gadget Server using Carbon Studio

Objectives:

Often, it is preferable if we can create artifacts using an IDE rather than navigating through a web console, because it is quicker and easier. WSO2 Carbon Studio gives you that ease where it can be installed in Eclipse IDE. Creation/testing and debugging of many Carbon artifacts are supported in WSO2 Carbon Studio 1.0.0 release. WSO2 Gadget Server artifact support is one example. This tutorial takes you through the step by step process of creating a gadget from scratch and making it viewable via the WSO2 Gadget Server portal.

Introduction:

WSO2 Carbon Studio supports tooling facility for many products in the WSO2 Carbon platform. This also supports creating/testing and deploying of gadget artifacts which are the main artifacts used within WSO2 Gadget Server. In Carbon Studio, the gadgets artifacts can be created in four different ways such as creating a new gadget, importing a dashboard archive (.dar) file from file system, importing gadget resource file from file system, and importing a gadget collection from registry. In this tutorial I will be taking you through the steps of how a gadget artifact is created from scratch using the gadget's editors provided within C-App.

Applies To:

Prerequisites:

As the initial step, you need to have WSO2 Carbon Studio installed in Eclipse. Carbon Studio Release 1.0.0 can be downloaded from here. After that you need to create a C-Apps project in your Eclipse IDE. For this, simply right click on the project explorer and select to create a new project. Then select “WSO2 Application Project" as your project type. The C-Apps project is the IDEs container which will hold the Carbon artifacts and details of their configurations.

In this scenario, first we will be creating a gadget artifact which will hold our gadget specification. Then we will start a WSO2 Gadget Server instance from Eclipse IDE and deploy the gadget specification in the server. If any failure is returned from the artifact, we can correct it from the IDE itself and redeploy in the server. After that, we need to set user permissions in the WSO2 Gadget Server to access this gadget and add to the gadget repository. As the last step, we will move to the WSO2 Gadget Server portal to access and view the gadget.

Now lets' move on to details;

1. Create a gadget artifact.

Click on “Create New artifact” button in “root-artifact.xml” in your C-Apps project and select "Gadget" OR Right click on the C-Apps project you created and select "Gadget". You will get the “New Gadget” creation wizard.

 At the 'Name' prompt, give your gadget artifact a name and proceed.

In the next screen, specify a name for the folder containing your gadget specific artifacts and finish the wizard. NOTE: The project that you will be creating the artifact in, will appear selected in this window. If you want you can change it here.

After this initial step, you should have your project structure like this:

3. Develop the gadget code.

WSO2 Carbon Studio loads open social development environment (OSDE) in Eclipse. This is one of the plug-ins that gets installed with Carbon Studio. If you double click on your .xml file (maps.xml in my case) you will have the OSDE opened up on the right side of the IDE. Now, lets fill in the gadget code. The code that I am going to put in is a sample taken from Google's gadget docs (https://code.google.com/apis/gadgets/docs/fundamentals.html#location

In the proceeding steps, I will show you how easy it is to create and deploy this using WSO2 Carbon Studio.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Map of __UP_loc__" height="300" 
    author="Jane Smith" 
    author_email="[email protected]" /> 
  <UserPref name="loc" 
    display_name="Location" 
    required="true" />
  <Content type="html">
  <![CDATA[ 
    <script src="https://maps.google.com/maps?file=js" type="text/javascript"></script>
    <div id="map" style="width: 100%; height: 100%;"></div>
    <script type="text/javascript">
    var prefs = new gadgets.Prefs();
    var map = new GMap(document.getElementById("map"));
    map.addControl(new GSmallMapControl());
    map.addControl(new GMapTypeControl());
    var geocoder = new GClientGeocoder();
    geocoder.getLatLng(prefs.getString('loc'), showMap)
  
    function showMap(point) {
      if (point!=null) {
        map.centerAndZoom(point, 6);
      }
    };    
    </script>
  ]]> 
  </Content>

 And it is as simple as filling the tabs that you find at the bottom your IDE (see the image below).

There are ModulePrefs such as title, author, author_email supported by the editor. Values for these can be entered in the ‘Attributes’ section in the ‘Basic’ tab. My sample gadget specification also require ‘features to be added. Features can be added from the ‘Features’ section in the Basic tab.

The Userpref tag holds values that require user’s input. In the sample gadget specification that I am using I am asking user’s preferred location as an input.  This can be added from 'UserPref' tab in the editor. I also marked it as a required parameter. Since it doesn't have a default value, I kept that option empty and proceeded with the default 'String' data type.                               

The Content type of a gadget specification tells to which content type the gadget belongs to. It can be "html" or "url". If 'html", it can hold an HTML code and if it is "url" the content will be a link to an external HTML content. To add contents through the editor, click the 'Add' button in the 'Content' tab and mention the content type 'html' content (as shown in the above code: Content type="html"). ‘view’ is an optional attribute that can be used within ‘Content’ tag. Since my sample is using the default view, I can leave 'view' type empty.

Once that is done, you will have an entry created for the view and the content type that you added just now. In the next step you need to fill in the HTML content' to it. This includes all the things you put within CDATA tags in the above gadget specification.

NOTE: You DON'T need to type in <![CDATA[ section, as OSDE prints it by itself. Also, you cannot have <html>, <head> or <body> tags as having them violates the gadget rules.

That's it! If you navigate to 'Source' tab, you will see your gadget's code there with complete, correct syntax and perfect alignments.

4. Add the gadget to server's gadget repository

In this step, we are going to start WSO2 Gadgets Server via Carbon Studio and deploy the carbon application (the gadget artifact) that we created above, to the server. To do this, you need to have a WSO2 Gadget Server binary distribution with you. Download it from here, extract and you will be ready.

i. Start WSO2 Gadget Server from Eclipse & Deploy the application

While in J2EE perspective in eclipse, go to server area and add a WSO2 Gadget Server as described here. This will let you start the server from within Eclipse.  After the server is started, right click on the server configuration and select 'Add & Remove' option. In the 'Add & Remove' box select the application we created above and add it to the server as shown below.

ii. View the deployed content from server's web console.

Now, login to Gadget Server admin console and navigate to '/_system/config/repository/dashboards/gadgets' folder in internal registry. You will see the gadget that was deployed from Carbon Studio listed in here. This console lets you view, edit and even download your gadget specification.

Also, if you view the installed application list by going to “Advanced > Applications >List”,  the Carbon applications created and deployed from WSO2 Carbon Studio will be listed there. You can navigate to each application's dashboard view and view its configuration details. Now that we saw the gadget being deployed in the Server from C-App, we have to follow two more steps to make it available in Gadget’s portal, where it is actually used.

iii. Grant anonymous user permission to the gadget.

Navigate to '/_system/config/repository/dashboards/' in the internal registry. You will see a collection with the name 'gadgets' there. The gadget specifications deployed from WSO2 Carbon Studio are stored here. We need to grant permission for 'anonymous user' to this gadgets folder.

iv. Add the gadget to gadget repository.
From 'Manage Gadget Server' menu, access 'Gadget Repository'. Click 'Add New Gadget' link from there. You need to add the gadget's information there.

  Gadget Name : Maps
  Gadget URL  : /registry/resource/_system/config/repository/dashboards/gadgets/maps.xml
You can add an image and description as you prefer.

v. Make the gadget available by default
Now, the gadget is added to the repository. We need to make it a default gadget.

Go to the Gadget Repository and look for your maps gadget. Once you found it, enable the 'Make Default' and 'Show Gadget To Anonymous User' options.

Make Default -
Makes the gadget available to be added by any user who signs into gadget portal.

Show Gadget To Anonymous User -
Makes gadget available as a default gadget to users not signed in.

5. Access the gadget from Gadgets' Portal

Let's move to gadget's portal and use our gadget there.

i. Click on "View Portal' menu or directly access https://localhost:8080/portal

You could be automatically signed in as admin if you are in the same browser session. Else, click on the 'Sign-in' link and sign in as admin (until you register a new user).

ii. Click on 'add tab' button on top of the portal window to add a new tab.

iii. To add your new gadget to this new tab, click on the 'Add Gadgets' button and it will open the gadget repository. Search for your 'maps' gadget and add it.

Return to the Dashboard and you'll see your gadgets there!!!

Author : Yumani Ranaweera, Technical Lead, WSO2 Inc