Writing Review Board Extensions¶

Minimum Extension Structure¶

At minimum, an extension requires the following files:

• setup.py
• extensiondir/__init__.py
• extensiondir/extension.py

The following are a description and example of each file. In each example extensiondir has been replaced with the extension’s package, ‘sample_extension’:

setup.py

This is the file used to create the Python Egg. It defines the Entry Point along with other meta-data. See Python Egg for a description of features relevant to Review Board extensions. Example:

from setuptools import setup


PACKAGE = "sample_extension"
VERSION = "0.1"

setup(
    name=PACKAGE,
    version=VERSION,
    description="description of extension",
    author="Your Name",
    packages=["sample_extension"],
    entry_points={
        'reviewboard.extensions':
            '%s = sample_extension.extension:SampleExtension' % PACKAGE,
    },
)

See Python Egg and the setuptools documentation for more information.

sample_extension/__init__.py

This file indicates the sample_extension is a Python package.

sample_extension/extension.py

This is the main module of the extension. The Extension subclass should be defined here. Example:

from reviewboard.extensions.base import Extension


class SampleExtension(Extension):
    def __init__(self, *args, **kwargs):
        super(SampleExtension, self).__init__(*args, **kwargs)

Other Structure¶

Review Board also expects extensions to follow a few other conventions when naming files. The following files serve a special purpose:

models.py

An extension may define Django models in this file. The corresponding tables will be created in the database when the extension is loaded. See Models for more information.

models/

As an alternative to using models.py, a Python package may be created in models/, which may define models in its modules.

admin_urls.py

An extension may define urls for configuration in the admin panel. It is only used when is_configurable is set True. For more information, see Admin URLs.

admin.py

This file allows an extension to register models in its own Django admin site. It is only used when has_admin_site is set True. For more information, see extension-admin-sites.

Default Settings¶

To provide defaults for the settings dictionary, an extension may use the default_settings attribute. If a key is not found in settings, default_settings will be checked. If neither dictionary contains the key, a KeyError exception will be thrown.

Here is an example extension setting default_settings:

class SampleExtension(Extension):
   default_settings = {
      'mysetting': 1,
      'anothersetting': 4,
      'stringsetting': "I'm a string setting",
   }

   def __init__(self, *args, **kwargs):
     super(SampleExtension, self).__init__(*args, **kwargs)

Admin URLs¶

If an extension has is_configurable set to True, it will be assigned a URL namespace under the admin path. A button labeled Configure will appear in the list of installed extensions, linking to the base path of this namespace.

To specify URLs in the namespace, an admin_urls.py file should be created, taking the form of a Django URLconf module. This module should follow Django’s conventions, defining a urlpatterns variable.

urlpatterns¶

Used to specify URLs. This should be a Python list, in the format returned by the function django.conf.urls.patterns().

The following is an example admin_url.py file:

from django.conf.urls.defaults import patterns, url


urlpatterns = patterns('sample_extension.views',
    url(r'^$', 'configure')
)

This would direct the base URL of the namespace to the configure view.

For a more in depth explanation of URLconfs please see the Django URLs documentation.

Settings Form¶

Review Board supplies the views, templates, and a base Django form to make creating a configuration UI for Settings painless. To take advantage of this feature, do the following:

• Define a new form class inheriting from djblets.extensions.forms.SettingsForm
• Create a new URL pattern to reviewboard.extensions.views.configure_extension, providing the extension class and form class. See Admin URLs for more information on creating URL patterns.

Here is an example form class:

from django import forms
from djblets.extensions.forms import SettingsForm


class SampleExtensionSettingsForm(SettingsForm):
    field1 = forms.IntegerField(min_value=0, initial=1, help_text="Field 1")

Here is an example URL pattern for the form:

from django.conf.urls.defaults import patterns

from sample_extension.extension import SampleExtension
from sample_extension.forms import SampleExtensionSettingsForm


urlpatterns = patterns('',
    (r'^$', 'reviewboard.extensions.views.configure_extension',
     {'ext_class': SampleExtension,
      'form_class': SampleExtensionSettingsForm,
     }),
)

URLHook¶

reviewboard.extensions.hooks.URLHook are used to extend the URL patterns that Review Board wil recognize and respond to.

URLHook requires two arguments for initialization: the extension instance and the URL patterns.

Example usage in an Extension:

class SampleExtension(Extension):
    def __init__(self, *args, **kwargs):
        super(SampleExtension, self).__init__(*args, **kwargs)
        pattern = patterns('', (r'^sample_extension/',
                                include('sample_extension.urls')))
        self.url_hook = URLHook(self, pattern)

Notice how sample_extension.urls was included in the patterns. In this case, sample_extension is the package name for the extension, and urls is the module that contains the patterns:

from django.conf.urls.defaults import patterns, url


urlpatterns = patterns('sample_extension.views',
    url(r'^$', 'dashboard'),
)

DashboardHook¶

