MDL-37477 output: Add support for table captions

lib/outputcomponents.php

@@ -1513,6 +1513,19 @@ class html_writer {
 
         $countcols = 0;
 
+        // Output a caption if present.
+        if (!empty($table->caption)) {
+            $captionattributes = array();
+            if ($table->captionhide) {
+                $captionattributes['class'] = 'accesshide';
+            }
+            $output .= html_writer::tag(
+                'caption',
+                $table->caption,
+                $captionattributes
+            );
+        }
+
         if (!empty($table->head)) {
             $countcols = count($table->head);
 
@@ -2095,6 +2108,23 @@ class html_table {
      */
     public $summary;
 
+    /**
+     * @var string Caption for the table, typically a title.
+     *
+     * Example of usage:
+     * $t->caption = "TV Guide";
+     */
+    public $caption;
+
+    /**
+     * @var bool Whether to hide the table's caption from sighted users.
+     *
+     * Example of usage:
+     * $t->caption = "TV Guide";
+     * $t->captionhide = true;
+     */
+    public $captionhide = false;
+
     /**
      * Constructor
      */

lib/tests/html_writer_test.php

@@ -202,16 +202,53 @@ class core_html_writer_testcase extends basic_testcase {
         // The attribute will get overwritten by the ID above.
         $table->data[] = $row;
 
+        // Specify a caption to be output.
+        $table->caption = "A table of meaningless data.";
+
         $output = html_writer::table($table);
 
         $expected = <<<EOF
 <table class="generaltable" id="Jeffrey" data-name="Colin">
-<tbody><tr class="lastrow" id="Bob" data-name="Fred">
+<caption>A table of meaningless data.</caption><tbody><tr class="lastrow" id="Bob" data-name="Fred">
 <td class="cell c0 lastcol" id="Jeremy" data-name="John" style=""></td>
 </tr>
 </tbody>
 </table>
 
+EOF;
+        $this->assertSame($expected, $output);
+    }
+
+    public function test_table_hidden_caption() {
+
+        $table = new html_table();
+        $table->id = "whodat";
+        $table->data = array(
+            array('fred', 'MDK'),
+            array('bob',  'Burgers'),
+            array('dave', 'Competitiveness')
+        );
+        $table->caption = "Who even knows?";
+        $table->captionhide = true;
+
+        $output = html_writer::table($table);
+        $expected = <<<EOF
+<table class="generaltable" id="whodat">
+<caption class="accesshide">Who even knows?</caption><tbody><tr class="">
+<td class="cell c0" style="">fred</td>
+<td class="cell c1 lastcol" style="">MDK</td>
+</tr>
+<tr class="">
+<td class="cell c0" style="">bob</td>
+<td class="cell c1 lastcol" style="">Burgers</td>
+</tr>
+<tr class="lastrow">
+<td class="cell c0" style="">dave</td>
+<td class="cell c1 lastcol" style="">Competitiveness</td>
+</tr>
+</tbody>
+</table>
+
 EOF;
         $this->assertSame($expected, $output);
     }

lib/upgrade.txt

@@ -14,6 +14,7 @@ information provided here is intended especially for developers.
 * For 3rd party plugin specific environment.xml files, it's now possible to specify version independent checks by using the
   <PLUGIN name="component_name"> tag instead of the version dependent <MOODLE version="x.y"> one. If the PLUGIN tag is used any
   Moodle specific tags will be ignored.
+* html_table: new API for adding captions to tables (new field, $table->caption) and subsequently hiding said captions from sighted users using accesshide (enabled using $table->captionhide).
 
 === 2.8 ===
 

theme/bootstrapbase/less/moodle/grade.less

@@ -426,6 +426,12 @@
 .path-grade-report {
     .gradeparent {
         table {
+            caption {
+                font-size: 24px;
+                font-weight: bold;
+                line-height: 42px;
+                text-align: left;
+            }
             .border-radius(@baseBorderRadius);
         }
         tr .cell {
@@ -482,6 +488,9 @@
 
     &.dir-rtl {
         .gradeparent table {
+            caption {
+                text-align: right;
+            }
             margin-left: 0;
             margin-right: (@dockWidth + (@dockTitleMargin * 2));
         }