Note:

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

User:Frank Ralf/Semantic HTML5: Difference between revisions

From MoodleDocs
(44 intermediate revisions by the same user not shown)
Line 1: Line 1:
== formslib - checkboxes ==
Read the whole story:


Styling forms proves a bit difficult due to the way formslib.php renders the individual form items. Let's look at a simple example:
# [[User:Frank_Ralf/Moodle_HTML| Site Admin Block: "Look Ma, (nearly) no DIVs!"]]
# [[User:Frank_Ralf/Semantic_HTML2| Site Admin Block: Better image placement]]
# [[User:Frank_Ralf/Semantic_HTML3| Course Categories - The Ugly Duckling]]
# [[User:Frank_Ralf/Semantic_HTML4| Course Categories - Clearing the Tables]]
 
Read the whole story on Moodle forms:
 
# [[User:Frank_Ralf/Moodle_forms1| Inconsistencies of Moodle forms]]
# [[User:Frank_Ralf/Moodle_forms2| formslib - Checkboxes: A case of "Divitis"?]] aka [[User:Frank Ralf/Semantic HTML5]]
# [[User:Frank_Ralf/Moodle_forms3| Moodle forms - A peek under the hood]]
 
 
 
== formslib - checkboxes: A case of "Divitis"? ==
 
Working with forms proves a bit difficult due to the way ''formslib.php'' renders the individual form items. Let's look at a simple example (inspired by the General Developer forum discussion on [http://moodle.org/mod/forum/discuss.php?d=125304 "Interface design input please"]).


=== Example PHP ===
=== Example PHP ===


<code php>
<code php>
$mform->addElement('header', 'checkboxes', get_string('checkboxtest', 'block_simpleblock'));
$mform->addElement('header', 'checkboxes', 'checkboxtest');
  $mform->addElement(
$mform->addElement(
    'checkbox',
  'checkbox',       // "type" attribute of input element
    'TEACHER',
  'TEACHER',         // "name" attribute of input element
    'Mr. Smith',
  'Mr. Smith',       // label to the left 
    'History',                    
  'History',         // label to the right
    array('class'=>'pe_teacher', 'id'=> 'SMITH')
  array('class'=>'pe_teacher', 'id'=> 'SMITH') // additional attributes   
    );
  );


  $mform->addElement(
$mform->addElement(
    'checkbox',                 
  'checkbox',                 
    'teachers',   
  'teachers',   
    'Ms. Miller',
  'Ms. Miller',
    'Math',                         
  'Math',                         
    array('class'=>'pe_teacher', 'id'=> 'miller')  
  array('class'=>'pe_teacher', 'id'=> 'miller')  
    );
  );
</code>
</code>


=== Screenshots ===
=== Screenshots ===


That looks quite unsuspicious:
That looks quite unsuspicious, but you might already see that the labels on the left and right side of the checkbox don't line up correctly:


[[Image:Formslib checkboxes.png]]
[[Image:Formslib checkboxes.png]]


Let's add some CSS to see the details:
So let's add some color by CSS to see the details.
'''Tip''': See [[Stylish]] for a tool to apply such helper CSS temporarily to your pages.


<code php>
<code php>
fieldset#checkboxes {background-color: yellow;}
fieldset#checkboxes {background-color: yellow;}
fieldset#checkboxes * {margin: 5px; padding: 5px;}


legend{background-color: lime;}
legend             {background-color: lime;}
div.fcontainer {background-color: blue;}
div.fcontainer     {background-color: blue;}
div.fitem {background-color: red;}
div.fitem           {background-color: red;}
div.fitemtitle {background-color: silver;}
div.fitemtitle     {background-color: silver;}
label {background-color: aqua;}
label               {background-color: aqua;}
div.felement {background-color: teal;}
div.felement       {background-color: teal;}
span {background-color: orange;}
span               {background-color: orange;}
input.pe_teacher {background-color: fuchsia; border: 3px dotted purple;}
input.pe_teacher   {background-color: fuchsia; border: 3px dotted purple;}
</code>
</code>


[[Image:Formslib checkboxes-colorful.png]]
[[Image:Formslib checkboxes-colorful.png]]


And with some margings and padding added:
With some margins and padding added by the following CSS it's becoming clearer:
 
<code php>
fieldset#checkboxes * {margin: 5px; padding: 5px;}
</code>


[[Image:Formslib checkboxes colorful-with-margins.png]]
[[Image:Formslib checkboxes colorful-with-margins.png]]