reviewboard.extensions.hooks.DashboardHook can be used to define a custom dashboard page for your Extension. DashboardHook requires two arguments for initialization: the extension instance and a list of entries. Each entry in this list must be a dictionary with the following keys:

• label: Label to appear on the dashboard’s navigation pane.
• url: URL for the dashboard page.

If the extension needs only one dashboard, then it needs only one entry in this list. (See NavigationBarHook)

Example usage in an Extension:

class SampleExtension(Extension):
    def __init__(self, *args, **kwargs):
        super(SampleExtension, self).__init__(*args, **kwargs)
        self.dashboard_hook = DashboardHook(
            self,
            entries = [
                {
                    'label': 'A SampleExtension Label',
                    'url': settings.SITE_ROOT + 'sample_extension/',
                }
            ]
        )

Corresponding code in views.py:

def dashboard(request, template_name='sample_extension/dashboard.html'):
    return render_to_response(template_name, RequestContext(request))

Corresponding template dashboard.html:

{% extends "base.html" %}
{% load djblets_deco %}
{% load i18n %}

{% block title %}{% trans "sample_extension Dashboard" %}{% endblock %}

{% block content %}
{%  box "reports" %}
 <h1 class="title">{% trans "sample_extension Dashboard" %}</h1>

 <div class="main">
  <p>{% trans "This is my new Dashboard page for Review Board" %}</p>
 </div>
{%  endbox %}
{% endblock %}

NavigationBarHook¶

reviewboard.extensions.hooks.NavigationBarHook can be used to introduce additional items to the main navigation bar.

NavigationBarHook requires two arguments: the extension instance and a list of entries. Each entry represents an item on the navigation bar, and is a dictionary with the following keys:

• label: The label to display.
• url: The URL to point to.
• url_name: The name of the URL to point to.

Only one of url or url_name is required. url_name will take precedence.

If your extension needs to access the template context, you can define a subclass from NavigationBarHook to override get_entries and return results from there.

Example usage in an Extension:

class SampleExtension(Extension):
    def __init__(self, *args, **kwargs):
        super(SampleExtension, self).__init__(*args, **kwargs)
        self.navigationbar_hook = NavigationBarHook(
            self,
            entries = [
                {
                    'label': 'An Item on Navigation Bar',
                    'url': settings.SITE_ROOT + 'an_item_url_a/',
                },
                {
                    'label': 'Another Item on Navigation Bar',
                    'url': settings.SITE_ROOT + 'an_item_url_b/',
                },
                {
                    'label': 'Yet Another Item on Navigation Bar',
                    'url': settings.SITE_ROOT + 'an_item_url_c/',
                },
            ]
        )

Subclassing ReviewUIHook¶

extension.py must use a Review UI Hook to register its list of Review UIs. This can be using reviewboard.extensions.hooks.ReviewUIHook directly, using a subclass of it. ReviewUIHook expects a list of Review UIs as argument in addition to the extension instance.

Example: XMLReviewUIExtension:

class XMLReviewUIExtension(Extension):
    def __init__(self, *args, **kwargs):
        super(XMLReviewUIExtension, self).__init__(*args, **kwargs)
        self.reviewui_hook = ReviewUIHook(self, [XMLReviewUI])

ReviewUI Class¶

Each Review UI must be defined by its own ReviewUI class that subclasses reviewboard.reviews.ui.base.FileAttachmentReviewUI. It must also define the following class variables:

• supported_mimetypes: a list of mimetypes of the files that this Review UI will be responsible for rendering.
• template_name: where to find the html template used when rendering this Review UI
• object_key: a unique name to identify this Review UI

Example: XMLReviewUI:

import logging

from django.utils.encoding import force_unicode
import pygments

from reviewboard.reviews.ui.base import FileAttachmentReviewUI


class XMLReviewUI(FileAttachmentReviewUI):
    """ReviewUI for XML mimetypes"""
    supported_mimetypes = ['application/xml', 'text/xml']
    template_name = 'xml_review_ui_extension/xml.html'
    object_key = 'xml'

The class should also have some function to render the particular mimetype(s) that it is responsible for. There are no restrictions on the name of the function or what it returns, but it should be in agreement with logic specified in its corresponding template.

Example: render() in XMLReviewUI. This simply uses the pygments API to convert raw XML into syntax-highlighted HTML:

def render(self):
    data_string = ""
    f = self.obj.file

    try:
        f.open()
        data_string = f.read()
    except (ValueError, IOError), e:
        logging.error('Failed to read from file %s: %s' % (self.obj.pk, e))

    f.close()

    return pygments.highlight(
        force_unicode(data_string),
        pygments.lexers.XmlLexer(),
        pygments.formatters.HtmlFormatter())

ReviewUI Template¶

Here is the template that corresponds to the above Review UI:

xml_review_ui_extension/templates/xml_review_ui_extension/xml.html:

{% extends base_template %}
{% load i18n %}
{% load reviewtags %}

