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
This commit is contained in:
parent
0f40f3b757
commit
80b4e33f1a
|
@ -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.
|
|
@ -1,6 +1,6 @@
|
|||
===============
|
||||
Django overview
|
||||
===============
|
||||
==================
|
||||
Django at a glance
|
||||
==================
|
||||
|
||||
Because Django was developed in a fast-paced newsroom environment, it was
|
||||
designed to make common Web-development tasks fast and easy. Here's an informal
|
||||
|
@ -17,7 +17,7 @@ Design your model
|
|||
=================
|
||||
|
||||
Start by describing your database layout in Python code. Django's data-model API
|
||||
offers many rich ways of representing your models — so far, it's been
|
||||
offers many rich ways of representing your models -- so far, it's been
|
||||
solving two years' worth of database-schema problems. Here's a quick example::
|
||||
|
||||
class Reporter(meta.Model):
|
||||
|
@ -127,7 +127,7 @@ A dynamic admin interface: It's not just scaffolding -- it's the whole house
|
|||
============================================================================
|
||||
|
||||
Once your models are defined, Django can automatically create an administrative
|
||||
interface — a Web site that lets authenticated users add, change and
|
||||
interface -- a Web site that lets authenticated users add, change and
|
||||
delete objects. It's as easy as adding an extra admin attribute to your model
|
||||
classes::
|
||||
|
||||
|
@ -183,9 +183,9 @@ requested URL. (If none of them matches, Django calls a special 404 view.) This
|
|||
is blazingly fast, because the regular expressions are compiled at load time.
|
||||
|
||||
Once one of the regexes matches, Django imports and calls the given view, which
|
||||
is a simple Python function. Each view gets passed a request object —
|
||||
is a simple Python function. Each view gets passed a request object --
|
||||
which contains request metadata and lets you access GET and POST data as simple
|
||||
dictionaries — and the values captured in the regex, via keyword
|
||||
dictionaries -- and the values captured in the regex, via keyword
|
||||
arguments.
|
||||
|
||||
For example, if a user requested the URL "/articles/2005/05/39323/", Django
|
||||
|
@ -282,14 +282,14 @@ Here's what the "base" template might look like::
|
|||
|
||||
Simplistically, it defines the look-and-feel of the site (with the site's logo),
|
||||
and provides "holes" for child templates to fill. This makes a site redesign as
|
||||
easy as changing a single file — the base template.
|
||||
easy as changing a single file -- the base template.
|
||||
|
||||
Note that you don't have to use Django's template system if you prefer another
|
||||
system. While Django's template system is particularly well-integrated with
|
||||
Django's model layer, nothing forces you to use it. For that matter, you don't
|
||||
have to use Django's API, either. You can use another database abstraction
|
||||
layer, you can read XML files, you can read files off disk, or anything you
|
||||
want. Each piece of Django — models, views, templates — is decoupled
|
||||
want. Each piece of Django -- models, views, templates -- is decoupled
|
||||
from the next.
|
||||
|
||||
This is just the surface
|
||||
|
@ -301,7 +301,7 @@ features:
|
|||
* A caching framework that integrates with memcached or other backends.
|
||||
* An RSS framework that makes creating RSS feeds as easy as writing a
|
||||
small Python class.
|
||||
* More sexy automatically-generated admin features — this overview barely
|
||||
* More sexy automatically-generated admin features -- this overview barely
|
||||
scratched the surface
|
||||
|
||||
The next obvious steps are for you to download Django, read the documentation
|
||||
|
|
Loading…
Reference in New Issue