563908e2c0
* Clean up unnecessary vertical quotes at the left side caused by extra spaces at the beginning of lines. * Do not use backquotes in the title lines (ref/run_tests.rst, ref/horizon.rst) When backquotes are used in the first-level title, it will be included in the navigation at the top-right corner https://docs.openstack.org/developer/horizon/contributor/ref/index.html * Remove duplicated contents:: directive in ref/run_tests.sh. openstackdocstheme generates the toc by default, so having contents:: directive leads to duplicated toc in a page. Change-Id: Icc641927ad7cd7a8d79632c64a3ce212f0dc0b64
119 lines
4.3 KiB
ReStructuredText
119 lines
4.3 KiB
ReStructuredText
.. _contributor-intro:
|
|
|
|
==============
|
|
Horizon Basics
|
|
==============
|
|
|
|
Values
|
|
======
|
|
|
|
"Think simple" as my old master used to say - meaning reduce
|
|
the whole of its parts into the simplest terms, getting back
|
|
to first principles.
|
|
|
|
-- Frank Lloyd Wright
|
|
|
|
Horizon holds several key values at the core of its design and architecture:
|
|
|
|
* Core Support: Out-of-the-box support for all core OpenStack projects.
|
|
* Extensible: Anyone can add a new component as a "first-class citizen".
|
|
* Manageable: The core codebase should be simple and easy-to-navigate.
|
|
* Consistent: Visual and interaction paradigms are maintained throughout.
|
|
* Stable: A reliable API with an emphasis on backwards-compatibility.
|
|
* Usable: Providing an *awesome* interface that people *want* to use.
|
|
|
|
The only way to attain and uphold those ideals is to make it *easy* for
|
|
developers to implement those values.
|
|
|
|
History
|
|
=======
|
|
|
|
Horizon started life as a single app to manage OpenStack's compute project.
|
|
As such, all it needed was a set of views, templates, and API calls.
|
|
|
|
From there it grew to support multiple OpenStack projects and APIs gradually,
|
|
arranged rigidly into "dash" and "syspanel" groupings.
|
|
|
|
During the "Diablo" release cycle an initial plugin system was added using
|
|
signals to hook in additional URL patterns and add links into the "dash"
|
|
and "syspanel" navigation.
|
|
|
|
This incremental growth served the goal of "Core Support" phenomenally, but
|
|
left "Extensible" and "Manageable" behind. And while the other key values took
|
|
shape of their own accord, it was time to re-architect for an extensible,
|
|
modular future.
|
|
|
|
|
|
The Current Architecture & How It Meets Our Values
|
|
==================================================
|
|
|
|
At its core, **Horizon should be a registration pattern for
|
|
applications to hook into**. Here's what that means and how it is
|
|
implemented in terms of our values:
|
|
|
|
Core Support
|
|
------------
|
|
|
|
Horizon ships with three central dashboards, a "User Dashboard", a
|
|
"System Dashboard", and a "Settings" dashboard. Between these three they
|
|
cover the core OpenStack applications and deliver on Core Support.
|
|
|
|
The Horizon application also ships with a set of API abstractions
|
|
for the core OpenStack projects in order to provide a consistent, stable set
|
|
of reusable methods for developers. Using these abstractions, developers
|
|
working on Horizon don't need to be intimately familiar with the APIs of
|
|
each OpenStack project.
|
|
|
|
Extensible
|
|
----------
|
|
|
|
A Horizon dashboard application is based around the :class:`~horizon.Dashboard`
|
|
class that provides a consistent API and set of capabilities for both
|
|
core OpenStack dashboard apps shipped with Horizon and equally for third-party
|
|
apps. The :class:`~horizon.Dashboard` class is treated as a top-level
|
|
navigation item.
|
|
|
|
Should a developer wish to provide functionality within an existing dashboard
|
|
(e.g. adding a monitoring panel to the user dashboard) the simple registration
|
|
pattern makes it possible to write an app which hooks into other dashboards
|
|
just as easily as creating a new dashboard. All you have to do is import the
|
|
dashboard you wish to modify.
|
|
|
|
Manageable
|
|
----------
|
|
|
|
Within the application, there is a simple method for registering a
|
|
:class:`~horizon.Panel` (sub-navigation items). Each panel contains the
|
|
necessary logic (views, forms, tests, etc.) for that interface. This granular
|
|
breakdown prevents files (such as ``api.py``) from becoming thousands of
|
|
lines long and makes code easy to find by correlating it directly to the
|
|
navigation.
|
|
|
|
Consistent
|
|
----------
|
|
|
|
By providing the necessary core classes to build from, as well as a
|
|
solid set of reusable templates and additional tools (base form classes,
|
|
base widget classes, template tags, and perhaps even class-based views)
|
|
we can maintain consistency across applications.
|
|
|
|
Stable
|
|
------
|
|
|
|
By architecting around these core classes and reusable components we
|
|
create an implicit contract that changes to these components will be
|
|
made in the most backwards-compatible ways whenever possible.
|
|
|
|
Usable
|
|
------
|
|
|
|
Ultimately that's up to each and every developer that touches the code,
|
|
but if we get all the other goals out of the way then we are free to focus
|
|
on the best possible experience.
|
|
|
|
.. seealso::
|
|
|
|
* :ref:`quickstart` A short guide to getting started with using Horizon.
|
|
* :ref:`faq` Common questions and answers.
|
|
* :ref:`glossary` Common terms and their definitions.
|