root/django/branches/0.90-bugfixes/docs/admin_css.txt

======================================
Customizing the Django admin interface
======================================

Django's dynamic admin interface gives you a fully-functional admin for free
with no hand-coding required. The dynamic admin is designed to be
production-ready, not just a starting point, so you can use it as-is on a real
site. While the underlying format of the admin pages is built in to Django, you
can customize the look and feel by editing the admin stylesheet and images.

Here's a quick and dirty overview some of the main styles and classes used in
the Django admin CSS.

Modules
=======

The ``.module`` class is a basic building block for grouping content in the
admin. It's generally applied to a ``div`` or a ``fieldset``. It wraps the content
group in a box and applies certain styles to the elements within. An ``h2``
within a ``div.module`` will align to the top of the ``div`` as a header for the
whole group.

.. image:: http://media.djangoproject.com/img/doc/admincss/module.gif
   :alt: Example use of module class on admin homepage

Column Types
============

The base template for each admin page has a block that defines the column
structure for the page. This sets a class on the page content area
(``div#content``) so everything on the page knows how wide it should be. So far
there are three options available, and one special hybrid option.

colM
    This is the default column setting for all pages. The "M" stands for "main".
    Assumes that all content on the page is in one main column
    (``div#content-main``).
colMS
    This is for pages with one main column and a sidebar on the right. The "S"
    stands for "sidebar". Assumes that main content is in ``div#content-main``
    and sidebar content is in ``div#content-related``. This is used on the main
    admin page.
colSM
    Same as above, with the sidebar on the left. The source order of the columns
    doesn't matter.
colM superwide
    This is for ridiculously wide pages. Doesn't really work very well for
    anything but colM. With superwide, you've got 1000px to work with. Don't
    waste them.
flex
    This is for liquid-width pages, such as changelists. Currently only works
    with single-colum pages (does not combine with ``.colMS`` or ``.colSM``).
    Form pages should never use ``.flex``.

For instance, you could stick this in a template to make a superwide page::

    {% block coltype %}colM superwide{% endblock %}

or this to make a liquid-width page (note that ``flex`` replaces ``colM``, so
both classes are not required)::

    {% block coltype %}flex{% endblock %}

Widths
======

There's a whole mess of classes in the stylesheet for custom pixel widths on
objects. They come in handy for tables and table cells, if you want to avoid
using the ``width`` attribute. Each class sets the width to the number of pixels
in the class, except ``.xfull`` which will always be the width of the column
it's in. (This helps with tables that you want to always fill the horizontal
width, without using ``width="100%"`` which makes IE 5's box model cry.)

**Note:** Within a ``.flex`` page, the ``.xfull`` class will ``usually`` set
to 100%, but there are exceptions and still some untested cases.

Available width classes::

    .x50 .x75 .x100 .x150 .x200 .x250 .x300 .x400 .x500 .xfull

Text Styles
===========

Font Sizes
----------

Most HTML elements (headers, lists, etc.) have base font sizes in the stylesheet
based on context. There are three classes are available for forcing text to a
certain size in any context.

small
    11px
tiny
    10px
mini
    9px (use sparingly)

Font Styles and Alignment
-------------------------

There are also a few styles for styling text.

.quiet
    Sets font color to light gray. Good for side notes in instructions. Combine
    with ``.small`` or ``.tiny`` for sheer excitement.
.help
    This is a custom class for blocks of inline help text explaining the
    function of form elements. It makes text smaller and gray, and when applied
    to ``p`` elements withing ``.form-row`` elements (see Form Styles below), it will
    offset the text to align with the form field. Use this for help text,
    instead of ``small quiet``. It works on other elements, but try to put the class
    on a ``p`` whenever you can.
.align-left
    It aligns the text left. Only works on block elements containing inline elements.
.align-right
    Are you paying attention?
.nowrap
    Keeps text and inline objects from wrapping. Comes in handy for table headers you want to stay
    on one line.

Floats and Clears
-----------------

float-left
    floats left
float-right
    floats right
clear
    clears all

Object Tools
============

Certain actions which apply directly to an object are used in form and
changelist pages. These appear in a "toolbar" row above the form or changelist,
to the right of the page. The tools are wrapped in a ``ul`` with the class
``object-tools``. There are two custom tool types which can be defined with an
additional class on the ``a`` for that tool. These are ``.addlink`` and
``.viewsitelink``.

Example from a changelist page::

    <ul class="object-tools">
          <li><a href="/stories/add/" class="addlink">Add redirect</a></li>
         </ul>
        
.. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_01.gif
   :alt: Object tools on a changelist page

and from a form page::

    <ul class="object-tools">
     <li><a href="/history/303/152383/">History</a></li>
     <li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
    </ul>

.. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_02.gif
   :alt: Object tools on a form page

Form Styles
===========

Fieldsets
---------

Admin forms are broken up into groups by ``fieldset`` elements. Each form fieldset
should have a class ``.module``. Each fieldset should have a header ``h2`` within the
fieldset at the top (except the first group in the form, and in some cases where the
group of fields doesn't have a logical label).

Each fieldset can also take extra classes in addition to ``.module`` to apply
appropriate formatting to the group of fields.

.aligned
    this will align the labels and inputs side by side on the same line.
.wide
    used in combination with ``.aligned`` to widen the space available for the labels.

Form Rows
---------

Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
with class ``form-row``. If the field in the row is required, a class of
``required`` should also be added to the ``div.form-row``.

.. image:: http://media.djangoproject.com/img/doc/admincss/formrow.gif
   :alt: Example use of form-row class

Labels
------

Form labels should always precede the field, except in the case
of checkboxes and radio buttons, where the ``input`` should come first. Any
explanation or help text should follow the ``label`` in a ``p`` with class
``.help``.