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 * static/
  89   some global stuff:
  90    * templates (django templates, i.e. (essentially html) fragments that can be specializied)
  91    * static files (css, js, images..)
  92   see more about that below
  93
  94 * devel:
  95   no code in there, only various notes and other scripts useful for developers
  96
  97 ========== automatically generated
  98
  99 * all-static: (generated, no need to source-control)
 100   this is where 'manage.py collectstatic' will gather all your static contents if you run a local server
 101   make has convenience targets to refresh this area
 102   $ make clean-static
 103   $ make static
 104
 105 * myslice.sqlite3
 106   this is where django stores its own stuff, as per settings.py
 107
 108
 109 ==================== conventions for templates and static
 110
 111 * templates:
 112   we store this under templates/ within the corresponding app, e.g.
 113   auth/templates/login.html
 114   for now this is mostly about html, but the engine can be used for rendering anything including js(on) or whatever..
 115
 116 * static files:
 117   we chose to have all static files (images, but also javascript and stylesheets) in the various
 118   proj or app where they belong, under a static/ subdir that has this structure:
 119   where-it-belongs/
 120     static/
 121       img/
 122       css/
 123       js/
 124
 125
 126 NOTE. in essence any of these files can be moved around (from e.g. one templates/ dir to another)
 127 at any time without any change needed in the code
 128