src/ceph/src/pybind/mgr/dashboard/HACKING.rst

   1
   2 HACKING
   3 =======
   4
   5 See the top-level docs in the ceph repository for general information about how to submit code.  This
   6 file is about the specifics of how this module fits together.
   7
   8 This module uses deliberately simple/explicit structure so that it is accessbile
   9 to people who are not specialists in webapps.  Very little javascript knowledge
  10 is needed.  The absence of a javascript toolchain (node, bower, grunt, etc) is
  11 considered a feature rather than a bug.  All of the CSS and Javascript in
  12 the git repository is used as-is without any compilation/minification.
  13
  14 On the server (i.e. python-side)
  15 --------------------------------
  16
  17 In the serve() method, there's a cherrypy request handler object with methods that correspond to URLs.
  18 See the cherrypy documentatino for how that stuff works.
  19
  20 There is a mixture of endpoints that return JSON (for live updates of pages) and endpoints that return
  21 HTML (for initial loads of pages).  The HTML files are rendered from jinja2 templates (the .html files
  22 in the source tree).
  23
  24 The initial render of the HTML template includes some json-ized inline data, so that the page can
  25 be rendered immediately without having to make another request to the server to load the data
  26 after loading the markup.
  27
  28 The pattern is that for some resource 'foo' we would generally have three methods, along the lines of:
  29
  30 ::
  31
  32     def _foo(self):
  33         return {...the data of interest...}
  34
  35     @cherrypy.expose
  36     def foo(self):
  37         data = self._foo()
  38         *render a foo.html template with data inline*
  39
  40     @cherrypy.expose
  41     @cherrypy.tools.json_out()
  42     def foo_data(self):
  43         return self._foo()
  44
  45 In the browser (Javascript and markup)
  46 --------------------------------------
  47
  48 The javascript code uses the rivets.js (http://rivetsjs.com/) library to render the data from
  49 the server into HTML templates, and to enable subsequent updates without reloading the whole
  50 page.
  51
  52 The use of rivets.js looks something like this:
  53
  54 ::
  55
  56     <tr rv-each-server="servers">
  57         <td>
  58             {server.hostname}
  59         </td>
  60
  61 The "rv-each" attributes do iteration over lists, and the curly braces substitute
  62 values into place.  See the rivets docs for more.
  63
  64 If you see double-curly-brace items in the markup, those are the ones that
  65 were populated server side, including the initial data, like this:
  66
  67 ::
  68
  69      var content_data = {{ content_data }};
  70
  71 If you really wanted to, you could skip rivets on any given page, and just
  72 render the whole page server-side with ``{{}}`` entries, but that of course
  73 leaves you with a page that won't update without the user actively refreshing.
  74
  75 The common markup such as headers and footers lives in ``base.html``, and
  76 all the other pages' templates start with ``{% extends "base.html" %}``.  This
  77 is jinja2 syntax that is handled server-side.
  78
  79 Styles/CSS
  80 ----------
  81
  82 This module includes the AdminLTE dashboard layout.  This is perhaps overkill,
  83 but saves us from writing any significant amount of CSS.  If you need to fudge
  84 something, don't be shy about putting "style=" attributes inline within reason.
  85
  86 URLs
  87 ----
  88
  89 The URLs follow a convention that CherryPy knows how to route for us: the
  90 name of the handler function, followed by positional arguments between
  91 slashes.  For example, a handler like ``def filesystem(self, fscid)`` is
  92 automatically called on requests like ``/filesystem/123```
  93
  94
  95