lizard-ui 2.0

lizard-ui
=========

Lizard-ui provides a basic `Django <http://djangoproject.com>`_ user
interface, so a **base Django template** and some **css + javascript**. We
designed it at `Nelen & Schuurmans <http://www.nelen-schuurmans.nl>`_ for our
geographical information websites (with water management information).


Choices, requirements, assumptions
----------------------------------

Lizard-ui is opinionated: it makes choices and prescribes (good!)
technologies.

- Included: the `blueprint css framework <http://www.blueprintcss.org/>`_. It
resets css styles so that we've got a common base. It fixes common IE
layout bugs. It gives a basic typography that's quite pleasing.

- Required: `django-staticfiles
<http://pypi.python.org/pypi/django-staticfiles>`_. For a more verbose
description, see `Reinout's blog entry
<http://reinout.vanrees.org/weblog/2010/05/19/django-css-javascript-files.html>`_
(written with lizard-ui in mind).

- Required: `django_compressor
<http://pypi.python.org/pypi/django_compressor>`_ for combining css/javascript
files in production.

- Assumption: one screen, using the full width/height of the browser, without
scrolling. Our main goal is showing a nice big map with a small header and
a sidebar. You don't want to scroll a map. It is of course possible to
have a scrollbar inside that main content area itself.

- Assumption: javascript is available. Hey, we're showing a map so you need
javascript. So we liberally use javascript to get the UI right, for
instance by detecting and setting the main content area's width and height.

- Included: jquery. Yeah, it is pretty much the standard nowadays. So we use
jquery where jquery can be used instead of doing it with generic javascript.

- Included: both jqueryui and jquerytools. Visual goodies. Jquerytools for
the overlay and tabs, jqueryui for the rest (drag/drop and so).

- Included: openlayers as map javascript library. (Lizard-map, sooooon to be
released, contains our basic map interaction javascript and python code).


License + licenses
------------------

Our own license is GPLv3.

Lizard-ui ships with a couple of external css/javascript libraries.

Blueprint
Modified MIT

Jquery and jqueryui
Dual licensed under the MIT or GPL Version 2 licenses. Includes Sizzle.js,
released under the MIT, BSD, and GPL Licenses.

Jquerytools
No copyrights or licenses. Do what you like.

Openlayers
Clear BSD license.

Famfamfam icon set
CC attribution license.

Treeview jquery plugin
MIT/GPL


Django settings
---------------

Here's an excerpt of a ``settings.py`` you can use. The media and static root
directory setup assumes the use of buildout, but you can translate it to your
own filesystem setup::

INSTALLED_APPS = [
'lizard_ui',
'compressor',
'staticfiles',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
]

# Note: the below settings are more elaborate than needed,
# but we want to test django_compressor's compressing which
# needs a media url and root and so.

# Set COMPRESS to True if you want to test compression when
# DEBUG == True. (By default, COMPRESS is the opposite of
# DEBUG).
COMPRESS = False

# SETTINGS_DIR allows media paths and so to be relative to
# this settings file instead of hardcoded to
# c:\only\on\my\computer.
SETTINGS_DIR = os.path.dirname(os.path.realpath(__file__))

# BUILDOUT_DIR is for access to the "surrounding" buildout,
# for instance for BUILDOUT_DIR/var/static files to give
# django-staticfiles a proper place to place all collected
# static files.
BUILDOUT_DIR = os.path.abspath(os.path.join(SETTINGS_DIR, '..'))

# Absolute path to the directory that holds user-uploaded
# media.
MEDIA_ROOT = os.path.join(BUILDOUT_DIR, 'var', 'media')
# Absolute path to the directory where django-staticfiles'
# "bin/django build_static" places all collected static
# files from all applications' /media directory.
STATIC_ROOT = os.path.join(BUILDOUT_DIR, 'var', 'static')

# URL that handles the media served from MEDIA_ROOT. Make
# sure to use a trailing slash if there is a path component
# (optional in other cases).
MEDIA_URL = '/media/'
# URL for the per-application /media static files collected
# by django-staticfiles. Use it in templates like "{{
# MEDIA_URL }}mypackage/my.css".
STATIC_URL = '/static_media/'
# URL prefix for admin media -- CSS, JavaScript and
# images. Make sure to use a trailing slash. Uses
# STATIC_URL as django-staticfiles nicely collects admin's
# static media into STATIC_ROOT/admin.
ADMIN_MEDIA_PREFIX = STATIC_URL + 'admin/'

