More doc improvements: tweaks to the overview; added admin css documentation from wilson.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@50 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 181 insertions, 0 deletions

diff --git a/docs/admin_css.txt b/docs/admin_css.txt
new file mode 100644
index 0000000000..d162d00995
--- /dev/null
+++ b/docs/admin_css.txt
@@ -0,0 +1,181 @@
+======================
+Django Admin CSS Guide
+======================
+
+Django's dynamic admin interface gives you a fully-functional admin for free
+with no hand-coding required. The dynamic admin is designed to be
+production-ready, not just a starting point, so you can use it as-is on a real
+site. While the underlying format of the admin pages is built in to Django, you
+can customize the look and feel by editing the admin stylesheet and images.
+
+Here's a quick and dirty overview some of the main styles and classes used in
+the Django admin CSS.
+
+Modules
+=======
+
+The ``.module`` class is a basic building block for grouping content in the
+admin. It's generally applied to ``div``s or ``fieldset``s. It wraps the content
+group in a box and applies certain styles to the elements within. An ``h2``
+within a ``div.module`` will align to the top of the ``div`` as a header for the
+whole group.
+
+Column Types
+============
+
+The base template for each admin page has a block that defines the column
+structure for the page. This sets a class on the page content area
+(``div#content``) so everything on the page knows how wide it should be. So far
+there are three options available, and one special hybrid option.
+
+colM
+    This is the default column setting for all pages. The "M" stands for "main".
+    Assumes that all content on the page is in one main column
+    (``div#content-main``).
+colMS
+    This is for pages with one main column and a sidebar on the right. The "S"
+    stands for "sidebar". Assumes that main content is in ``div#content-main``
+    and sidebar content is in ``div#content-related``. This is used on the main
+    admin page.
+colSM
+    Same as above, with the sidebar on the left. The source order of the columns
+    doesn't matter.
+colM superwide
+    This is for ridiculously wide pages. Doesn't really work very well for
+    anything but colM. With superwide, you've got 1000px to work with. Don't
+    waste them.
+flex
+    This is for liquid-width pages, such as changelists. Currently only works
+    with single-colum pages (does not combine with ``.colMS`` or ``.colSM``).
+    Form pages should never use ``.flex``.
+
+For instance, you could stick this in a template to make a superwide page::
+
+    {% block coltype %}colM superwide{% endblock %}
+
+or this to make a liquid-width page (note that ``flex`` replaces ``colM``, so
+both classes are not required)::
+
+    {% block coltype %}flex{% endblock %}
+
+Widths
+======
+
+There's a whole mess of classes in the stylesheet for custom pixel widths on
+objects. They come in handy for tables and table cells, if you want to avoid
+using the ``width`` attribute. Each class sets the width to the number of pixels
+in the class, except ``.xfull`` which will always be the width of the column
+it's in. (This helps with tables that you want to always fill the horizontal
+width, without using ``width="100%"`` which makes IE 5's box model cry.)
+
+``'Note:``' Within a ``.flex`` page, the ``.xfull`` class will ``usually`` set
+to 100%, but there are exceptions and still some untested cases.
+
+Available width classes::
+
+    .x50 .x75 .x100 .x150 .x200 .x250 .x300 .x400 .x500 .xfull
+
+Text Styles
+===========
+
+Font Sizes
+----------
+
+Most HTML elements (headers, lists, etc.) have base font sizes in the stylesheet
+based on context. There are three classes are available for forcing text to a
+certain size in any context.
+
+small
+    11px
+tiny
+    10px
+mini
+    9px (use sparingly)
+
+Font Styles and Alignment
+-------------------------
+
+There are also a few styles for styling text.
+
+.quiet
+    Sets font color to light gray. Good for side notes in instructions. Combine
+    with ``.small`` or ``.tiny`` for sheer excitement.
+.help
+    This is a custom class for blocks of inline help text explaining the
+    function of form elements. It makes text smaller and gray, and when applied
+    to ``p``s withing ``.form-row`` elements (see Form Styles below), it will
+    offset the text to align with the form field. Use this for help text,
+    instead of ``small quiet``. It works on ``span``s, but try to put the class
+    on the ``p`` whenever you can.
+.align-left
+    It aligns the text left. Only works on block elements, I think.
+.align-right
+    Are you paying attention?
+.nowrap
+    Keeps text from wrapping. Comes in handy for table headers you want to stay
+    on one line.
+
+Floats and Clears
+-----------------
+
+float-left
+    floats left
+float-right
+    floats right
+clear
+    clears all
+
+Object Tools
+============
+
+Certain actions which apply directly to an object are used in form and
+changelist pages. These appear in a "toolbar" row above the form or changelist,
+to the right of the page. The tools are wrapped in a ``ul`` with the class
+``object-tools``. There are two custom tool types which can be defined with an
+additional class on the ``a`` for that tool. These are ``.addlink`` and
+``.viewsitelink``.
+
+Example from a changelist page::
+
+    <ul class="object-tools"><li><a href="/stories/add/" class="addlink">Add story</a></li></ul>
+
+and from a form page::
+
+    <ul class="object-tools">
+     <li><a href="/history/303/152383/">History</a></li>
+     <li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
+    </ul>
+
+Form Styles
+===========
+
+Fieldsets
+---------
+
+Admin forms are broken up into groups by ``fieldset``s. Each form fieldset
+should have a class ``.module``. Each fieldset should have a header ``h2``
+within the fieldset at the top (except the first group in the form, and in some
+cases where the group of fields doesn't have a logical label).
+
+Each fieldset can also take extra classes in addition to ``.module`` to apply
+appropriate formatting to the group of fields.
+
+.aligned
+    this will align the labels and inputs side by side on the same line.
+.wide
+    used in combination with ``.aligned`` to widen the space available for the labels.
+
+Form Rows
+---------
+
+Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
+with class ``form-row``. If the field in the row is required, a class of
+``required`` should also be added to the ``form-row div``.
+
+Labels
+------
+
+Each form ``label`` and field should be enclosed in a header ``h4``. Any
+explanation or help text should follow this ``h4`` in a ``p`` with class
+``.help``. Form ``label``s should always precede the field, except in the case
+of checkboxes and radio buttons, where the ``input`` should come first.
\ No newline at end of file