Standardize classnames and layout to facilitate theming
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.
- CSS selectors should use classnames over IDs. The logic being that we build reusable classes for application in multiple contexts, with consistent markup across numerous page view and elements, rather than writing CSS to target individual 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">
This is mentioned again in the Consolidation item below.
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 Selectors for Several 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. In each case, we should implement a single class, and if possible eliminate unnecessary extra classes and IDs.
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
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