]>
Commit | Line | Data |
---|---|---|
31f18b77 FG |
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 |