Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
Info
iconfalse
titleTable of Contents

Table of Contents
maxLevel1

Widgets

Dashboard widgets are implemented as Ruby on Rails views. Widgets must be declared with the Java extension point org.sonar.api.web.Widget.

Example of structure :

  • sonar-foo-plugin/
    • src/
      • main/
        • java/
          • com/
            • foo/
              • MyWidget.java
        • resources/
          • com/
            • foo/
              • my_widget.html.erb
Code Block
titleMyWidget.java
languagejava
package com.foo;

import org.sonar.api.web.*;
@WidgetCategory("Labs")
@WidgetProperties({
  @WidgetProperty(key = "max", type = WidgetPropertyType.INTEGER, defaultValue = "80")
})
public final class MyWidget extends AbstractRubyTemplate implements RubyRailsWidget {
  public String getId() {
    return "my_widget";
  }
  public String getTitle() {
    return "My Widget";
  }
  protected String getTemplatePath() {
    return "/com/foo/my_widget.html.erb";
  }
} 
Code Block
titlemy_widget.html.erb
languageruby
<p>This is my first widget</p> 
<p>Display widget property: <%= widget_properties['max'] -%></p>
Info

Widgets can be manually tested with the URL : http://<server>/widget?id=<widget id>.

If you're testing a project-level widget, you'll need to add a project to the URL, like so : http://<server>/widget?id=<widget id>&resource=<project key>.

The width can be set with the property widget_width. The default value is 350px.

Info

Helpers and partials are not supported.

Development mode

The development mode reloads Ruby changes on the fly. It lets you edit code and immediately display your widget changes.

To enable development mode on a widget :

  1. Install SonarQube
  2. Edit the method RubyRailsWidget#getTemplatePath() in order to return the absolute path to the widget file, rather than the class path.
  3. Build the plugin and copy it to /extensions/plugins
  4. Start server
  5. (warning)Do not forget to revert the path before commiting your changes

Applications

Info

Ruby on Rails applications are supported since SonarQube3.0.

Ruby on Rails applications allow plugins to extend the SonarQube webapp with a complete MVC stack : controllers, helpers, models and views. Unlike widgets, it does not require you to declare a Java component; Ruby sources just have to be stored in the plugin directory : /src/main/resources/org/sonar/ror/<plugin key>. This directory must also contain an empty file named init.rb.

Example for an application provided by the plugin with key 'foo' :

  • sonar-foo-plugin/
    • src/
      • main/
        • resources/
          • org/
            • sonar/
              • ror/
                • foo/
                  • init.rb
                  • app/
                    • controllers/
                      • my_console_controller.rb
                    • helpers/
                      • my_console_helper.rb
                    • views/
                      • my_console/
                        • index.html.erb
                        • _my_partial.html.erb

Controller URLs are not isolated from the core URLs used by SonarQube. You have to be careful of potential conflicts and choose controller names different than : https://github.com/SonarSource/sonar/tree/master/sonar-server/src/main/webapp/WEB-INF/app/controllers

Code Block
titlemy_console_controller.rb :
languageruby
class MyConsoleController < ApplicationController

  # this is an administration console
  SECTION=Navigation::SECTION_CONFIGURATION

  before_filter :admin_required
  
  # GET http://<server>/my_console/index
  def index
    # automatically renders the file ../views/my_console/index.html.erb
  end
end

Add page to sidebar

By the default the application is not visible. Pages have to be declared with the Java extension point org.sonar.api.web.Page :

Code Block
titleExample of MySample.java
languagejava
import org.sonar.api.web.NavigationSection;
import org.sonar.api.web.Page;
import org.sonar.api.web.UserRole;

@NavigationSection(NavigationSection.CONFIGURATION)
@UserRole(UserRole.ADMIN)
public final class MyConsolePage implements Page {
  public String getId() {
    // URL of the controller
    return "/my_sample/index";
  }
  public String getTitle() {
    return "My Console";
  }
}

Development mode

The development mode reloads Ruby changes on the fly. It allows you to edit code and directly interact with the application. Only changes on the files that exist during server startup are supported. Adding a new file requires you to restart the server.

To enable the development mode on an application :

  1. Install SonarQube
  2. Install the plugin by copying the initial JAR file to /extensions/plugins
  3. Enable the development mode :
    1. If SonarQube 3.x : edit the file war/sonar-server/WEB-INF/web.xml and set the context-params rails.env to development and jruby.max.runtimes to 3.
    2. If SonarQube 4.x : edit conf/sonar.properties and add the line sonar.web.dev=true
  4. Edit the file war/sonar-server/WEB-INF/config/environment.rb and set the absolute path to your ruby application by replacing the property config.plugin_paths :

    Code Block
    #config.plugin_paths << "#{Java::OrgSonarServerUi::JRubyFacade.getInstance().getServerHome()}/temp/ror"
    config.plugin_paths << '/absolute/path/to/sonar-foo-plugin/src/main/resources/org/sonar/ror'
  5. Start server

Web services

Web Services are simply packaged as applications. The only differences are that controllers are located in controllers/api/ instead of controllers/, and the class must extend Api::ApiController.

Code Block
titleExample of code for controllers/api/my_web_service_controller.rb
languageruby
class Api::MyWebServiceController < Api::ApiController

  # GET http://<server>/api/my_web_service/index
  def index
    respond_to do |format|
      # returns {'foo': 'bar'}
      format.json { render :json => jsonp({'foo' => 'bar'}) }
    end
  end
end 
Info
iconfalse

The Java extension point org.sonar.api.web.RubyRailsWebservice is still supported but is useless since SonarQube 3.0.

Static files

Plugins can provide static files like images, CSS or JS files. They have to be copied in src/main/resources/static and then can by accessible from the public URL :

Code Block
http://<server>/static/<plugin key>/<filename>

The URL can be generated from widgets or applications with the Ruby helper function :

Code Block
url_for_static(:plugin => '<plugin key>', :path => '<filename>')

Note that the plugin key is logged during the maven build :

Code Block
[INFO] -------------------------------------------------------
[INFO] Plugin definition in update center
[INFO]     Key: foo
[INFO]     Name: Foo
[INFO]     Description: 
[INFO]     Version: 1.0-SNAPSHOT
Info

Static files are not deployed on the fly when the development mode is enabled. The plugin has to be built and re-installed after changes.

Dynamic charts

SonarQube integrates JFreechart Eastwood 1.1.0, a partial implementation of the Google Chart API . To know if a chart is implemented, simply replace http://chart.apis.google.com/chart?<params>  by http://<sonar>/gchart?<params>.

TBD : protovis.js.

Language packs

See Internationalization