Tutorial: Creating an Horizon Plugin

Why should I package my code as a plugin?

We highly encourage that you write and maintain your code using our plugin architecture. A plugin by definition means the ability to be connected. In practical terms, plugins are a way to extend and add to the functionality that already exists. You can control its content and progress at a rate independent of Horizon. If you write and package your code as a plugin, it will continue to work in future releases.

Writing your code as a plugin also modularizes your code making it easier to translate and test. This also makes it easier for deployers to consume your code allowing selective enablement of features. We are currently using this pattern internally for our dashboards.

Creating the Plugin

This tutorial assumes you have a basic understanding of Python, HTML, JavaScript. Knowledge of AngularJS is optional but recommended if you are attempting to create an Angular plugin.

Name of your repository

Needless to say, it is important to choose a meaningful repository name.

In addition, if you plan to support translation on your dashboard plugin, it is recommended to choose a name like xxxx-dashboard (or xxxx-ui. xxxx-horizon). The OpenStack CI infra script considers a repository with these suffixes as Django project.

Types of Plugins that add content

The file structure for your plugin type will be different depending on your needs. Your plugin can be categorized into two types:

• Plugins that create new panels or dashboards

• Plugins that modify existing workflows, actions, etc… (Angular only)

We will cover the basics of working with panels for both Python and Angular. If you are interested in creating a new panel, follow the steps below.

Note

This tutorial shows you how to create a new panel. If you are interested in creating a new dashboard plugin, use the file structure from Tutorial: Building a Dashboard using Horizon instead.

File Structure

Below is a skeleton of what your plugin should look like.:

myplugin
│
├── myplugin
│   ├── __init__.py
│   │
│   ├── enabled
│   │   └──_31000_myplugin.py
│   │
│   ├── api
│   │   ├──__init__.py
│   │   ├── my_rest_api.py
│   │   └── myservice.py
│   │
│   ├── content
│   │   ├──__init__.py
│   │   └── mypanel
│   │       ├── __init__.py
│   │       ├── panel.py
│   │       ├── tests.py
│   │       ├── urls.py
│   │       ├── views.py
│   │       └── templates
│   │           └── mypanel
│   │               └── index.html
│   │
│   └── static
│   |   └── dashboard
│   |       └── identity
│   |           └── myplugin
│   |               └── mypanel
│   |                   ├── mypanel.html
│   |                   ├── mypanel.js
│   |                   └── mypanel.scss
│   │
│   └── locale
│       └── <lang>
│            └── LC_MESSAGES
│                ├── django.po
│                └── djangojs.po
│
├── setup.py
├── setup.cfg
├── LICENSE
├── MANIFEST.in
├── README.rst
├── babel-django.cfg
└── babel-djangojs.cfg

If you are creating a Python plugin, you may ignore the static folder. Most of the classes you need are provided for in Python. If you intend on adding custom front-end logic, you will need to include additional JavaScript here.

An AngularJS plugin is a collection of JavaScript files or static resources. Because it runs entirely in your browser, we need to place all of our static resources inside the static folder. This ensures that the Django static collector picks it up and distributes it to the browser correctly.

The Enabled File

The enabled folder contains the configuration file(s) that registers your plugin with Horizon. The file is prefixed with an alpha-numeric string that determines the load order of your plugin. For more information on what you can include in this file, see pluggable settings in Settings Reference.

_31000_myplugin.py:

# The name of the panel to be added to HORIZON_CONFIG. Required.
PANEL = 'mypanel'

# The name of the dashboard the PANEL associated with. Required.
PANEL_DASHBOARD = 'identity'

# Python panel class of the PANEL to be added.
ADD_PANEL = 'myplugin.content.mypanel.panel.MyPanel'

# A list of applications to be prepended to INSTALLED_APPS
ADD_INSTALLED_APPS = ['myplugin']

# A list of AngularJS modules to be loaded when Angular bootstraps.
ADD_ANGULAR_MODULES = ['horizon.dashboard.identity.myplugin.mypanel']

# Automatically discover static resources in installed apps
AUTO_DISCOVER_STATIC_FILES = True

# A list of js files to be included in the compressed set of files
ADD_JS_FILES = []

# A list of scss files to be included in the compressed set of files
ADD_SCSS_FILES = ['dashboard/identity/myplugin/mypanel/mypanel.scss']

# A list of template-based views to be added to the header
ADD_HEADER_SECTIONS = ['myplugin.content.mypanel.views.HeaderView',]

Note

Currently, AUTO_DISCOVER_STATIC_FILES = True will only discover JavaScript files, not SCSS files.

