This file documents the contents of this module

See the devel/ subdir for more devel-oriented doc.

==================== 1 minute howto

*  REQUIREMENTS  is to have python + django installed django
** should be straightforward
** see devel/django-install.txt in case of trouble

* git clone git://git.onelab.eu/myslice-django.git
-- or --
* git clone ssh://yourlogin@git.onelab.eu/git/myslice-django.git

* edit myslice/settings.py and
** change DEVELOPER_ROOT if you didnt clone into ~/git/myslice-django
** change the location of your backend API (not yet supported)

* init django
$ manage.py syncdb

[ at this point point it *might* be needed to run
$ make allst
 but as far as running a local server is concerned you should be good without that 
 feedback on this is appreciated]

* run a local server:
$ manage.py runserver 0.0.0.0:8000

* use it from your browser 


==================== Status

For now there's not much in here; 

* Logging in should be easy using one of the few hard coded accounts
  this was the simplest possible way to demonstrate deferring authorization elsewhere
* To logout, click on 'logged as *jean*', this shows a confirmation page..


Right now the UI has 4 views: 

* the most useful one being the 'Plugin' view which demonstrates all the available plugins
  see test_plugin_view in engine/views.py

* slice view : only demonstrates how to use URLs to pass arguments along
* scroll view : forget about that one, but it does illustrate that some pages can be made public (no need to login)
* tab view : a hand-made tab widget
(last three from slice/views.py)


Third party tools shipped:

* jquery
* datatables
* bootstrap

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

==================== Contents: 1st level subdirs

========== code from git
* myslice: 
  this is the django 'project', where to look for
  . settings.py
  . urls.py

* engine:
  the code for building / rendering plugins

* plugins:
  the actual code for plugins

* auth: 
  a django 'app' that deals with authentication; see especially
  auth.backend.MyCustomBackend 
  for how to use a separate authentication system, 
  as well as settings.py for how to enable it

* slice:
  a django app for dealing with slice views

* insert_above: 
  a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header

* templates/
   * some global templates (django templates, i.e. (essentially html) fragments that can be specializied)
     more on this below

* static/
   * third party stuff (bootstrapfs, jquery, datatables)
   * + some global static files (css, js, images..)
     see more about that below too

* devel:
  no code in there, only various notes and other scripts useful for developers

========== automatically generated 

* all-static: (generated, no need to source-control)
  this is where 'manage.py collectstatic' will gather all your static contents if you run a local server
  make has convenience targets to refresh this area
  $ make clean-static 
  $ make static 

* myslice.sqlite3
  this is where django stores its own stuff, as per settings.py


==================== conventions for templates and static

* templates:
  we store this under templates/ within the corresponding app, e.g.
  auth/templates/login.html
  for now this is mostly about html, but the engine can be used for rendering anything including js(on) or whatever..

* static files:
  we chose to have all static files (images, but also javascript and stylesheets) in the various
  proj or app where they belong, under a static/ subdir that has this structure:
  where-it-belongs/
    static/
      img/
      css/
      js/

NOTE. in essence any of these files can be moved around (from e.g. one templates/ dir to another) 
at any time without any change needed in the code

* filenames / locations

  you can run the following make targets to have a summary of where things are

  $ make list-html list-js list-css list-img
  -- or --
  $ make list-all

  as far as possible it's great to have things named the same after e.g. say a plugin name
    like e.g.
    plugins/quickfilter.py
    plugins/templates/quickfilter.html
    plugins/static/js/quickfilter.js
    plugins/static/css/quickfilter.css

  it's sometimes not working though, so here are a few additional conventions

    the global layout (for now I needed only one) is named layout-myslice.html
      it provides the global layout with one menu stuck on top and 2 divs 3/4 1/4

    the views that I currently have are all named in templates/view-<>.html
      they all extend a layout
      they should/could admittedly move where they belong (in auth/slice/engine) 
      so that they would go with their views.py code, but for now it's impler this way

    and there are 3 'widgets' (login, logout, and topmenu) 
      these could maybe be best implemented as a plugin now that I have the right model for that
      however esp. for the login/logout I'm not quite sure this will remain over time
      so for now it's good enough like this

So in summary there's still room for a lot of improvement on this particular topic..
At the very least topmenu should be made a plugin, and maybe also login/logout