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 * init django
  20 $ manage.py syncdb
  21
  22 [ at this point point it *might* be needed to run
  23 $ make allst
  24  but as far as running a local server is concerned you should be good without that
  25  feedback on this is appreciated]
  26
  27 * run a local server:
  28 $ manage.py runserver 0.0.0.0:8000
  29
  30 * use it from your browser
  31
  32
  33 ==================== Status
  34
  35 For now there's not much in here;
  36
  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..
  40
  41
  42 Right now the UI has 4 views:
  43
  44 * the most useful one being the 'Plugin' view which demonstrates all the available plugins
  45   see test_plugin_view in engine/views.py
  46
  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)
  51
  52
  53 Third party tools shipped:
  54
  55 * jquery
  56 * datatables
  57 * bootstrap
  58
  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
  60
  61 ==================== Contents: 1st level subdirs
  62
  63 ========== code from git
  64 * myslice:
  65   this is the django 'project', where to look for
  66   . settings.py
  67   . urls.py
  68
  69 * engine:
  70   the code for building / rendering plugins
  71
  72 * plugins:
  73   the actual code for plugins
  74
  75 * auth:
  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
  80
  81 * slice:
  82   a django app for dealing with slice views
  83
  84 * insert_above:
  85   a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
  86
  87 * templates/
  88    * some global templates (django templates, i.e. (essentially html) fragments that can be specializied)
  89      more on this below
  90
  91 * static/
  92    * third party stuff (bootstrapfs, jquery, datatables)
  93    * + some global static files (css, js, images..)
  94      see more about that below too
  95
  96 * devel:
  97   no code in there, only various notes and other scripts useful for developers
  98
  99 ========== automatically generated
 100
 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
 104   $ make clean-static
 105   $ make static
 106
 107 * myslice.sqlite3
 108   this is where django stores its own stuff, as per settings.py
 109
 110
 111 ==================== conventions for templates and static
 112
 113 * templates:
 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..
 117
 118 * static files:
 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:
 121   where-it-belongs/
 122     static/
 123       img/
 124       css/
 125       js/
 126
 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
 129
 130 * filenames / locations
 131
 132   you can run the following make targets to have a summary of where things are
 133
 134   $ make list-html list-js list-css list-img
 135   -- or --
 136   $ make list-all
 137
 138   as far as possible it's great to have things named the same after e.g. say a plugin name
 139     like e.g.
 140     plugins/quickfilter.py
 141     plugins/templates/quickfilter.html
 142     plugins/static/js/quickfilter.js
 143     plugins/static/css/quickfilter.css
 144
 145   it's sometimes not working though, so here are a few additional conventions
 146
 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
 149
 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
 154
 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
 159
 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