[Openinteract-dev] OI2 + CSS + XHTML thoughts

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Hi, all!

A couple of us at work were thinking of having a stab at refurbishing
the OI2 templates. We'd like a fresher look and eventually make use of
CSS, DOM+ECMAScript and other kinds of usable goodies.

I've noticed the "Themes" discussion in the OI2Ideas wiki page[1], and
based on it, would like to propose some thoughts for the CSS effort
ahead. I'm sure I haven't considered everything, and hope we can get a
fruitful discussion before we start on 1.99_07... :)

                            --==o==--

I suggest,

  - That things we agree upon are noted somewhere appropriate in the OI2
wiki. If we can't agree, Chris has the privilege to decide Our One True
$PATH. ;-)

  - We drop the base_theme package entirely, and implement themes _only_
using CSS. The goal should be that _no_ presentation details are
retrieved from a database (sorry, Teemu ;) ), and that there's only one
authoritative source for information on look and/or theme - namely the
CSS files. All that's necessary to understand the CSS layout must be
made available in an obvious, consistent and easy manner. Doing this
will reduce database/filesystem access, give us a cleaner separation
between data and presentation and improve debugging, system
comprehension, CSS data accessibility, performance and cacheability. We
should try to reduce complexity where we can - keep it simple; Separate
concerns cleanly.

  - We create a single set of CSS files that describe the look of all
standard page components and widgets, using CSS classes, ID's and
cascading/inheritance as appropriate. The goal is to have a sensibly-
looking and workable site out-of-the-box, with all style information
easily accessible and/or overrideable.

  - That all templates generate valid CSS-friendly XHTML1.0 (where
appropriate, as it's interesting to generate other types of markup too.)
Should the client not understand CSS, the pages must degrade gracefully
(e.g. still be readable/scannable and show the content in a clear and
useful manner.)

  - We only allow different "themes" by adding alternative CSS files,
and referring to them in the usual manner from the XHTML documents.

  - In the beginning we concentrate on W3C standards compliance. We worry
about browser-compliance issues later.

  - There should only be _one_ place for references to style information
in each XHTML page, namely in the <HEAD> section. We allow NO use of
local style attributes in the default templates - we want style
consistency throughout the entire site, and sub-document style
modifications should therefore be avoided.

  - Likewise, there should be _no_ ECMAScript/JavaScript inline in the
templates. We'll only allow references to separate .js files so the
browser can load them. If we need to use JavaScipt triggers of some
sort (onmouseover, etc.), we add these from the JavaScript files by
manipulating the DOM tree. This way, we separate document structure
(XHTML) from client-side programs (JavaScript) in a clean and nicely
degradable manner, in addition to improving download speed and
cacheability. For a guide on how to do the DOM manipulation, see the
"Unobtrusive JavaScript"[2] website.

  - The stylesheets should be complete (and resulting pages attractive)
enough so that it's not necessary for OI2 applications to override any
of it. But if one _has_ to override something anyway, then it should be
easy to do so.

  - If we find the user agent understands the XHTML MIME type
"application/xhtml+xml" (by checking the "Accept:" HTTP header), we
should make sure all XHTML data is transferred as this. (Sadly, not all
browsers support this cleanly, but since we prioritize W3C standard
compliance, we worry about this later.) For a discussion on this topic,
see "Sending XHTML as text/html Considered Harmful"[3].

  - We should also make sure all XHTML documents are using UTF-8 as
charset. This may be our first step in making all of OI2 use UTF-8 :).
In order to ease transition to UTF-8, we _may_ want to try to use HTML
entities whenever common eight-bit characters are used (e.g. in I18N msg
files, templates and error messages.)

  - Additionally, we should probably have a look at naming conventions.
E.g, all template filenames should have a .tmpl suffix and be in a
namespace. We should try to make it _really_ simple for newcomers to
understand what each file in OI2 is for. A more thorough look into
naming conventions in general may also be in place - see OIN-46[4] for
some initial thoughts regarding this.

  - Keep the templates as simple as possible, trying to reduce the
"depth" of INCLUDE and PROCESS calls. A maximum depth of two or three
levels should be strived for.

  - If we can avoid breaking the widget API, fine. But when we have good
reasons to break it (e.g. removing the old base_theme-specific stuff),
then we go ahead and break stuff.

  - Key structural elements in the generated XHTML should be identified