my_rest_api.py

This file will likely be necessary if creating a plugin using Angular. Your plugin will need to communicate with a new service or require new interactions with a service already supported by Horizon. In this particular example, the plugin will augment the support for the already supported Identity service, Keystone. This file serves to define new REST interfaces for the plugin’s client-side to communicate with Horizon. Typically, the REST interfaces here make calls into myservice.py.

This file is unnecessary in a purely Django based plugin, or if your Angular based plugin is relying on CORS support in the desired service. For more information on CORS, see https://docs.openstack.org/oslo.middleware/latest/admin/cross-project-cors.html

myservice.py

This file will likely be necessary if creating a Django or Angular driven plugin. This file is intended to act as a convenient location for interacting with the new service this plugin is supporting. While interactions with the service can be handled in the views.py, isolating the logic is an established pattern in Horizon.

panel.py

We define a panel where our plugin’s content will reside in. This is currently a necessity even for Angular plugins. The slug is the panel’s unique identifier and is often use as part of the URL. Make sure that it matches what you have in your enabled file.:

from django.utils.translation import gettext_lazy as _
import horizon


class MyPanel(horizon.Panel):
    name = _("My Panel")
    slug = "mypanel"

tests.py

Write some tests for the Django portion of your plugin and place them here.

urls.py

Now that we have a panel, we need to provide a URL so that users can visit our new panel! This URL generally will point to a view.:

from django.urls import re_path

from myplugin.content.mypanel import views

urlpatterns = [
    re_path(r'^$', views.IndexView.as_view(), name='index'),
]

views.py

Because rendering is done client-side, all our view needs is to reference some HTML page. If you are writing a Python plugin, this view can be much more complex. Refer to the topic guides for more details.:

from django.views import generic


class IndexView(generic.TemplateView):
    template_name = 'identity/mypanel/index.html'

index.html

The index HTML is where rendering occurs. In this example, we are only using Django. If you are interested in using Angular directives instead, read the AngularJS section below.:

{% extends 'base.html' %}
{% load i18n %}
{% block title %}{% trans "My plugin" %}{% endblock %}

{% block page_header %}
  {% include "horizon/common/_domain_page_header.html" with title=_("My Panel") %}
{% endblock page_header %}

{% block main %}
  Hello world!
{% endblock %}

At this point, you have a very basic plugin. Note that new templates are required to extend base.html. Including base.html is important for a number of reasons. It is the template that contains all of your static resources along with any functionality external to your panel (things like navigation, context selection, etc…). As of this moment, this is also true for Angular plugins.

MANIFEST.in

This file is responsible for listing the paths you want included in your tar.:

include setup.py

recursive-include myplugin *.js *.html *.scss

setup.py

import setuptools

setuptools.setup(
    setup_requires=['pbr>=2.0.0'],
    pbr=True)

setup.cfg

[metadata]
name = myplugin
summary = A panel plugin for OpenStack Dashboard
description_file =
    README.rst
author = myname
author_email = myemail
home_page = __REPLACE_YOUR_PLGUIN_HOMEPAGE_URL__
classifier =
    Environment :: OpenStack
    Framework :: Django
    Intended Audience :: Developers
    Intended Audience :: System Administrators
    License :: OSI Approved :: Apache Software License
    Operating System :: POSIX :: Linux
    Programming Language :: Python
    Programming Language :: Python :: 3 :: Only
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.6
    Programming Language :: Python :: 3.7
    Programming Language :: Python :: 3.8
    Programming Language :: Python :: 3.9

[files]
packages =
    myplugin

AngularJS Plugin

If you have no plans to add AngularJS to your plugin, you may skip this section. In the tutorial below, we will show you how to customize your panel using Angular.

index.html

The index HTML is where rendering occurs and serves as an entry point for Angular. This is where we start to diverge from the traditional Python plugin. In this example, we use a Django template as the glue to our Angular template. Why are we going through a Django template for an Angular plugin? Long story short, base.html contains the navigation piece that we still need for each panel.

{% extends 'base.html' %}
{% load i18n %}
{% block title %}{% trans "My panel" %}{% endblock %}

{% block page_header %}
  <hz-page-header
    header="{$ 'My panel' | translate $}"
    description="{$ 'My custom panel!' | translate $}">
  </hz-page-header>
{% endblock page_header %}

{% block main %}
  <ng-include src="'{{ STATIC_URL }}dashboard/identity/myplugin/mypanel/mypanel.html'">
  </ng-include>
{% endblock %}

