docs/admin_css.txt

   1 ======================================
   2 Customizing the Django admin interface
   3 ======================================
   4
   5 Django's dynamic admin interface gives you a fully-functional admin for free
   6 with no hand-coding required. The dynamic admin is designed to be
   7 production-ready, not just a starting point, so you can use it as-is on a real
   8 site. While the underlying format of the admin pages is built in to Django, you
   9 can customize the look and feel by editing the admin stylesheet and images.
  10
  11 Here's a quick and dirty overview some of the main styles and classes used in
  12 the Django admin CSS.
  13
  14 Modules
  15 =======
  16
  17 The ``.module`` class is a basic building block for grouping content in the
  18 admin. It's generally applied to a ``div`` or a ``fieldset``. It wraps the content
  19 group in a box and applies certain styles to the elements within. An ``h2``
  20 within a ``div.module`` will align to the top of the ``div`` as a header for the
  21 whole group.
  22
  23 .. image:: http://media.djangoproject.com/img/doc/admincss/module.gif
  24    :alt: Example use of module class on admin homepage
  25
  26 Column Types
  27 ============
  28
  29 The base template for each admin page has a block that defines the column
  30 structure for the page. This sets a class on the page content area
  31 (``div#content``) so everything on the page knows how wide it should be. So far
  32 there are three options available, and one special hybrid option.
  33
  34 colM
  35     This is the default column setting for all pages. The "M" stands for "main".
  36     Assumes that all content on the page is in one main column
  37     (``div#content-main``).
  38 colMS
  39     This is for pages with one main column and a sidebar on the right. The "S"
  40     stands for "sidebar". Assumes that main content is in ``div#content-main``
  41     and sidebar content is in ``div#content-related``. This is used on the main
  42     admin page.
  43 colSM
  44     Same as above, with the sidebar on the left. The source order of the columns
  45     doesn't matter.
  46 colM superwide
  47     This is for ridiculously wide pages. Doesn't really work very well for
  48     anything but colM. With superwide, you've got 1000px to work with. Don't
  49     waste them.
  50 flex
  51     This is for liquid-width pages, such as changelists. Currently only works
  52     with single-column pages (does not combine with ``.colMS`` or ``.colSM``).
  53     Form pages should never use ``.flex``.
  54
  55 For instance, you could stick this in a template to make a superwide page::
  56
  57     {% block coltype %}colM superwide{% endblock %}
  58
  59 or this to make a liquid-width page (note that ``flex`` replaces ``colM``, so
  60 both classes are not required)::
  61
  62     {% block coltype %}flex{% endblock %}
  63
  64 Widths
  65 ======
  66
  67 There's a whole mess of classes in the stylesheet for custom pixel widths on
  68 objects. They come in handy for tables and table cells, if you want to avoid
  69 using the ``width`` attribute. Each class sets the width to the number of pixels
  70 in the class, except ``.xfull`` which will always be the width of the column
  71 it's in. (This helps with tables that you want to always fill the horizontal
  72 width, without using ``width="100%"`` which makes IE 5's box model cry.)
  73
  74 **Note:** Within a ``.flex`` page, the ``.xfull`` class will ``usually`` set
  75 to 100%, but there are exceptions and still some untested cases.
  76
  77 Available width classes::
  78
  79     .x50 .x75 .x100 .x150 .x200 .x250 .x300 .x400 .x500 .xfull
  80
  81 Text Styles
  82 ===========
  83
  84 Font Sizes
  85 ----------
  86
  87 Most HTML elements (headers, lists, etc.) have base font sizes in the stylesheet
  88 based on context. There are three classes are available for forcing text to a
  89 certain size in any context.
  90
  91 small
  92     11px
  93 tiny
  94     10px
  95 mini
  96     9px (use sparingly)
  97
  98 Font Styles and Alignment
  99 -------------------------
 100
 101 There are also a few styles for styling text.
 102
 103 .quiet
 104     Sets font color to light gray. Good for side notes in instructions. Combine
 105     with ``.small`` or ``.tiny`` for sheer excitement.
 106 .help
 107     This is a custom class for blocks of inline help text explaining the
 108     function of form elements. It makes text smaller and gray, and when applied
 109     to ``p`` elements withing ``.form-row`` elements (see Form Styles below), it will
 110     offset the text to align with the form field. Use this for help text,
 111     instead of ``small quiet``. It works on other elements, but try to put the class
 112     on a ``p`` whenever you can.
 113 .align-left
 114     It aligns the text left. Only works on block elements containing inline elements.
 115 .align-right
 116     Are you paying attention?
 117 .nowrap
 118     Keeps text and inline objects from wrapping. Comes in handy for table headers you want to stay
 119     on one line.
 120
 121 Floats and Clears
 122 -----------------
 123
 124 float-left
 125     floats left
 126 float-right
 127     floats right
 128 clear
 129     clears all
 130
 131 Object Tools
 132 ============
 133
 134 Certain actions which apply directly to an object are used in form and
 135 changelist pages. These appear in a "toolbar" row above the form or changelist,
 136 to the right of the page. The tools are wrapped in a ``ul`` with the class
 137 ``object-tools``. There are two custom tool types which can be defined with an
 138 additional class on the ``a`` for that tool. These are ``.addlink`` and
 139 ``.viewsitelink``.
 140
 141 Example from a changelist page::
 142
 143     <ul class="object-tools">
 144           <li><a href="/stories/add/" class="addlink">Add redirect</a></li>
 145          </ul>
 146
 147 .. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_01.gif
 148    :alt: Object tools on a changelist page
 149
 150 and from a form page::
 151
 152     <ul class="object-tools">
 153      <li><a href="/history/303/152383/">History</a></li>
 154      <li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
 155     </ul>
 156
 157 .. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_02.gif
 158    :alt: Object tools on a form page
 159
 160 Form Styles
 161 ===========
 162
 163 Fieldsets
 164 ---------
 165
 166 Admin forms are broken up into groups by ``fieldset`` elements. Each form fieldset
 167 should have a class ``.module``. Each fieldset should have a header ``h2`` within the
 168 fieldset at the top (except the first group in the form, and in some cases where the
 169 group of fields doesn't have a logical label).
 170
 171 Each fieldset can also take extra classes in addition to ``.module`` to apply
 172 appropriate formatting to the group of fields.
 173
 174 .aligned
 175     this will align the labels and inputs side by side on the same line.
 176 .wide
 177     used in combination with ``.aligned`` to widen the space available for the labels.
 178
 179 Form Rows
 180 ---------
 181
 182 Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
 183 with class ``form-row``. If the field in the row is required, a class of
 184 ``required`` should also be added to the ``div.form-row``.
 185
 186 .. image:: http://media.djangoproject.com/img/doc/admincss/formrow.gif
 187    :alt: Example use of form-row class
 188
 189 Labels
 190 ------
 191
 192 Form labels should always precede the field, except in the case
 193 of checkboxes and radio buttons, where the ``input`` should come first. Any
 194 explanation or help text should follow the ``label`` in a ``p`` with class
 195 ``.help``.