PageRenderTime 45ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

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