This template contains both Django and AngularJS code. Angular is denoted by {$..$} while Django is denoted by {{..}} and {%..%}. This template gets processed twice, once by Django on the server-side and once more by Angular on the client-side. This means that the expressions in {{..}} and {%..%} are substituted with values by the time it reaches your Angular template.

What you chose to include in block main is entirely up to you. Since you are creating an Angular plugin, we recommend that you keep everything in this section Angular. Do not mix Python code in here! If you find yourself passing in Python data, do it via our REST services instead.

Remember to always use STATIC_URL when referencing your static resources. This ensures that changes to the static path in settings will continue to serve your static resources properly.

Note

Angular’s directives are prefixed with ng. Similarly, Horizon’s directives are prefixed with hz. You can think of them as namespaces.

mypanel.js

Your controller is the glue between the model and the view. In this example, we are going to give it some fake data to render. To load more complex data, consider using the $http service.

(function() {
  'use strict';

  angular
    .module('horizon.dashboard.identity.myplugin.mypanel', [])
    .controller('horizon.dashboard.identity.myPluginController',
      myPluginController);

  myPluginController.$inject = [ '$http' ];

  function myPluginController($http) {
    var ctrl = this;
    ctrl.items = [
      { name: 'abc', id: 123 },
      { name: 'efg', id: 345 },
      { name: 'hij', id: 678 }
    ];
  }
})();

This is a basic example where we mocked the data. For exercise, load your data using the $http service.

mypanel.html

This is our view. In this example, we are looping through the list of items provided by the controller and displaying the name and id. The important thing to note is the reference to our controller using the ng-controller directive.

<div ng-controller="horizon.dashboard.identity.myPluginController as ctrl">
  <div>Loading data from your controller:</div>
  <ul>
    <li ng-repeat="item in ctrl.items">
      <span class="c1">{$ item.name $}</span>
      <span class="c2">{$ item.id $}</span>
    </li>
  </ul>
</div>

mypanel.scss

You can choose to customize your panel by providing your own scss. Be sure to include it in your enabled file via the ADD_SCSS_FILES setting.

Translation Support

A general instruction on how to enable translation support is described in the Infrastructure User Manual [1].

This section describes topics specific to Horizon plugins.

ADD_INSTALLED_APPS

Be sure to include <modulename> (myplugin in this example) in ADD_INSTALLED_APPS in the corresponding enabled file.

• If you are preparing a new plugin, you will use <modulename> as INSTALLED_APPS in most cases as suggested in this tutorial. This is good and there is nothing more to do.

• If for some reason your plugin needs to register other python modules to ADD_INSTALLED_APPS, ensure that you include its <modulename> additionally.

This comes from the combination of the following two reasons.

• Django looks for translation message catalogs from each path specified in INSTALLED_APPS [2].

• OpenStack infra scripts assumes translation message catalogs are placed under <modulename>/locale (for example myplugin/locale).

[1]

https://docs.openstack.org/infra/manual/creators.html#enabling-translation-infrastructure

[2]

https://docs.djangoproject.com/es/1.9/topics/i18n/translation/#how-django-discovers-translations

myplugin/locale

Translated message catalog files (PO files) are placed under this directory.

babel-django.cfg, babel-djangojs.cfg

These files are used to extract messages by pybabel: babel-django.cfg for python code and template files, and babel-djangojs.cfg for JavaScript files.

They are required to enable translation support by OpenStack CI infra. If they do not exist, the translation jobs will skip processing for your project.

Installing Your Plugin

Now that you have a complete plugin, it is time to install and test it. The instructions below assume that you have a working plugin.

• plugin is the location of your plugin

• horizon is the location of horizon

• package is the complete name of your packaged plugin

1. Run “cd plugin & python setup.py sdist”

2. Run “cp -rv enabled horizon/openstack_dashboard/local/”

3. Run “horizon/tools/with_venv.sh pip install dist/package.tar.gz”

4. Restart Apache or your Django test server

Note

Step 3 installs your package into the Horizon’s virtual environment. You can install your plugin without using with_venv.sh and pip. The package would simply be installed in the PYTHON_PATH of the system instead.

If you are able to hit the URL pattern in urls.py in your browser, you have successfully deployed your plugin! For plugins that do not have a URL, check that your static resources are loaded using the browser inspector.

Assuming you implemented my_rest_api.py, you can use a REST client to hit the url directly and test it. There should be many REST clients available on your web browser.

Note that you may need to rebuild your virtual environment if your plugin is not showing up properly. If your plugin does not show up properly, check your .tox folder to make sure the plugin’s content is as you expect.

Note

To uninstall, use pip uninstall. You will also need to remove the enabled file from the local/enabled folder.