with the appropriate ID attribute, e.g. the main global menu may look
like this:

   <!-- Main menu. See /main.css for style information -->
   <ul class="oi2_menu" id="oi2_global_menu">
       <li><a href="/user">Users</a></li>
       <li><a href="/group">Groups</a></li>
   </ul>
   <!-- End of main menu -->

This will make it easier to usefult things by manipulating the DOM tree
with JavaScript.

  - Other useful features we may want to allow, are the "tabindex",
"accesskey" and "label" attributes in forms, "title" and "alt"
attributes in links and images, metadata elements (e.g. the <meta> and
<link> headers) and how these can be utilized using existing packages
and features in OI2. Further ideas on what to keep in mind can be found
in W3C's "Web Content Accessibility Guidelines" documents[5][6].

  - We may also want to explore ways to create menus in a consistent
manner across the entire site, either by using or improving base_box, or
looking at creating a new base_menu package.

                          --==o==--

In order to do all this, we may need some new functionality:

  - A method to allow any package template to specify new CSS files
which should be appended to the existing list of used stylesheets (this
enables the "Cascading" in "Cascading Style Sheets"), e.g.. by using a
method like

   [% OI.append_style(
                title   = "Main style",
                css_url = "/css/mypkg/screen.css",
                media   = "screen" ); %]

..which would generate something similar to the following string:

   <link rel="stylesheet" type="text/css"
         title="Main style" media="screen"
         href="/css/mypkg/screen.css" />

This way, each application has the _possibility_ to extend (or "fix")
specific style issues.

  - Likewise, one could get "theme" functionality by allowing for
alternate style sheets

   [% OI.append_alternate_style(
               title   = "High contrast style",
               css_url = "/css/mypkg/highcontrast-screen.css",
               media   = "screen" ); %]

...resulting in:

   <link rel="alternate stylesheet" type="text/css"
         title="High contrast style" media="screen"
         href="/css/mypkg/highcontrast-screen.css" />

  - We should also have similar methods for adding external
ECMAScript/JavaScript documents.

   [% OI.append_JavaScipt(
              src   = "/JavaScipt/mypkg/table_sort.js",
              defer = "yes" ); %]

...giving:

   <script type="text/JavaScipt"
           src="/JavaScipt/mypkg/table_sort.js"></script>

  - For applications to create application-specific site-general menus in
a globally consistent manner, we may want to be able to "register" one
or more menu items:

   [% OI.append_to_action_menu(
               TASK           = "search",
               LINK_KEY       = "mypkg.menu_item.searchlink",
               LINK_TITLE_KEY = "mypkg.menu_item.searchlink_title",
               other_arg      = "something useful" ); %]

...which might result in something like this placed in the
application-specific menu:

   <li><a href="/mypkg/search?other_arg=something%20useful"
          title="Search for my packages">Search</a>
   </li>

...or

   [% OI.append_to_global_menu(
               EXTERNAL       = "irc://irc.freenode.net/openinteract",
               LINK_KEY       = "global.menu.irclink",
               LINK_TITLE_KEY = "global.menu.irclink_title",
              ); %]

...resulting in:

   <li><a href="irc://irc.freenode.net/openinteract"
          title="Chat with other in the OI2 community!">OI2 Chat</a>
   </li>

                              --==o==--

Finally there are a couple of other things that would be nice to sort out:

  - Some way of cleanly managing breadcrumbs, clickpaths and other types
of link-stacks and -queues.

  - Likewise standardized a way of telling about program state. (e.g. a
place on the webpage where one always can expect to see "where" in an
application one currently "is", at any given time.)

  - Furthermore, I propose we create a branch of the OI2 tree right
after 1.99_06 has been tagged and released, so we have a stable
foundation to work from.

Any thoughts?

- Salve

[1] http://openinteract.org/cgi-bin/twiki/view/OI/OpenInteract2Ideas
[2] http://www.onlinetools.org/articles/unobtrusivejavascript/
[3] http://www.hixie.ch/advocacy/xhtml
[4] http://jira.openinteract.org/browse/OIN-46
[5] http://www.w3.org/TR/WAI-WEBCONTENT/
[6] http://www.w3.org/TR/WCAG20/

-- 
Salve J. Nilsen <salvejn at met dot no> / Systems Developer
Norwegian Meteorological Institute           http://met.no/
Information Technology Department / Section for Development