# Storage engine to be used during compression
COMPRESS_STORAGE = "staticfiles.storage.StaticFileStorage"
# The URL that linked media will be read from and compressed
# media will be written to.
COMPRESS_URL = STATIC_URL
# The absolute file path that linked media will be read from
# and compressed media will be written to.
COMPRESS_ROOT = STATIC_ROOT


# Used for django-staticfiles
TEMPLATE_CONTEXT_PROCESSORS = (
# Default items.
"django.core.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media",
# Needs to be added for django-staticfiles to allow you
# to use {{ STATIC_URL }}myapp/my.css in your templates.
'staticfiles.context_processors.static_url',
)

And a suitable apache config hint::

<Location /static_media/>
# The css/javascript/image staticfiles are cached in the
# browser for a day.
ExpiresActive On
ExpiresDefault "access plus 1 day"
</Location>

<Location /static_media/CACHE/>
# django_compress's generated timestamp'ed files:
# cache forever
ExpiresActive On
ExpiresDefault "access plus 10 years"
</Location>

# Static files are hosted by apache itself.
# User-uploaded media: MEDIA_URL = '/media/'
Alias /media/ ${buildout:directory}/var/media/
# django-staticfiles: STATIC_URL = '/static_media/'
Alias /static_media/ ${buildout:directory}/var/static/


Usage
-----

You can mount lizard-ui's urls, but it contains only live examples. So
perhaps you should only mount it in debug mode under ``/ui``. Handy, as it
contains reasonably full documentation on how to use it, including available
blocks and classes/IDs that you can use.

The base layout is defined in ``realbase.html``. You should however extend
``lizard_ui/lizardbase.html`` and then override the blocks that you want.

CSS and javascript should be added to the relevant blocks, but don't forget to
call "block.super". An example::

{% extends "lizard_ui/lizardbase.html" %}

{% block css %}
{{ block.super }}
<link type="text/css"
href="{{ STATIC_URL }}lizard_map/lizard_map.css"
media="screen, projection"
rel="stylesheet" />
{% endblock css %}

{% block javascript %}
{{ block.super }}
<script type="text/javascript"
src="{{ STATIC_URL }}openlayers/OpenLayers.js"></script>
<script type="text/javascript"
src="{{ STATIC_URL }}lizard_map/jquery.workspace.js"></script>
<script type="text/javascript"
src="{{ STATIC_URL }}lizard_map/lizard_map.js"></script>
{% endblock javascript %}

{% block content %}
<div id="map"></div>
{% endblock content %}

A example of a common task: change the logo. For that, make a
``media/lizard_ui`` directory in your django application (or site) and place a
``logo.png`` in it. Django-staticfiles' mechanism will take your logo.png in
preference to lizard-ui's.


Development installation
------------------------

The first time, you'll have to run the "bootstrap" script to set up setuptools
and buildout::

$> python bootstrap.py

And then run buildout to set everything up::

$> bin/buildout

(On windows it is called ``bin\buildout.exe``).

You'll have to re-run buildout when you or someone else made a change in
``setup.py`` or ``buildout.cfg``.

The current package is installed as a "development package", so
changes in .py files are automatically available (just like with ``python
setup.py develop``).

If you want to use trunk checkouts of other packages (instead of released
versions), add them as an "svn external" in the ``local_checkouts/`` directory
and add them to the ``develop =`` list in buildout.cfg.

Tests can always be run with ``bin/test`` or ``bin\test.exe``.


TODO
====

- Document all of the available classes/IDs that you can use to get automatic
(javascript) behaviour.

- Document the javascript code.

- Add basic test that the example.html renders without errors.

- Add javascript tests for the javascript code, ideally.

- Add mechanism for rendering a passed-in (or registered/configured) list of
object_tabs and object_actions, including some nice formatting.

- Add mechanism for breadcrumbs.

- Important: add tests for the login functionality.


Credits
=======

- TODO started this library


Changelog of lizard-ui
======================


2.0 (2011-06-22)
----------------

- Fixed logo (it was slightly to high).


1.70 (2011-06-22)
-----------------

- Newer lizard logo (without the gray background as that conflicts with our
own gray gradient), but that's ok for now.

- More app icons with shadows.


1.69 (2011-06-21)
-----------------

- Made popups more consistent (shadow color and size).


1.68 (2011-06-17)
-----------------

- Fixed .gif image that was a wrong file type.


1.67 (2011-06-16)
-----------------

- Fixed #2882: changed css to make some parts overflow: auto.


