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 .. admonition:: Note
  30
  31     All admin pages (except the dashboard) are fluid-width. All fixed-width
  32     classes from previous Django versions have been removed.
  33
  34 The base template for each admin page has a block that defines the column
  35 structure for the page. This sets a class on the page content area
  36 (``div#content``) so everything on the page knows how wide it should be. There
  37 are three column types available.
  38
  39 colM
  40     This is the default column setting for all pages. The "M" stands for "main".
  41     Assumes that all content on the page is in one main column
  42     (``div#content-main``).
  43 colMS
  44     This is for pages with one main column and a sidebar on the right. The "S"
  45     stands for "sidebar". Assumes that main content is in ``div#content-main``
  46     and sidebar content is in ``div#content-related``. This is used on the main
  47     admin page.
  48 colSM
  49     Same as above, with the sidebar on the left. The source order of the columns
  50     doesn't matter.
  51
  52 For instance, you could stick this in a template to make a two-column page with
  53 the sidebar on the right::
  54
  55     {% block coltype %}colMS{% endblock %}
  56
  57 Text Styles
  58 ===========
  59
  60 Font Sizes
  61 ----------
  62
  63 Most HTML elements (headers, lists, etc.) have base font sizes in the stylesheet
  64 based on context. There are three classes are available for forcing text to a
  65 certain size in any context.
  66
  67 small
  68     11px
  69 tiny
  70     10px
  71 mini
  72     9px (use sparingly)
  73
  74 Font Styles and Alignment
  75 -------------------------
  76
  77 There are also a few styles for styling text.
  78
  79 .quiet
  80     Sets font color to light gray. Good for side notes in instructions. Combine
  81     with ``.small`` or ``.tiny`` for sheer excitement.
  82 .help
  83     This is a custom class for blocks of inline help text explaining the
  84     function of form elements. It makes text smaller and gray, and when applied
  85     to ``p`` elements within ``.form-row`` elements (see Form Styles below),
  86     it will offset the text to align with the form field. Use this for help
  87     text, instead of ``small quiet``. It works on other elements, but try to
  88     put the class on a ``p`` whenever you can.
  89 .align-left
  90     It aligns the text left. Only works on block elements containing inline
  91     elements.
  92 .align-right
  93     Are you paying attention?
  94 .nowrap
  95     Keeps text and inline objects from wrapping. Comes in handy for table
  96     headers you want to stay on one line.
  97
  98 Floats and Clears
  99 -----------------
 100
 101 float-left
 102     floats left
 103 float-right
 104     floats right
 105 clear
 106     clears all
 107
 108 Object Tools
 109 ============
 110
 111 Certain actions which apply directly to an object are used in form and
 112 changelist pages. These appear in a "toolbar" row above the form or changelist,
 113 to the right of the page. The tools are wrapped in a ``ul`` with the class
 114 ``object-tools``. There are two custom tool types which can be defined with an
 115 additional class on the ``a`` for that tool. These are ``.addlink`` and
 116 ``.viewsitelink``.
 117
 118 Example from a changelist page::
 119
 120     <ul class="object-tools">
 121       <li><a href="/stories/add/" class="addlink">Add redirect</a></li>
 122     </ul>
 123
 124 .. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_01.gif
 125    :alt: Object tools on a changelist page
 126
 127 and from a form page::
 128
 129     <ul class="object-tools">
 130      <li><a href="/history/303/152383/">History</a></li>
 131      <li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
 132     </ul>
 133
 134 .. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_02.gif
 135    :alt: Object tools on a form page
 136
 137 Form Styles
 138 ===========
 139
 140 Fieldsets
 141 ---------
 142
 143 Admin forms are broken up into groups by ``fieldset`` elements. Each form fieldset
 144 should have a class ``.module``. Each fieldset should have a header ``h2`` within the
 145 fieldset at the top (except the first group in the form, and in some cases where the
 146 group of fields doesn't have a logical label).
 147
 148 Each fieldset can also take extra classes in addition to ``.module`` to apply
 149 appropriate formatting to the group of fields.
 150
 151 .aligned
 152     This will align the labels and inputs side by side on the same line.
 153 .wide
 154     Used in combination with ``.aligned`` to widen the space available for the
 155     labels.
 156
 157 Form Rows
 158 ---------
 159
 160 Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
 161 with class ``form-row``. If the field in the row is required, a class of
 162 ``required`` should also be added to the ``div.form-row``.
 163
 164 .. image:: http://media.djangoproject.com/img/doc/admincss/formrow.gif
 165    :alt: Example use of form-row class
 166
 167 Labels
 168 ------
 169
 170 Form labels should always precede the field, except in the case
 171 of checkboxes and radio buttons, where the ``input`` should come first. Any
 172 explanation or help text should follow the ``label`` in a ``p`` with class
 173 ``.help``.