README

   1 This file documents the contents of this module
   2
   3 See the devel/ subdir for more devel-oriented doc.
   4
   5 ==================== 1 minute howto
   6
   7 *  REQUIREMENTS  is to have python + django installed django
   8 ** should be straightforward
   9 ** see devel/django-install.txt in case of trouble
  10
  11 * git clone git://git.onelab.eu/myslice-django.git
  12 -- or --
  13 * git clone ssh://yourlogin@git.onelab.eu/git/myslice-django.git
  14
  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)
  18
  19 * edit myslice/config.py and enter the details of your manifold backend
  20
  21 * init django
  22 $ manage.py syncdb
  23 [[ at this point point it *might* be needed to run
  24 $ make allst
  25  but as far as running a local server is concerned you should be good without that
  26  feedback on this is appreciated]]
  27
  28 * run a local server:
  29 $ manage.py runserver 0.0.0.0:8000
  30
  31 * use it from your browser
  32
  33
  34 ==================== Status
  35
  36 *** Authentication ***
  37
  38 Although there still are a few hard-coded accounts in the system, you
  39 will only be able to see some static views and won't be able to send
  40 real queries if you use these, so you'd better use a real account (one
  41 that your manifold backend knows about).
  42
  43 For logging out: click on 'logged as *jean*', this shows a
  44 confirmation page for logging out. this is intended to be temporary.
  45
  46
  47 *** Features ***
  48
  49 We have a basic model for asynchroneous queries (referring to manifold
  50 queries) and for plugins (in the most general sense a plugin is just a
  51 piece of the output that may be connected to a query)
  52
  53 Right now the UI has a handful of demo views only; as of this writing
  54 only the list of slices actually comes from the manifold backend in an
  55 asynchroneous way.
  56
  57 Also all the views are gathered in the trash/ locations for now, being
  58 that they're only for assessment purposes.
  59
  60 * dahsboard : has one async. query and 2 plugins that share that
  61   query; the intent was to demo a different layout in both cases,
  62   although the datatables one won't work yet at this point.
  63
  64 * the 'Plugin' view demonstrates most of the available plugins.
  65
  66 * slice view : only demonstrates how to use URLs to pass arguments along
  67
  68 * scroll view : mostly it only illustrates that some pages can be made
  69   public (no need to login)
  70
  71 * tab view : a hand-made tab widget
  72
  73 Not much effort has yet been put into coming up with a nice layout,
  74 feel free to tweak that but it's probably still way too early for
  75 this.
  76
  77 ====================
  78
  79 Third party tools shipped:
  80
  81 * jquery
  82 * datatables
  83 * spin
  84 * bootstrap
  85
  86 I've tried to keep track of the version I picked and to have an easy upgrade path.
  87
  88 ==================== Contents: 1st level subdirs
  89
  90 ========== code from git
  91 * myslice:
  92   this is the django 'project', where to look for
  93   . settings.py
  94   . urls.py
  95
  96 * engine:
  97   the code for building / rendering plugins / queries
  98
  99 * plugins:
 100   the actual code for plugins
 101
 102 * auth:
 103   a django 'app' that deals with authentication; see especially
 104   auth.backend.MyCustomBackend
 105   for how to use a separate authentication system,
 106   as well as settings.py for how to enable it
 107
 108 * insert_above:
 109   a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
 110
 111 * templates/
 112    * some global templates (django templates, i.e. (essentially html) fragments that can be specializied)
 113      more on this below
 114
 115 * static/
 116    * third party stuff (bootstrapfs, jquery, datatables)
 117    * + some global static files (css, js, images..)
 118      see more about that below too
 119
 120 * devel:
 121   no code in there, only various notes and other scripts useful for developers
 122
 123 ========== automatically generated
 124
 125 * all-static: (generated, no need to source-control)
 126   this is where 'manage.py collectstatic' will gather all your static contents if you run a local server
 127   make has convenience targets to refresh this area
 128   $ make clean-static
 129   $ make static
 130
 131 * myslice.sqlite3
 132   this is where django stores its own stuff, as per settings.py
 133
 134
 135 ==================== conventions for templates and static
 136
 137 * templates:
 138   we store this under templates/ within the corresponding app, e.g.
 139   auth/templates/login.html
 140   for now this is mostly about html, but the engine can be used for rendering anything including js(on) or whatever..
 141
 142 * static files:
 143   we chose to have all static files (images, but also javascript and stylesheets) in the various
 144   proj or app where they belong, under a static/ subdir that has this structure:
 145   where-it-belongs/
 146     static/
 147       img/
 148       css/
 149       js/
 150
 151 NOTE. in essence any of these files can be moved around (from e.g. one templates/ dir to another)
 152 at any time without any change needed in the code
 153
 154 * filenames / locations
 155
 156   you can run the following make targets to have a summary of where things are
 157
 158   $ make list-html list-js list-css list-img
 159   -- or --
 160   $ make list-all
 161
 162   as far as possible it's great to have things named the same after e.g. say a plugin name
 163     like e.g.
 164     plugins/quickfilter.py
 165     plugins/templates/quickfilter.html
 166     plugins/static/js/quickfilter.js
 167     plugins/static/css/quickfilter.css
 168
 169   it's sometimes not working though, so here are a few additional conventions
 170
 171     the global layout (for now I needed only one) is named layout-myslice.html
 172       it provides the global layout with one menu stuck on top and 2 divs 3/4 1/4
 173
 174     the views that I currently have are all named in templates/view-<>.html
 175       they all extend a layout
 176       they should/could admittedly move where they belong (in auth/slice/engine)
 177       so that they would go with their views.py code, but for now it's impler this way
 178
 179     and there are 3 'widgets' (login, logout, and topmenu)
 180       these could maybe be best implemented as a plugin now that I have the right model for that
 181       however esp. for the login/logout I'm not quite sure this will remain over time
 182       so for now it's good enough like this
 183
 184 So in summary there's still room for a lot of improvement on this particular topic..
 185 At the very least topmenu should be made a plugin, and maybe also login/logout