1.66 (2011-06-16)
-----------------

- Added error message when next accordion pane fails to load.


1.65 (2011-06-10)
-----------------

- Added reloadLocalizedGraphs() in addition to reloadGraphs() to reload only
graphs inside a certain div. (Used in lizard-map popups with tabs).

- Added Tipsy (Facebook/Github-style tooltips https://github.com/jaz303/tipsy)

- Added buttons.css (from https://github.com/ubuwaits/css3-buttons)

- Some repeatable backgrounds. (from http://subtlepatterns.com/)

- Some icons from http://glyphicons.com/, added/implemented seperately.
(TODO: integrate properly in sprite.png and the stylesheet of silk)

- OpenLayers 'Dark' theme.

- Re-exported several icon PNG's (meldingen, kaarten) with an alphachannel
drop-shadow.

- Added extra field to ApplicationScreen model. (description, for display in
tipsy tooltips)

- Centered the icons in the 'iphonesque' app-screen.

- Added inset drop-shadows to the app-screen.

- Changed the app-screen font to helvetica-light. (TODO: Try out Google
Webfonts instead)

- Changed gray H2 bars' bevel to a higher contrast, expressing more depth.

- Aligned lizard logo to the outmost left.
.
- Added tooltips to several interface elements.

- Improved appearance of the breadcrumb. (TODO: position is still a bit
awkward?)

- Changed OpenLayers javascript + css so that the layer chooser's
background color matches the rest of the dark theme.


1.64 (2011-06-01)
-----------------

- Changed accordion behaviour. All titles are refreshed, but we don't refresh
all pane contents anymore: only the new one. This makes sure trees stay
expanded. And it reduces re-rendering time for big trees. And we
theoretically don't need to send over all the panes' data in case that's
prohibitive for performance.


1.63 (2011-05-30)
-----------------

- Removed relative positioning on #portal-tabs. See ticket #2827.
- Reverted my changes made to .sidebarbox-action-icon in changeset:21174. Even
added 1px extra to better vertically align workspace items. See ticket #2750
for screenshots.
- Added a extra class name for save_form.
- Bigger portal-tabs with rounded corners.
- Corrected text-align of wrong-login.
- "Log in" and "Log uit" links have the same cursor: they were different and
"Log uit" had an illogical one, viz. cursor:text.


1.62 (2011-05-18)
-----------------

- Fixed vertical location of workspaceitem icons that aren't part of a header.


1.61 (2011-05-17)
-----------------

- Fixing menubar at 2em height to keep longer content from overflowing the
bar.

- Added favicon image in ``media/lizard_ui/favicon.ico``. So if you want a
different favicon in your project, place an updated icon in your site's
``media/lizardui/`` folder.


1.60 (2011-05-06)
-----------------

- Changed CSS of .workspace (#2659).

- Added five custom icons. (Gijs, req. by Dave)

- Downgraded to jQuery 1.5.1 due to IE8 bug in 1.5.2.
See https://office.nelen-schuurmans.nl/trac/ticket/2656#comment:5
See http://bugs.jquery.com/ticket/8755


1.59 (2011-04-28)
-----------------

- Deleted 'Copyright @ Nelen ...' text.


1.58 (2011-04-27)
-----------------

- Added dacom icon.

- Updated tabs css (needed for lizard-map >= 1.71).


1.57 (2011-04-20)
-----------------

- Added new flooding icon flooding2.png.

- Updated OpenLayers from 2.8 to 2.10.

- Jslint lizard.js.


1.56 (2011-04-14)
-----------------

- Updated Lizard logo.

- Added lizard_ui/tabs.css.

- Updated jQuery from 1.4.2 to 1.5.2, jQuery UI from 1.8.2 to 1.8.11,
jQueryTools from 1.2.2 to 1.2.5. Treeview from 1.4 to 1.4.1.

- Added css class for progress animation image


1.55 (2011-04-05)
-----------------

- Added 3di icon.

- Added Waterbalance icon.


1.54 (2011-03-18)
-----------------

- Removed width: 100% css for .auto-inserted. It works fine without
it. Before the image was slightly scaled horizontally.

- Added possibility for a double-height item in the
divideVerticalSpaceEqually() method. Just add a
"double-vertical-item" class instead of "vertical-item" to the item
you want to give double the height.


1.53 (2011-03-09)
-----------------

- Removed setUpWorkspaceAcceptableButtons. The button is now added
when a workspace-acceptable is clicked (lizard-map 1.58 and higher).

- Adding error message when a "replace-with-image" image is loaded and
there's an error. Instead of an ever-spinning "loading..." icon.


1.52 (2011-02-23)
-----------------

- Centered the progress animation.

- Added data-src to progress animation (for debugging purposes).


1.51 (2011-02-15)
-----------------

- Added progress animation to vertical-item / img-use-my-size /
replace-with-image.


1.50 (2011-02-15)
-----------------

- Added icons dike and controlnext.


1.36 (2011-02-15)
-----------------

- Added application screens and icons support: added models and views.


1.35 (2011-02-02)
-----------------

- Refactored the window.resize function in lizard.js [Gijs].


1.34 (2011-02-01)
-----------------

- Added breadcrumbs example.

- Added new breadcrumbs method. See examples.

- Added protovis library.

- Added support for portal-tabs, see also the examples page.


1.33 (2011-01-24)
-----------------

- Removed preventDefault in logout function.


1.32 (2011-01-20)
-----------------

- Still trying to fix logout bug.


1.31 (2011-01-20)
-----------------

- Fixed logout bug.


1.30 (2011-01-20)
-----------------

- Added turtle app icon.

- After logging out one goes back to "/".

- Improved login function.

- Added (empty) login screen with redirect option.


1.29 (2011-01-13)
-----------------

- Added &nbsp; to workspace acceptable button.


1.28 (2011-01-12)
-----------------

- Added setUpWorkspaceAcceptableButtons in lizard.js. The function is
in lizard-ui because setUpAccordion needs the function as well.


1.27 (2010-12-08)
-----------------

- Loading accordions re-initializes tree structures.


1.26 (2010-12-06)
-----------------

- Added default 500 and 404 pages.


1.25 (2010-12-01)
-----------------

- Added custom templatetag dutch_timedelta.

- Moved tooltip css from lizard_map to here.

- Add optional description to tree snippet.


1.24 (2010-11-24)
-----------------

- Added css class action-icon.


1.23 (2010-11-11)
-----------------

- (Re-)initializes tooltips when loading accordion.

- Added setUpTooltips() in lizard.js.


1.22 (2010-11-09)
-----------------

- Updated accordion: when an item is clicked, all panes and headers
are updated.


1.21 (2010-10-15)
-----------------

- Fix "apple" icon height to 80px.


1.20 (2010-10-15)
-----------------

- Fixed IE7 print problem.

- Added exception-logging middleware.

- Added app_icons.

- Added sidebar and sidebarbox css entries.

- Added tree_snippet.html template for creating trees.


1.19 (2010-09-27)
-----------------

- Fixed float problem for IE in login popup.

- Fixing visibility of "restore from print view" icon in IE.


1.18 (2010-09-27)
-----------------

- Added automatic print button that also allows you to expand the
collapsed-for-printing view again.

- Tables now print with a grid and proper left/center/right alignment.

- Links don't print anymore (at least, their url isn't appended anymore to the
link text when printing).


1.17 (2010-09-22)
-----------------

- Add colorpicker js library.

- Added createcoverage command.



1.16 (2010-09-08)
-----------------

- Added more tests.

- Small layout tweak for popup box.


1.15 (2010-09-03)
-----------------

- Added utility templatetags.


1.14 (2010-08-30)
-----------------

- Importing json via django now.


1.13 (2010-08-30)
-----------------

- Bugfix simplejson.


1.12 (2010-08-27)
-----------------

- Small adjustments to support lizard-map's new graph popup. (A better
separation of lizard-ui and lizard-map is needed later on: after the
deadlines :-) ).


1.11 (2010-08-26)
-----------------

- Styled the login form including proper "enter" behaviour and
first-field-gets-focus handling.


1.10 (2010-08-26)
-----------------

- Moved some css styling from lizard-map to lizard-ui.

- Added initial login support + forms. You need to add lizard-ui's urls.py to
yours if you want to use it.

- Better drag/drop visual feedback.


1.8 (2010-08-18)
----------------

- Javascript syntax fix: added two semicolons and removed another.


1.7 (2010-07-15)
----------------

- Make "replace-with-image" clickable by using "data-href-click"
property.

- Add ol.forms css.


1.6 (2010-07-06)
----------------

- Image replacement looks at "use-my-size" class instead of
use-my-width/height.

- Added javascript "printPage()" function that prints a webpage that at least
doesn't flow over the right hand side of the physical paper page. Printing
uses a combination of a custom print stylesheet and blueprint's print
stylesheet. Printing definitively isn't perfect yet, but at least usable.
Note: you should refresh or resize the page after printing to get the full
width again.


1.5 (2010-07-01)
----------------

- Added generic automatic image resizing (replacing a generic "a href" with an
image with the same src as the href and then figuring out the height/width
and passing that along as a GET parameter and as attributes on the img tag.

- Fixed resize timer by having a global variable for it.

- Calculating hiddenStuffHeight (currently: only the date popup hidden div)
only once: before the date popup has been opened.. Fixes the bug that you'd
get a large empty space at the bottom of the screen.


1.4.1 (2010-06-25)
------------------

- Updated TODO list.


1.4 (2010-06-25)
----------------

- We're now on the python package index, hurray!
http://pypi.python.org/pypi/lizard-ui

- Updated package metadata.

- Big README documentation update.


1.3 (2010-06-23)
----------------

- Added graph reloading on sidebar collapse/expand.

- UI css fixes (overflow:hidden in a couple of places to prevent scrollbars in
corner cases, for instance).


1.2 (2010-06-22)
----------------

- Floating the main content area now and giving it the proper width with
javascript. This makes the layout in IE more reliable.

- The main body has "overflow: hidden" to get rid of scrollbars once and for
all: scrollbars sometimes occur when there's a small layout bug. A
scrollbar takes up space, so the main content float is pushed down. We have
an assumption of a single page without scrolling, so hiding scrollbars is
perfectly fine. (The main area itself *can* have scrollbars for textual
content).


1.1 (2010-06-18)
----------------

- IE tweaks.


1.0 (2010-06-17)
----------------

- Fixed javascript code with jslint.

- Added django-compressor for javascript and css compression and combination.
You'll need to add the configuration in http://dpaste.de/xLDU/ to your
settings and add "compressor" to your installed apps.

- Switched to a separate "javascript" and "css" block instead of the
site-head-extras, head-extras and so. Be sure to add {{super.block}} when
you override the blocks.


0.12 (2010-06-11)
-----------------

- Upgraded to jqueryui 1.8.2 (from 1.8.1).

- Removed jqueryui's tab component as it conflicts with jquerytools'
implementation. Jquerytools' implementation is way friendlier to our
existing sidebar css.


0.11 (2010-06-08)
-----------------

- Added direct support for a jquery tree. We already contained the base
treeview javascript, so lizard-ui was a logical place for setting it up.


0.10 (2010-06-07)
-----------------

- Added fillSidebar() alias for stretchOneSidebarBox().

- Splitted title block in sitetitle/subtitle as that's a common occurrence.


0.9 (2010-06-03)
----------------

- Using jquery's live() for "late binding" of events to elements added later
through javascript. Saves some couple of lines.


0.8 (2010-06-01)
----------------

- Added generic accordion handling for the sidebar. Including ajaxy loading.


0.7 (2010-05-18)
----------------

- Added jquerytools for accordeon behaviour in sidebar.

- Layout fixes, mostly for the sidebar. Also fix for the datepicker-placed
div at the bottom.

- Update to jquery-ui 1.8.1.


0.6 (2010-04-28)
----------------

- Added collapsible sidebar.

- Changed css framework from yui to blueprint: more understandable. The
reason for yui was that it had a 100%-width layout. We're now building up
the layout (grid-wise) ourselves due to the collapsible sidebar, so
switching back to blueprint is now possible.

- Changed layout to match Dirk-Jan's latest screenshots.


0.5 (2010-04-13)
----------------

- Layout improvements.

- Added documentation (just mount our urls!).

- Removed separate icons, leaving only the sprite'd icons.

- Added jqueryui. Including it automatically. It also means extjs isn't
included automatically anymore.

- Sidebar width is 300px instead of 180px.


0.4 (2010-03-16)
----------------

- Added extjs javascript library.

- Added javascript and css for dividing the vertical space equally.


0.3.1 (2010-03-05)
------------------

- Bugfix: removed sample breadcrumb content from the template.


0.3 (2010-03-05)
----------------

- Added openlayers 2.8.

- Added famfamfam silk icon set.

- Added background to menubar, footer and body.

- Removed blueprint and added the YUI css framework.


0.2 (2010-02-12)
----------------

- Nested our templates in templates/lizard_ui instead of directly in
templates. We're well-behaved now!


0.1 (2010-02-12)
----------------

- Added lizardbase.html template as base for a lizard user interface.

- Added django-staticfiles as a dependency for managing css and javascript
resources.

- Added blueprint css framework.

- Initial structure created by nensskel.