-The contents of this module:
+This file documents the contents of this module
-==================== 1st level subdirs
+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 sjango project', where to look for
- . settings
- . urls
- . common static files
+ this is the django 'project', where to look for
+ . settings.py
+ . urls.py
-* 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
- much like our past drupal_set_html_head()
+* engine:
+ the code for building / rendering plugins
+
+* plugins:
+ the actual code for plugins
* auth:
- a django 'app' that deals with authentication
+ 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:
- only for various notes and other utiliy scripts
+ 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
-==================== conventions
+
+* 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 only about html, but the engine can be used for rendering anything including json or whatever..
+ 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
img/
css/
js/
- the stuff I have so far is in myslice/ because it looks common to all apps..
+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
git://git.onelab.eu / unfold.git / blobdiff