=== Output HTML ===
=== Output HTML ===
Line 76: Line 94:
</fieldset>
</fieldset>
</code>
</code>
== What's the problem? ==
* Given class ("pe_teacher") does have no visible effect at all.
* Alignment issue with the two labels.
* Makes DOM traversal with JavaScript difficult.
* Possibly accessibility issues.
* Our ID got an extra "id_" prepended (because we're overriding some automatically generated ID).
* No inline elements (SPAN) allowed in form elements [?]
* "ftitle" DIV only wraps label element
* Two labels for the same form item
* Default label to the left of the checkbox (right side recommended for accessibility reasons)
== The culprit ==
The rendering of form elements is defined in ''formslib.php'' by the function ''[http://xref.moodle.org/lib/formslib.php.source.html#l1639 MoodleQuickForm_Renderer()]'' in the '''_elementTemplates''' variable ('''default' =>''):
<code php>
<div class="fitem {advanced}
  <!-- BEGIN required --> required<!-- END required -->
  ">
  <div class="fitemtitle">
    <label>{label}
      <!-- BEGIN required -->{req}<!-- END required -->
      {advancedimg}{help}
    </label>
  </div>
  <div class="felement {type}
    <!-- BEGIN error --> error<!-- END error -->
    ">
    <!-- BEGIN error -->
      <span class="error">{error}</span>
      <br />
    <!-- END error -->
    {element}
  </div>
</div>
</code>
== See also ==
=== Related forum discussions ===
* [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] - Some important insights on how to make a form behave like you want it...
=== Moodle Docs ===
* [[Obsolete:Moodle forms library]]
=== Moodle Tracker ===
* MDL-10505 "Add group name to rendered elements for better CSS control"
* MDL-11134 "Help links in forms are outside the <label> - they will be ignored in JAWS forms mode"
=== Online resources ===
* [http://www.webstandards.org/learn/tutorials/accessible-forms/ "Accessible HTML/XHTML Forms"] by Ian Lloyd, ''The Web Standards Project''
* [http://www.formsthatwork.com "Forms that work: Designing web forms for usability"]. This is the companion web site to the book of the same name by Caroline Jarrett and Gerry Gaffney.

Revision as of 11:11, 25 November 2010

Read the whole story:

  1. Frank Ralf/Moodle HTML
  2. Frank Ralf/Semantic HTML2
  3. Frank Ralf/Semantic HTML3
  4. Frank Ralf/Semantic HTML4

Read the whole story on Moodle forms:

  1. Frank Ralf/Moodle forms1
  2. Frank Ralf/Moodle forms2 aka User:Frank Ralf/Semantic HTML5
  3. Frank Ralf/Moodle forms3


formslib - checkboxes: A case of "Divitis"?

Working with forms proves a bit difficult due to the way formslib.php renders the individual form items. Let's look at a simple example (inspired by the General Developer forum discussion on "Interface design input please").

Example PHP

$mform->addElement('header', 'checkboxes', 'checkboxtest'); $mform->addElement(

 'checkbox',        // "type" attribute of input element
 'TEACHER',         // "name" attribute of input element
 'Mr. Smith',       // label to the left  
 'History',         // label to the right
 array('class'=>'pe_teacher', 'id'=> 'SMITH') // additional attributes     
 );

$mform->addElement(

 'checkbox',                 
 'teachers',  
 'Ms. Miller',
 'Math',                         
 array('class'=>'pe_teacher', 'id'=> 'miller') 
 );

Screenshots

That looks quite unsuspicious, but you might already see that the labels on the left and right side of the checkbox don't line up correctly:

Formslib checkboxes.png

So let's add some color by CSS to see the details. Tip: See Stylish for a tool to apply such helper CSS temporarily to your pages.

fieldset#checkboxes {background-color: yellow;}

legend {background-color: lime;} div.fcontainer {background-color: blue;} div.fitem {background-color: red;} div.fitemtitle {background-color: silver;} label {background-color: aqua;} div.felement {background-color: teal;} span {background-color: orange;} input.pe_teacher {background-color: fuchsia; border: 3px dotted purple;}

Formslib checkboxes-colorful.png

With some margins and padding added by the following CSS it's becoming clearer:

fieldset#checkboxes * {margin: 5px; padding: 5px;}

Formslib checkboxes colorful-with-margins.png

Output HTML

So let's have a closer look at the markup Moodle provides (only first form item shown):

<fieldset class="clearfix" id="checkboxes">

 <legend class="ftoggler">Checkbox Test</legend>

</fieldset>

What's the problem?

  • Given class ("pe_teacher") does have no visible effect at all.
  • Alignment issue with the two labels.
  • Makes DOM traversal with JavaScript difficult.
  • Possibly accessibility issues.
  • Our ID got an extra "id_" prepended (because we're overriding some automatically generated ID).
  • No inline elements (SPAN) allowed in form elements [?]
  • "ftitle" DIV only wraps label element
  • Two labels for the same form item
  • Default label to the left of the checkbox (right side recommended for accessibility reasons)

The culprit

The rendering of form elements is defined in formslib.php by the function MoodleQuickForm_Renderer() in the _elementTemplates variable ('default' =>):

   <label>{label}
     {req}
     {advancedimg}{help}
   </label>
     {error}
     
{element}

See also

Related forum discussions

Moodle Docs

Moodle Tracker

  • MDL-10505 "Add group name to rendered elements for better CSS control"
  • MDL-11134 "Help links in forms are outside the <label> - they will be ignored in JAWS forms mode"

Online resources