1 This file documents the contents of this module
3 See the devel/ subdir for more devel-oriented doc.
5 ==================== 1 minute howto
7 * REQUIREMENTS is to have python + django installed django
8 ** should be straightforward
9 ** see devel/django-install.txt in case of trouble
11 * git clone git://git.onelab.eu/myslice-django.git
13 * git clone ssh://yourlogin@git.onelab.eu/git/myslice-django.git
15 * edit myslice/settings.py and
16 ** change DEVELOPER_ROOT if you didnt clone into ~/git/myslice-django
17 ** change the location of your backend API (not yet supported)
22 [ at this point point it *might* be needed to run
24 but as far as running a local server is concerned you should be good without that
25 feedback on this is appreciated]
28 $ manage.py runserver 0.0.0.0:8000
30 * use it from your browser
33 ==================== Status
35 For now there's not much in here;
37 * Logging in should be easy using one of the few hard coded accounts
38 this was the simplest possible way to demonstrate deferring authorization elsewhere
39 * To logout, click on 'logged as *jean*', this shows a confirmation page..
42 Right now the UI has 4 views:
44 * the most useful one being the 'Plugin' view which demonstrates all the available plugins
45 see test_plugin_view in engine/views.py
47 * slice view : only demonstrates how to use URLs to pass arguments along
48 * scroll view : forget about that one, but it does illustrate that some pages can be made public (no need to login)
49 * tab view : a hand-made tab widget
50 (last three from slice/views.py)
53 Third party tools shipped:
59 not much effort has been put into coming up with a nice layout and all, feel free to tweak that but it's probably way too early for that
61 ==================== Contents: 1st level subdirs
63 ========== code from git
65 this is the django 'project', where to look for
70 the code for building / rendering plugins
73 the actual code for plugins
76 a django 'app' that deals with authentication; see especially
77 auth.backend.MyCustomBackend
78 for how to use a separate authentication system,
79 as well as settings.py for how to enable it
82 a django app for dealing with slice views
85 a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
88 * some global templates (django templates, i.e. (essentially html) fragments that can be specializied)
92 * third party stuff (bootstrapfs, jquery, datatables)
93 * + some global static files (css, js, images..)
94 see more about that below too
97 no code in there, only various notes and other scripts useful for developers
99 ========== automatically generated
101 * all-static: (generated, no need to source-control)
102 this is where 'manage.py collectstatic' will gather all your static contents if you run a local server
103 make has convenience targets to refresh this area
108 this is where django stores its own stuff, as per settings.py
111 ==================== conventions for templates and static
114 we store this under templates/ within the corresponding app, e.g.
115 auth/templates/login.html
116 for now this is mostly about html, but the engine can be used for rendering anything including js(on) or whatever..
119 we chose to have all static files (images, but also javascript and stylesheets) in the various
120 proj or app where they belong, under a static/ subdir that has this structure:
127 NOTE. in essence any of these files can be moved around (from e.g. one templates/ dir to another)
128 at any time without any change needed in the code
130 * filenames / locations
132 you can run the following make targets to have a summary of where things are
134 $ make list-html list-js list-css list-img
138 as far as possible it's great to have things named the same after e.g. say a plugin name
140 plugins/quickfilter.py
141 plugins/templates/quickfilter.html
142 plugins/static/js/quickfilter.js
143 plugins/static/css/quickfilter.css
145 it's sometimes not working though, so here are a few additional conventions
147 the global layout (for now I needed only one) is named layout-myslice.html
148 it provides the global layout with one menu stuck on top and 2 divs 3/4 1/4
150 the views that I currently have are all named in templates/view-<>.html
151 they all extend a layout
152 they should/could admittedly move where they belong (in auth/slice/engine)
153 so that they would go with their views.py code, but for now it's impler this way
155 and there are 3 'widgets' (login, logout, and topmenu)
156 these could maybe be best implemented as a plugin now that I have the right model for that
157 however esp. for the login/logout I'm not quite sure this will remain over time
158 so for now it's good enough like this
160 So in summary there's still room for a lot of improvement on this particular topic..
161 At the very least topmenu should be made a plugin, and maybe also login/logout