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``.