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