Gallery3:Coding Standards:HTML and CSS for Themes - Gallery Codex
Personal tools

Gallery3:Coding Standards:HTML and CSS for Themes

From Gallery Codex

This document outlines Gallery 3's theme system, its goals, and its HTML markup and CSS standards. It should be viewed as a high-level standards guide, not comprehensive developer documentation.

Audience

This guide is intended for the following audiences:

  • Intermediate to advanced theme developers
  • Framework developers
  • Module developers

Familiarity with HTML, CSS, JavaScript, and PHP is assumed.

HTML Markup Standards

Module and theme developers should strive to use HTML elements appropriate to the structure of Gallery's user interface and the content it presents. The Gallery core framework provides HTML partials for the most commonly used HTML element markup structures. Module and Theme developers should HTML markup should be used to group related content and elements into standard page layouts and content blocks.

Semantically Meaningful Markup

HTML coders should strive to use the tag that denotes the content's purpose as it relates to the document's structural hierarchy, not it's visual appearance. 'Meaningful' means make choices that make sense and seem reasonably 'correct' because not all markup choices are cut and dried. Obvious examples of semantically meaningful markup include using heading elements (<h1> - <h6>) for page headings and sub headings. Using unordered, ordered, and definition lists structure sequential list items (<ul>, <ol>, <dl>). Use of the <strong> element instead of <b> and <em> instead of <i>.

Keep It Simple

