X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=README;h=a8a6bbc8a2974c39533076f2ce868adfd1bd821e;hb=54a5954fbb6d77b012bbe198c7d492989c1f1585;hp=18f7ac97e01c59944d11d84913fb6a694d40d0ca;hpb=050db13e0c64e7a63646a8f45da74f734923dd9f;p=unfold.git diff --git a/README b/README index 18f7ac97..a8a6bbc8 100644 --- a/README +++ b/README @@ -1,50 +1,143 @@ This file documents the contents of this module -See devel/ for more devel-oriented doc. +See the devel/ subdir for more devel-oriented doc. -==================== 1st level subdirs +==================== 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) + +* edit myslice/config.py and enter the details of your manifold backend + +* 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 + +*** Authentication *** + +Although there still are a few hard-coded accounts in the system, you +will only be able to see some static views and won't be able to send +real queries if you use these, so you'd better use a real account (one +that your manifold backend knows about). + +For logging out: click on 'logged as *jean*', this shows a +confirmation page for logging out. this is intended to be temporary. + + +*** Features *** + +We have a basic model for asynchroneous queries (referring to manifold +queries) and for plugins (in the most general sense a plugin is just a +piece of the output that may be connected to a query) + +Right now the UI has a handful of demo views only; as of this writing +only the list of slices actually comes from the manifold backend in an +asynchroneous way. + +Also all the views are gathered in the trash/ locations for now, being +that they're only for assessment purposes. + +* dahsboard : has one async. query and 2 plugins that share that + query; the intent was to demo a different layout in both cases, + although the datatables one won't work yet at this point. + +* the 'Plugin' view demonstrates most of the available plugins. + +* slice view : only demonstrates how to use URLs to pass arguments along + +* scroll view : mostly it only illustrates that some pages can be made + public (no need to login) + +* tab view : a hand-made tab widget + +Not much effort has yet been put into coming up with a nice layout, +feel free to tweak that but it's probably still way too early for +this. + +==================== + +Third party tools shipped: + +* jquery +* datatables +* spin +* bootstrap + +I've tried to keep track of the version I picked and to have an easy upgrade path. + +==================== 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 / queries + +* 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/ - initially I had started to keep: - * templates (html templates with embedded python-like django chunks) - * static files (css, js, images..) - locally in the app were they belong - but I ended up with having the need to move up and down the tree endlessly - so for the beginning at least, I have moved everything in a unique place - this convention is subject to change - ---- + * 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 -==================== initial conventions for templates and 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 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 @@ -54,7 +147,39 @@ See devel/ for more devel-oriented doc. 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