Text File
PROPOSAL.txt

Cascading Style Sheet - Style Guide

Status

IsProposal

Author

Roger Ineichen

Problem/Proposal

First, it's important to understand what's the target of this style guide. Zope3 has a form machinery and uses widgets for rendering fields to HTML. The fields are defined in a interface. A object instance provides this interface and has to define attributes/properties for the interface fields.

We have different directive for register pages, add and edit forms, views etc. You don't have to write a single line of HTML for rendering interface fields to HTML if you use the default registered page templates offered by a directive.

If you register a page or view with such directive, a default page template is used and a python view. The python view normaly calls widgets for rendering the interface fields.

Both the page template and the widgets contains HTML. The page template can be often easy replaced in the directive with the template="" attribute. So we can use own page template with a page/view directive.

The widgets are written in Python. This means a widget is implicit called and depends on the registration to interface fields. It's not common to replace widgets, except you need a real funny widget and there is no such widget in Zope3. A widget is registred for a interface field. The widget renders most the time a HTML form field like &lt;input name="xy" id="xy" value="xxx" /&gt; input fields. You can define own widgets in most of the directive with the <widget> sub directive.

Widgets has many attributes in the directive where you can use. Like the width and height of a &lt;textarea&gt; tag. This includes also CSS styles with the attribute styles="".

You see there is all implemented for useing own styles. You can write own page tempalte use in forms, you can define own stlyes in widgets and you develop a own skin. I'm pretty sure you can customize Zope with this components and you will never see a CSS tag except your owns.

Ok, it looks like we don't need a Style Guide? Every thing which defines styles can be replaced?

Right but that's not what you whana to do in each project.

The target in the CSS Style Guide is to define minimal styles. We only need real base level styles for widgets and generic forms. We also have to make sure Zope3 forms and widgets use the same style for the same component (component = title, header in forms).

It's not the target to write nice and funny styles where presenting a skin in a special way. The target is to use less styles as possible and add only styles if there is no other way.

Our work will be to find ways where we can offere a real generic base for graphic people. To define nice CSS styles/skins is the job of graphic people's.

HTML Style Guide?

Perhaps we have also write some rules for writting HTML. A good example for this is how we use the form fields:

<div class="row">
    <div class="label">
        <label for="yx" title="xy">Label text</label>
    </div>
    <div class="field">
        <input type=text" ...>
    </div>
</div>

I propose not adding a own Style Guide for HTML. I think it's a part of the CSS Style Guide. Or not?

Goals

Proposed Solution

  1. Split form, widget and skin styles in different CSS files.

    Split all styles used in page templates used in directives to a own css file. Let's call it form.css

  2. Define default styles for HTML form fields.

    HTML form fields has some restriction in CSS. CSS can't define styles for form fields correct. The reason why is, they use the same tag name and define it's type in the type attribute. like &lt;input type="text" ..&gt;, or &lt;input type="file" ..&gt;

    I propose to add class names for this fields (some of them use allready this class names in widgets). The type attribute itself whould be the simpliest name:

    text input --> <input type="text" class="text" ..>
    
    checkbox input --> <input type="checkbox" class="checkbox" ..>
    
  3. Replace H1, H2, ... tags in forms.

    H1, H2, etc tags should not be used in edit forms or generic pages. If we use H1, H2 tags in generic pages there is now way to handle this in custom skins. A example, if a page use H1 for the header and H2 for subtitles etc. and we use a body field with HTML text, there is no way to redefine H1 and H2 Tags in the body field area.

    Replace H1, H2 Tags with div Tags and a class name like:

    H1 --> <div class="header">Header</div>
    
    H2 --> <div class="title">Title</div>
    
  4. Add classes for elements like error messages and important parts:

    <div class="error">Some error occure</div>
    
  5. Add a styleguide page which presents the used styles.

    This whould be "THE" style guide for developer. Every Zope3 developer has to follow this style guide if he is checkin a page template. The style guide can be used from graphic poeple for implement their own CSS definitions.

  6. Make use the real attribute names in widgets

    This isn't the right place here, but some widgets use curiose names in the widgets directive. See TextAreaWidget. The textarea widget use the names width and height for rendering the cols and rows attributes in the textarea tag. Make sure we use te standard names of the HTML tag's.

Location

More information, this proposal's source or the implementation can be found in the package zope.app.css.

Risks

We will break some skins based on the old CSS styles.