Avoid "divitis!" Simply put, if there's an HTML tag designated for content, use it. Avoid using more div's than are necessary to markup an element (see See http://csscreator.com/?q=divitis). Use <div> elements to define high-level layout units (eg. banner, sidebar, content, footer, etc.) and to group related content (eg. in album views, group an item's thumbnail with its title and other metadata). In most cases, there's no need to elements with additional div tags.

Instead of this:

<div class="g-breadcrumbs">
 <ul>
   <li>Gallery</li>
   <li>My Album</li>
 </ul>
</div>

Why not this?

<ul class="g-breadcrumbs">
 <li>Gallery</li>
 <li>My Album</li>
</ul>

Benefits include improved DOM script performance through fewer nodes in the HTML DOM.

Navigation and Menus as Lists

Use of unordered lists to markup all menus, including breadcrumbs, and pagers - No more <br> or <span> tags. Lists by default are vertical by default but can easily be styled to be horizontal. Sub-menus are marked up by nesting lists withing parent list items.

<ul id="g-module-menu" class="g-horizontal">
 <li>Gallery</li>
 <li>Site Admin
   <ul>
     <li>Plugins</li>
     <li>Users</li>
   </ul>
 </li>
</ul>

Inline CSS and JavaScript Event Handler Attributes

Use of inline CSS is strictly forbidden (<p style="color: red">)! Add styles to the core, module, or theme CSS. Using inline CSS does not keep with the theme system's goal of being overridable.

No JavaScript event handlers as HTML attributes (e.g. onlick="...")! Employ unobtrusive JavaScript techniques to attach event listeners to elements.

Forms

We shouldn't need tables to align labels with form inputs in Gx. Let's start using <legend>, <fieldset>, and <label> elements and style these properly. See http://themaninblue.com/writing/perspective/2004/03/24/ and http://2tbsp.com/content/flexible_and_efficient_htmlcss_form_layout

Data Tables

Let's start using the <caption> tag. Looks like G2 uses <th> appropriately. I'll talk about zebra striping table rows when addressing CSS standards. Instead of using a heading element above a table or within :

<table class="g-data-table">
 <tr>
   <th colspan="6"><h2>Gallery Settings</h2></th>
 </tr>

Use this:

<table class="g-data-table">
 <caption>Gallery Settings</caption>
 <tr>
   <th>Heading</th>
   ...

DOCTYPE - XHTML 1.0 Transitional or Strict - seem to remember a consensus for transitional

If someone has strong thoughts/opinions on the use of HTML 4.01 or XHTML 1.0 and strict vs. traditional doctypes, please share your thoughts. I can't think of any reason why we shouldn't stick to XHTML 1.0 strict.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

Cascading Style Sheets

CSS files that come with Gallery 3

/lib/gallery.common.css Includes common CSS styles for different states (enabled, active, error, ...), containers (block, horizontal list), and widgets (dialog, progressbar) that are designed to be very reusable and which we encourage every theme to reuse for consistency.

/themes/default/css/screen.css /themes/admin_default/css/admin_screen.css

Prefixing

All Gallery 3 (G3) ID and class CSS selectors are prefixed with the letter 'g' to avoid conflicts when G3 theme is integrated with CMS platforms (eg. Wordpress, Drupal, Joomla, etc.).

#g-unique-element { ... }
.g-recurring-element { ... }

Other prefixes that are used in the default Wind theme are 'ui-' for jQuery-UI CSS, 'sf-' for the superfish menu, 'yui-' for YUI CSS.


Peferred selectors

Preferred selectors. Why, what are they? Appropriate use of ID, Class, and Descendent CSS selectors

Rather than defining unique IDs and classes for every possible element in the G3 interface, G3 promotes the use of CSS descendant selectors. Descendant selectors couple high-level layout/content IDs with re-usable classes and HTML elements.

/* Style metadata in the main content container */
#g-content .g-metadata { ... }

/* Style metadata in the sidebar container */
#g-sidebar .g-metadata { ... }

Multiple CSS classes may be applied to a single HTML element and eliminates the need to wrap content with multiple HTML elements.

<a href="<?= url::site("admin/users/add_user_form") ?>" class="g-dialog-link g-button g-right">...</a>
<input type="user_email" id="g-user-email" class="g-required g-email" />

Stylesheet Organization

general notes:

  • from abstract to concrete
  • different sections should be numbered (1.1.2) for easy reference. for example from blueprints/wireframes about the layout structure


1.0 Global element styles

  • global = apply to 80-100% of the pages
  • element = only element styles. no class- or id-selectors
  • default styles that get overridden by other CSS styles
  • analog to YUI base

general

- html, body

text elements

- h1-h6, p, strong, em

links

lists

- e.g. lists will not have bullets and margin/padding by default (YUI reset wipes them out, note this here)

tables

- table, caption, tbody, tr, th, td

form elements

- form, fieldset, legend, label, input, textarea, select


(global) browser hacks

(specific browser hacks should go with the respective style declarations)

All IE hacks should be stored in separate file and applied via HTML conditional comment 2.0 Global unique styles

(this is for unique styles that are used on all or most pages, but go beyond simple element styles. this is mostly the global layout containers)

Generic Classes

  • wrap
  • header
  • logo
  • global navigation
  • login
  • search

content

  • Metadata (item, album thumbs)
  • Tag cloud
  • album tree
  • carousel

sidebar

footer

  • zebra striping - alternate table row display (odd, even)
  • sidebar block - apply rounded corners, bg colors, etc.
  • status message - confirm, success, warning, error, info
  • icon - provide padding to apply icon bg images to links, buttons, etc.

3.0 Global generic styles

(this is for generic styles that are used on many different pages)

text styles (that go beyond element styles)

- e.g understate, active, inactive,

link styles (that go beyond element styles)

Menus and Navigation - #g-login-menu - - .g-breadcrumb - - .g-paginator -

blocks

.g-block -

.g-item - Image Item(s) .g-metadata - Container for item and album metadata, both long and short forms. Long form metatadata is stored in tables, short form in unordered lists.

Don't know if those go here too?

- .g-tag-cloud

Status Message Display Types:

  1. Overall page/action - 1 instance per page/element
  2. Element-related - Multiple messages displayed adjacent to element

form styles (that go beyond element styles)

CMK: Jakob, I think g-metadata does, but not sure about g-tag-cloud. If we're confident that there will only be one tag cloud per page, perhaps it should be defined as an ID under Local styles.

4.0 Local styles

(I don't know if it makes any sense to break this down further into local unique and local generic?

But this should be structured further somehow)

CMK - Jakob, I do think we need this. This label doesn't quite fit.

#g-album-grid
#g-pagination - CMK - Pagination might better fit under global generic as a class rather than ID. I can see some themes wanting pagination at the top and bottom of views.
#g-comments
#g-album-view, #g-itemView, #gDashboardView - View container
#g-header - 1 header per page
#g-content - Primary content for the current view (page).
#g-sidebar - #g-sidebarN - Provide one or more sidebars.
#g-footer -

CSS Media Support

CMK - We need to address media type support. I think, in addition to screen, we must support print and handheld. I don't think we need to worry about projection since Opera's the only browser that supports it well. We might want to support TV, but I don't have a device with which to test.

Inheritance and overrides of screen styles by print and handheld sheets.

Do we need a special view for handheld devices or can we simply rely on CSS media detection to style the screen view? Depends on how many screen items should not be included in handheld views. Now that I'm back on AT&T's crummy Edge network and not 3G, I'm thinking a handheld optimized view might be nice.

I think we'll need simplified layout and navigation menu markup in handheld views or a switch to them in our standard screen views.

Tables vs. Floated Elements for Grid Display

More semantically correct, provide more flexibility in layout. I've written some JavaScript that will dynamically set column width based on the changing width of album areas in fluid layouts. I'd like to see this type of script coupled with the ability for users to set page widths and hardcode column counts included in Gx's default theme.

Possible approaches include:

  1. Purely CSS-driven approach. Requires row and column classes
  2. JS-driven approach

If widths aren't determined in the theme's CSS the framework or JS must calculate total possible columns based on thumbnail widths, thumbnail aspect ratios, and other factors that add to required width (image frames).

The framework would need to have some knowledge of the total width of the area where the thumbnail grid will be displayed. JavaScript can determine this during page load.

Forms

Forms are structured via unordered lists.

Gallery 3 Forms (by CSS ID)

  • #g-user-login
  • #g-user-register
  • #g-add-items
  • #g-edit-item
  • #g-create-album/#gEditAlbum
  • #g-add-comment
  • #g-search
  • #g-module-settings (replace 'Module' with module name or abbr.)

Form Input Classes (used for elements that aren't unique, like input, for status, and client-side validation)

.g-text - Note: we may not need to define both text and submit/reset/button inputs. I could see just classing submit inputs to reduce the number of classes applied.

.g-button Perhaps these classes should be injected via JS

The multiple class approach is supported by all modern browsers, not sure about mobile browsers. http://webdesign.about.com/od/css/qt/tipcssmulticlas.htm

DOM/AJAX Support

Make it easy to inject and manipulate HTML/CSS.

Client-Side Form Validation

Requirements

  • Provide hooks in the DOM for unobtrusive JS form validation.
  • Mark required fields.
  • Highlight inputs that didn't pass form validation.
  • Display field help messages for input requirements, examples, and general messages.

Form Input Validation Classes

THE FOLLOWING HAS NOT YET BEEN IMPLEMENTED

.g-required - Used without a validation rule class, this states that the field must contain some value, any value. It cannot be empty.

.g-rule - Replace 'Rule' with a validation rule label (i.e. not-empty, integer, string, email, alphanumeric, etc.). Might be able to use custom validation rules here too. Can be used with g-required or by itself. If used separately, only throws an error if input is provided that doesn't conform to the validation rule.

Dynamic classes - controllers apply these to elements that don't pass validation.

.g-validation-error - Apply to input container, label or div. Change color and apply message icon.

.g-validation-warn - Same as .g-validation-error

<form id="g-login">
 <label for="g-username">User name
   <input type="text" name="user_name" id="g-username" class="g-required g-alphanumeric" />
 </label>
 <label for="g-password">Password
   <input type="password" name="password" id="g-password" />
 </label>
 <input type="submit" name="submit" class="g-button" />
</form>

Icons and Images

.png = preferred image format

Icon naming convention (ex. ico_previous.png) Background images / tiles : bg_sitemenu.png Bullet points: bullet_tag.png

Icons are used to represent actions and key interface components in G3 and not modules as they were in G2. Here's a list of icons provided in G3's default theme:

  • close item, standard close window box with an X in it)
  • status messages (confirm, warning, error, info)
  • users/groups
  • slideshow, pagination (first, last, previous, next)
  • image viewing (view image, album indicator, view large)
  • image manipulation (scale, rotate, )
  • site sections (admin dashboard, )
  • actions - add, edit, delete, move, rearrange (grab for d&d), copy, upload
  • comments
  • meta/tags
  • search
  • progress indicator - spinning wheel, hourglass, etc.

Background images

  • Menu items
  • Buttons

Sidebar blocks

<div class="g-block">
 <h2>Block title</h2>
 <div class="g-block-content">
 </div>
</div>
  • enclosed by a .g-block div
  • must have .g-blockHeader div
    • h2 title
    • .minimize link
  • followed by .g-block-content elements
    • can be div, ul, table, ...

Jakob, I'd like to push for simplification until we hit a specific hurdle that requires the use of additional divs. I think the cleaner we keep the view template markup the better. There may be a concern over injecting HTML elements via JS and a theme developer's ability to understand this, but here's what I'd propose. - CMK

Sidebar block markup and CSS requirements:

  • Encapsulate block heading and content.
  • Provide class to apply styles to blocks (backgrounds, text styles, rounded corners, etc.)
  • Provide IDs and/or Classes for specific targeting of styles and DOM scripting.
    • ID: #g-module-block
    • Class: .g-minimize
  • Block titles must be <h2> elements.
<div id="g-module-block" class="g-block g-minimize">
 <h2>Block title</h2>
 <div class="g-content">
   ...
 </div>
</div>
  • Enclosed with a .g-block div
  • Apply 'g-minimize' class to blocks which can be minimized in the view template.
  • Inject <a class="g-minimize-button"></a> anchor into .g-minimize elements via JS and position with CSS. I assume the anchor would contain a minimize icon as a BG image, right?
  • Name content class .g-content instead of .g-block-content to make it more generic.
    • can be div, ul, table, ...
  • Style generic content containers in primary layout containers. Perhaps #g-content should be #gMainContent or #gViewContent.
    • #g-content .g-block .g-content { ... }
    • #g-sidebar .g-block .g-content { ... }