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.
This guide is intended for the following audiences:
Familiarity with HTML, CSS, JavaScript, and PHP is assumed.
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.
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>.
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.
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>
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.
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
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">
/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
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.
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" />
general notes:
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
content
sidebar
footer
(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:
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.
(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 -
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.
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:
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 are structured via unordered lists.
Gallery 3 Forms (by CSS ID)
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
Make it easy to inject and manipulate HTML/CSS.
Requirements
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>
.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:
Background images
<div class="g-block"> <h2>Block title</h2> <div class="g-block-content"> </div> </div>
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:
<div id="g-module-block" class="g-block g-minimize"> <h2>Block title</h2> <div class="g-content"> ... </div> </div>