{% block title %}{{xml.filename}}{% if caption %}: {{caption}}
{% endif %}{% endblock %}

{% block scripts-post %}
{{block.super}}

<script language="javascript"
src="{{MEDIA_URL}}ext/xml-review-ui-extension/js/XMLReviewableModel.js">
</script>

<script language="javascript"
src="{{MEDIA_URL}}ext/xml-review-ui-extension/js/XMLReviewableView.js">
</script>

<script language="javascript">
    $(document).ready(function() {
        var view = new RB.XMLReviewableView({
            model: new RB.XMLReviewable({
                attachmentID: '{{xml.id}}',
                caption: '{{caption|escapejs}}',
                rendered: '{{review_ui.render|escapejs}}'
            })
        });
        view.render();
        $('#xml-review-ui-container').append(view.$el);
    });
</script>
{% endblock %}

{% block review_ui_content %}
<div id="xml-review-ui-container"></div>
{% endblock %}

ReviewUI JavaScript¶

Here are the corresponding JavaScript used in the above template.

xml_review_ui_extension/htdocs/js/XMLReviewableModel.js:

/*
 * Provides review capabilities for XML files.
 */
RB.XMLReviewable = RB.FileAttachmentReviewable.extend({
    defaults: _.defaults({
        rendered: ''
    }, RB.FileAttachmentReviewable.prototype.defaults)
});

xml_review_ui_extension/htdocs/js/XMLReviewableView.js:

/*
 * Displays a review UI for XML files.
 */
RB.XMLReviewableView = RB.FileAttachmentReviewableView.extend({
    className: 'xml-review-ui',

    /*
     * Renders the view.
     */
    renderContent: function() {
        this.$el.html(this.model.get('rendered'));

        return this;
    }
});

Entry Point¶

To facilitate the auto-detection of installed extensions, a reviewboard.extensions entry point must be defined for each Extension Class. Here is an example entry point definition:

entry_points={
     'reviewboard.extensions':
         'sample_extension = sample_extension.extension:SampleExtension',
},

This defines an entry point for the SampleExtension class from the sample_extension.extension module. Here is an example of a full setup.py file defining this entry point:

from setuptools import setup


PACKAGE = "sample_extension"
VERSION = "0.1"

setup(
    name=PACKAGE,
    version=VERSION,
    description="Description of extension",
    author="Your Name",
    packages=["sample_extension"],
    entry_points={
        'reviewboard.extensions':
            'sample_extension = sample_extension.extension:SampleExtension',
    },
)

Static Files¶

Any static files (such as css, html, and javascript) the extension requires must be added to the package data of the Python Egg. Here is an example of how this is done in the setup.py file:

package_data={
    'sample_extension': [
        'htdocs/css/*.css',
        'htdocs/js/*.js',
        'templates/rbreports/*.html',
        'templates/rbreports/*.txt',
    ],
}

Here is an example of a full setup.py file including the static files:

from setuptools import setup


PACKAGE = "sample_extension"
VERSION = "0.1"

setup(
    name=PACKAGE,
    version=VERSION,
    description="Description of extension",
    author="Your Name",
    packages=["sample_extension"],
    entry_points={
        'reviewboard.extensions':
            'sample_extension = sample_extension.extension:SampleExtension',
    },
    package_data={
        'sample_extension': [
            'htdocs/css/*.css',
            'htdocs/js/*.js',
            'templates/rbreports/*.html',
            'templates/rbreports/*.txt',
        ],
    }
)

Dependencies¶

Any dependencies of the extension are defined in the setup.py file using install_requires. Here is an example of a full :file`setup.py` file including a dependency:

from setuptools import setup


PACKAGE = "sample_extension"
VERSION = "0.1"

setup(
    name=PACKAGE,
    version=VERSION,
    description="Description of extension",
    author="Your Name",
    packages=["sample_extension"],
    entry_points={
        'reviewboard.extensions':
            'sample_extension = sample_extension.extension:SampleExtension',
    },
    install_requires=['PythonPackageIDependOn>=0.1']
)

This will ensure any packages the extension requires will be installed. See the Setuptools documentation for more information on install_requires.

In addition to requiring python packages when installing, an extension can declare a list of additional extensions it requires. This requirements list gives the name of each extension that must be enabled before allowing the extension itself to be enabled. This list is declared by setting the requirements attribute. Here is an example of an extension defining a requirements list:

class SampleExtension(Extension):
    requirements = ['other_extension.extension.OtherExtension']

    def __init__(self, *args, **kwargs):
        super(RBWebHooksExtension, self).__init__(*args, **kwargs)

Developing With a Python Egg¶

In order for Review Board to detect an extension, the Python Egg must be generated using the setup.py file, and installed. During development this can be done by installing a link in the Python installation to the source directory of your extension. This is accomplished by running:

python setup.py develop

If changes are made to the setup.py file this should be executed again.

See the Setuptools documentation for more information.