README

   1 his 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
  24 * gather static files
  25 $ make static
  26
  27 * run a local server:
  28 $ manage.py runserver 0.0.0.0:8000
  29 -- or -- my advice:
  30 $ devel/server-loop.sh
  31 when you just need to hit ^C yourself when your static files need to be refreshed - see below
  32
  33 * use it from your browser
  34
  35 .......... NOTES on using the development server
  36 . first off, running manage.py runserver is provided by django as a development convenience but SHOULD NOT be used in production
  37 . second, when you do use it for developement purposes, please be aware that:
  38 .. the recommended layout for the various files and pieces (py, html, js and css) qith django is really painful
  39    we should use e.g. plugins/simplelist.py, plugins/templates/plugins.html, plugins/static/js/simplelist.js and plugins/static/css/simplelist.css
  40 .. as that does not make sense IMHO, I've rewritten the tool for gathering these pieces in such a layout but from a completely flat codebase
  41    I mean I want to be able to store all the files building a plugin in a single (git) directory
  42    Of course it's a completely different matter once the service is packaged and installed, these files of course get properly separated.
  43 .. as a result it is a little bit less convenient to use the development server
  44    when you change the layout of your static and template files, you might need to re-run 'make static', so it is recommended to use
  45    devel/server-loop.sh instead
  46
  47
  48 ==================== Status
  49
  50 *** Authentication ***
  51
  52 Although there still are a few hard-coded accounts in the system, you
  53 will only be able to see some static views and won't be able to send
  54 real queries if you use these, so you'd better use a real account (one
  55 that your manifold backend knows about).
  56
  57 For logging out: click on 'logged as *jean*', this shows a
  58 confirmation page for logging out. this is intended to be temporary.
  59
  60
  61 *** Features ***
  62
  63 We have a basic model for asynchroneous queries (referring to manifold
  64 queries) and for plugins (in the most general sense a plugin is just a
  65 piece of the output that may be connected to a query)
  66
  67 Right now the UI has a handful of demo views only; as of this writing
  68 only the list of slices actually comes from the manifold backend in an
  69 asynchroneous way.
  70
  71 Also all the views are gathered in the trash/ locations for now, being
  72 that they're only for assessment purposes.
  73
  74 * dahsboard : has one async. query and 2 plugins that share that
  75   query; the intent was to demo a different layout in both cases,
  76   although the datatables one won't work yet at this point.
  77
  78 * the 'Plugin' view demonstrates most of the available plugins.
  79
  80 * slice view : only demonstrates how to use URLs to pass arguments along
  81
  82 * scroll view : mostly it only illustrates that some pages can be made
  83   public (no need to login)
  84
  85 * tab view : a hand-made tab widget
  86
  87 Not much effort has yet been put into coming up with a nice layout,
  88 feel free to tweak that but it's probably still way too early for
  89 this.
  90
  91 ====================
  92
  93 Third party tools shipped:
  94
  95 * jquery
  96 * datatables
  97 * spin
  98 * bootstrap
  99
 100 I've tried to keep track of the version I picked and to have an easy upgrade path.
 101
 102 ==================== Contents: 1st level subdirs
 103
 104 ========== code from git
 105 * myslice:
 106   this is the django 'project', where to look for
 107   . settings.py
 108   . urls.py
 109
 110 * engine:
 111   the code for building / rendering plugins / queries
 112
 113 * plugins:
 114   the actual code for plugins
 115
 116 * auth:
 117   a django 'app' that deals with authentication; see especially
 118   auth.backend.MyCustomBackend
 119   for how to use a separate authentication system,
 120   as well as settings.py for how to enable it
 121
 122 * insert_above:
 123   a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
 124
 125 * trash/
 126   rough/preliminary views in here - as the name suggests this is temporary
 127
 128 * views/
 129   will receive actual views over time
 130   currently has some global html templates as well
 131
 132 * third-party/
 133    * third party stuff (bootstrapfs, jquery, datatables)
 134    * + some global static files (css, js, images..)
 135      see more about that below too
 136
 137 * devel:
 138   no code in there, only various notes and other scripts useful for developers
 139
 140 ========== automatically generated
 141
 142 * all-static: (generated, no need to source-control)
 143   this is where 'make static' will gather all your static contents if you run a local server
 144   make has convenience targets to refresh this area
 145   $ make static
 146   $ make clean-static
 147
 148 * myslice.sqlite3
 149   this is where django stores its own stuff, as per settings.py
 150
 151 ==================== conventions for templates
 152
 153 * templates:
 154   we store this under templates/ within the corresponding app, e.g.
 155   auth/templates/login.html
 156   for now this is mostly about html, but the engine can be used for rendering anything
 157   including js(on) or whatever..
 158
 159 ==================== conventions for static files
 160
 161 * static files:
 162   we chose to have all static files (images, but also javascript and stylesheets) in the various
 163   proj or app where they belong, under a static/ subdir that has this structure:
 164   where-it-belongs/
 165       img/
 166       css/
 167       js/
 168
 169 * filenames / locations
 170
 171   you can run the following make targets to have a summary of where things are
 172
 173   $ make list-html list-js list-css list-img
 174   -- or --
 175   $ make list-all
 176
 177
 178 * plugins
 179   use a naming scheme as simple as possible
 180     like e.g.
 181     plugins/quickfilter/quickfilter.py
 182     plugins/quickfilter/quickfilter.html
 183     plugins/quickfilter/quickfilter.js
 184     plugins/quickfilter/quickfilter.css
 185
 186