Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Standardize classnames and layout to facilitate theming

From MoodleDocs
Revision as of 18:55, 19 December 2012 by Amy Groshek (talk | contribs) (→‎Table)

Working notes on standardization of classnames and layout across Moodle activity types, with the intention of making theme design faster and more foolproof.

In order to be sure all bases are covered in standardization, I began with a Survey of existing page views and markup. I'm going to exclude editing screens from this survey because it would just be too much to cover. Additionally, student views should probably be the first priority.

Recommendations

Move away from use of IDs as CSS selectors

  • IDs are needed for elements which need identification for JavaScript. Elements which do not need to be accessed or manipulated by JavaScript can be identified by classnames.
  • Wherever possible, CSS selectors should use classnames over IDs.

Add a paragraph renderer

Add a paragraph renderer. The container() renderer encourages developers to render text that is not appropriately tagged as paragraph text. This would be a simple thing to add. Or if not, at least discourage instructions and other text within bare divs. // similar to the heading renderer heading(); // to replace container() as a default text function to print a block of text paragraph();

.generalbox for text features

Use generalbox only for a box/block of text, not for container of all content in the central column. (In following with purported original purposes of .generalbox, assuming it used to be similar to .generaltable.)

  <!-- If we aren't going to implement a framework, then this will suffice. -->
  <div class="generalbox">
  <!-- If we are going to implement a framework, then, at least with regard to Twitter Bootstrap, 
.generalbox is analogous to the .well class. 
We might implement them both. -->
  <div class="generalbox well">

Also, tables should not be getting the .generalbox class, as they are tables, not boxes.

#intro ID a classname instead

The #intro item is common to all activity types. It is not a target of JavaScript and in addition is not really different from any generalbox element in most cases. It could very easily just be another notification box.

Currently:

<div id="intro" class="box generalbox"></div>

Recommended:

<div class="intro generalbox"></div>

Use .maincontent instead of .generalbox to indicate parent of all content in central column

Expand the role="main" container div with a classname so it can take the place of .generalbox as a container of all content in the central column:

  <div role="main" class="maincontent">

Revise span.maincontent

Link to main content is needed for accessibility, but do we need a special element to do it? span.maincontent is not really semantic... MDL-34723

  <span id="maincontent"></span>

Going recommendation is

<a id="maincontent-target" name="maincontent-target"></a>

Standardize inheritance for tables

The .generaltable instances look nice and are commonly used. But there are some activities where tables are given their own classes entirely, and not given the .generaltable as well. This makes it hard to style all tables with general styles. It's no problem for a mod developer to add additional classnames to target with the mod's own CSS, but the parent classname should be retained.

An example of this is the forum. At present, the table of threads for a news forum has only one classname:

  <table cellspacing="0" class="forumheaderlist" id="yui_3_5_1_1_1353535026017_577">

This means that anything special theme designers did with .generaltable will not apply to the forum table. A better strategy would be to include the .generaltable class, and then add additional classes for mod-specific styling.

  <table cellspacing="0" class="generaltable forumheaderlist" id="yui_3_5_1_1_1353535026017_577">

Header usage should be hierarchical within page views

  • Headers should be hierarchical, with two or more <h3> under each <h2> and so forth.
  • <h2> is the top-level header of the page content/central column. There should be only one <h2>
  • Headers should not be used for notification. Notification classes should be used for notification.
  • We shouldn't even need the .main class. The fact that the header is located in the central column/main content area, and is a header, should be enough. The only reason we need it is because we're recruiting headers for other purposes.

Not this:

  <h2 class="main">This is the top-level header</h2>
  <p>A paragraph of content.</p>
  <h2 class="main">These is your score on XX activity.</h2>
   <p>A paragraph of content.</p>
  <h2 class="main">You must make a selection to proceed.</h2>
  <input type="submit" value="Generic submit button">

This:

  <h2>This is the top-level header</h2>
  <p>This paragraph gives additional information and explains what's to come.</p>
  <h3>Content sub-header</h3>
  <p>More paragraph content content content</p>
  <h3>Content sub-header</h3>
  <p>More paragraph content content content</p>
  <div class="notifyproblem">You must make a selection to proceed.</div>

Consolidate a Variety of Elements to a Set Number of Content Types

These elements were identified and organized by David Scotson, and their first listing can be found here: https://moodle.org/mod/forum/discuss.php?d=216519 The content types are based on components in Twitter Bootstrap.

Important Label

The following elements all present an error-type element. DS chose to associate them with Bootstrap's label-important class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#labels-badges

div.felement.error span.error,
span.error,
span.patherror,
tr.rolecap td.risk.xss a,
div.form-warning

Warning Label

The following elements all present warning-type elements. DS chose to associate them with Bootstrap's label-warning class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#labels-badges

span.warn,
p.warn,
span.editinstructions,
#page-admin-report-security-index span.statuswarning,
span.statuswarning,
tr.rolecap td.risk.spam a,
.form-overridden

Success Label

The following elements all present warning-type elements. DS chose to associate them with Bootstrap's label-success class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#labels-badges

span.ok,
span.pathok,
span.statusok,
font[color="green"],
tr.rolecap td.risk.config a

Alert

The following elements all present alert-type elements. DS chose to associate them with Bootstrap's alert class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#alerts

#page-admin-roles-assign h2 + .box.generalbox,
div.notifysuccess,
div.notifyproblem,
body.admin div.info,
div.box.copyright,
body.pagelayout-report div.info,
div.redirectmessage,
div.adminwarning,
div.forumnodiscuss,
div#notice p,
div.performanceinfo.pageinfo,
div.noticebox,
div#helppopupbox,
div.releasenoteslink,
.errorbox

DS also implemented the .alert .close class for the following Moodle element:

a#closehelpbox

Success Alert

The following elements all present success alert-type elements. DS chose to associate them with Bootstrap's alert-success class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#alerts

div.notifysuccess

Error Alert

The following elements all present error alert-type elements. DS chose to associate them with Bootstrap's alert-error class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#alerts

#page-admin-roles-assign h2 + .box.generalbox,
div.notifyproblem,
.errorbox

Info Alert

The following elements all present info alert-type elements. DS chose to associate them with Bootstrap's alert-info class, which can be viewed here: http://twitter.github.com/bootstrap/components.html#alerts

body.admin div.info,
div.box.copyright,
div#helppopupbox,
div.redirectmessage,
body.pagelayout-report div.info,
div.releasenoteslink,
div.performanceinfo.pageinfo

Form Buttons

The following elements all present form button elements. DS chose to associate them with Bootstrap's form-actions class, which can be viewed here: http://twitter.github.com/bootstrap/base-css.html#forms. DS notes that there are other form element types in need of consolidation.

#fgroup_id_buttonar,
#fitem_id_submitbutton,
table#form td.submit,
.form-buttons

Table

The following elements all present table elements. DS chose to associate them with Bootstrap's form-actions class, which can be viewed here: http://twitter.github.com/bootstrap/base-css.html#tables.

table#explaincaps,
table#defineroletable,
table.grading-report,
table#listdirectories,
table.rolecaps,
table.userenrolment,
table#form,
form#movecourses table,
form#movecourses table,
#page-report-log-user .generaltable,
#page-admin-course-index .editcourse,
.forumheaderlist,
.userprofilebox table.list,
.generaltable