MDL-17667: Added simple XSL-based 'doc' feature to xmldb

admin/xmldb/actions/generate_documentation/generate_documentation.class.php

@@ -0,0 +1,96 @@
+<?php // $Id$
+
+///////////////////////////////////////////////////////////////////////////
+//                                                                       //
+// NOTICE OF COPYRIGHT                                                   //
+//                                                                       //
+// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
+//          http://moodle.com                                            //
+//                                                                       //
+// Copyright (C) 1999 onwards Martin Dougiamas        http://dougiamas.com  //
+//           (C) 2001-3001 Eloy Lafuente (stronk7) http://contiento.com  //
+//                                                                       //
+// This program is free software; you can redistribute it and/or modify  //
+// it under the terms of the GNU General Public License as published by  //
+// the Free Software Foundation; either version 2 of the License, or     //
+// (at your option) any later version.                                   //
+//                                                                       //
+// This program is distributed in the hope that it will be useful,       //
+// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
+// GNU General Public License for more details:                          //
+//                                                                       //
+//          http://www.gnu.org/copyleft/gpl.html                         //
+//                                                                       //
+///////////////////////////////////////////////////////////////////////////
+
+/// This class will produce XSL documentation for the loaded XML file
+
+class generate_documentation extends XMLDBAction {
+
+    /**
+     * Init method, every subclass will have its own
+     */
+    function init() {
+        parent::init();
+
+    /// Set own custom attributes
+
+    /// Get needed strings
+        $this->loadStrings(array(
+            'backtomainview' => 'xmldb'
+        ));
+    }
+
+    /**
+     * Invoke method, every class will have its own
+     * returns true/false on completion, setting both
+     * errormsg and output as necessary
+     */
+    function invoke() {
+        parent::invoke();
+
+        $result = true;
+
+    /// Set own core attributes
+        $this->does_generate = ACTION_GENERATE_HTML;
+
+    /// These are always here
+        global $CFG, $XMLDB;
+
+    /// Do the job, setting $result as needed
+
+    /// Get the dir containing the file
+        $dirpath = required_param('dir', PARAM_PATH);
+        $dirpath = $CFG->dirroot . $dirpath;
+        $path = $dirpath.'/install.xml';
+        if(!file_exists($path) || !is_readable($path)) {
+            return false;
+        }
+        
+    /// Add link back to home
+        $b = ' <p class="centerpara buttons">';
+        $b .= '&nbsp;<a href="index.php?action=main_view#lastused">[' . $this->str['backtomainview'] . ']</a>';
+        $b .= '</p>';
+        $this->output=$b;
+        
+    /// Transform XML file and display it
+        $doc = new DOMDocument();
+        $xsl = new XSLTProcessor();
+        
+        $doc->load(dirname(__FILE__).'/xmldb.xsl');
+        $xsl->importStyleSheet($doc);
+        
+        $doc->load($path);                        
+        $this->output.=$xsl->transformToXML($doc);
+        $this->output.=$b;            
+
+    /// Launch postaction if exists (leave this unmodified)
+        if ($this->getPostAction() && $result) {
+            return $this->launch($this->getPostAction());
+        }
+
+        return $result;
+    }
+}
+?>

admin/xmldb/actions/generate_documentation/xmldb.xsl

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!-- Top level: disclaimer/intro -->
+<xsl:template match="/">
+  <p>This documentation is generated automatically from the XMLDB database
+    definition. It is available only in English.</p>
+  <p><em>Note: This documentation currently does not show full details of field types.</em></p>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<!-- Tables: heading, comment -->
+<xsl:template match="TABLE">
+  <h3 style="margin-top:3em"><xsl:value-of select="@NAME"/></h3>
+  <xsl:call-template name="display-comment"><xsl:with-param name="PARA">y</xsl:with-param></xsl:call-template>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<!-- Fields (if any): table with field, type, comment -->
+<xsl:template match="FIELDS[FIELD]">
+  <table class="generaltable boxaligncenter" style="margin:1em 0" cellspacing="1" cellpadding="5" width="100%"> 
+    <tr>
+      <th class="header c0" scope="col">Field</th>
+      <th class="header c1" scope="col">Type</th>
+      <th class="header c2 lastcol" scope="col">Description</th>
+    </tr>
+    <xsl:apply-templates/>
+  </table>
+</xsl:template>
+
+<!-- Each individual field -->
+<xsl:template match="FIELD">
+  <xsl:variable name="COUNT" select="count(preceding-sibling::*)"/>
+  <tr class="r{$COUNT}">
+    <td class="cell c0"><xsl:value-of select="@NAME"/></td>
+    <td class="cell c1"><xsl:value-of select="@TYPE"/> (<xsl:value-of select="@LENGTH"/>)</td>
+    <td class="cell c2 lastcol"><xsl:call-template name="display-comment"/></td>
+  </tr>
+</xsl:template>
+
+<!-- Keys (if any): table with key, type, field(s), reference, and comment --> 
+<xsl:template match="KEYS[KEY]">
+  <h4>Keys</h4>
+  <table class="generaltable boxaligncenter" cellspacing="1" cellpadding="5" width="100%"> 
+    <tr>      
+      <th class="header c0" scope="col">Name</th>
+      <th class="header c1" scope="col">Type</th>
+      <th class="header c2" scope="col">Field(s)</th>
+      <th class="header c3" scope="col">Reference</th>
+      <!-- If no keys have comments (which is usually sensible since it's 
+         completely obvious what they are) then the comment column is not 
+         included -->      
+      <xsl:if test="*[normalize-space(@COMMENT)!='']">
+        <th class="header c4 lastcol" scope="col">Description</th>
+      </xsl:if>
+    </tr>
+    <xsl:apply-templates/>
+  </table>
+</xsl:template>
+
+<!-- Individual key -->
+<xsl:template match="KEY">
+  <xsl:variable name="COUNT" select="count(preceding-sibling::*)"/>
+  <tr class="r{$COUNT}">
+    <td class="cell c0"><xsl:value-of select="@NAME"/></td>
+    <td class="cell c1"><xsl:value-of select="@TYPE"/></td>
+    <td class="cell c2"><xsl:value-of select="@FIELDS"/></td>
+    <td class="cell c3">
+      <xsl:if test="@REFTABLE">
+        <xsl:value-of select="@REFTABLE"/> (<xsl:value-of select="@REFFIELDS"/>)
+      </xsl:if>
+    </td>
+    <xsl:if test="../*[normalize-space(@COMMENT)!='']">
+      <td class="cell c4 lastcol"><xsl:call-template name="display-comment"/></td>
+    </xsl:if>    
+  </tr>
+</xsl:template>
+
+<!-- Indexes -->
+<xsl:template match="INDEXES[INDEX]">
+  <h4>Indexes</h4>
+  <table class="generaltable boxaligncenter" cellspacing="1" cellpadding="5" width="100%"> 
+    <tr>
+      <th class="header c0" scope="col">Name</th>
+      <th class="header c1" scope="col">Type</th>
+      <th class="header c2" scope="col">Field(s)</th>
+      <xsl:if test="*[normalize-space(@COMMENT)!='']">
+        <th class="header c4 lastcol" scope="col">Description</th>
+      </xsl:if>
+    </tr>
+    <xsl:apply-templates/>
+  </table>
+</xsl:template>
+
+<!-- Individual index -->
+<xsl:template match="INDEX">
+  <xsl:variable name="COUNT" select="count(preceding-sibling::*)"/>
+  <tr class="r{$COUNT}">
+    <td class="cell c0"><xsl:value-of select="@NAME"/></td>
+    <td class="cell c1">
+      <xsl:choose>
+        <xsl:when test="@UNIQUE='true'">Unique</xsl:when>
+        <xsl:otherwise>Not unique</xsl:otherwise>
+      </xsl:choose>
+    </td>
+    <td class="cell c2"><xsl:value-of select="@FIELDS"/></td>
+    <xsl:if test="../*[normalize-space(@COMMENT)!='']">
+      <td class="cell c4 lastcol"><xsl:call-template name="display-comment"/></td>
+    </xsl:if>    
+  </tr>
+</xsl:template>
+
+<xsl:template name="display-comment">
+  <xsl:param name="PARA"/>
+  <xsl:if test="normalize-space(@COMMENT)!=''">
+    <xsl:choose>
+      <xsl:when test="$PARA">
+        <p class="xmldb_comment"><xsl:value-of select="@COMMENT"/></p>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="@COMMENT"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:if> 
+</xsl:template>
+
+</xsl:stylesheet>

admin/xmldb/actions/main_view/main_view.class.php

@@ -51,7 +51,8 @@ class main_view extends XMLDBAction {
             'checkindexes' => 'xmldb',
             'checkdefaults' => 'xmldb',
             'checkforeignkeys' => 'xmldb',
-            'checkbigints' => 'xmldb'
+            'checkbigints' => 'xmldb',
+            'doc' => 'xmldb'
         ));
     }
 
@@ -181,6 +182,16 @@ class main_view extends XMLDBAction {
                     $b .= '[' . $this->str['save'] . ']';
                 }
                 $b .= '</td><td class="button cell">';
+            /// The document button
+                if ($dbdir->path_exists &&
+                    file_exists($key . '/install.xml') &&
+                    is_readable($key . '/install.xml') &&
+                    is_readable($key)) {
+                    $b .= '<a href="index.php?action=generate_documentation&amp;dir=' . urlencode(str_replace($CFG->dirroot, '', $key)) . '">[' . $this->str['doc'] . ']</a>';
+                } else {
+                    $b .= '[' . $this->str['doc'] . ']';
+                }
+                $b .= '</td><td class="button cell">';
             /// The revert button
                 if ($dbdir->path_exists &&
                     file_exists($key . '/install.xml') &&

lang/en_utf8/xmldb.php

@@ -7,7 +7,6 @@ $string['back'] = 'Back';
 $string['backtomainview'] = 'Back To Main';
 $string['binaryincorrectlength'] = 'Incorrect length for binary field';
 $string['cannotuseidfield'] = 'Cannot insert the \"id\" field. It is an autonumeric column';
-$string['cannotinstantiateclass'] = 'Error: cannot instantiate class (actions/$a->action/$a->actionclass)';
 $string['change'] = 'Change';
 $string['charincorrectlength'] = 'Incorrect length for char field';
 $string['checkbigints'] = 'Check bigints';
@@ -53,6 +52,7 @@ $string['delete_sentence'] = 'Delete Sentence';
 $string['delete_statement'] = 'Delete Statement';
 $string['delete_table'] = 'Delete Table';
 $string['delete_xml_file'] = 'Delete XML File';
+$string['doc'] = 'Doc';
 $string['down'] = 'Down';
 $string['duplicate'] = 'Duplicate';
 $string['duplicatefieldname'] = 'Another field with that name exists';
@@ -75,6 +75,7 @@ $string['filenotwriteable'] = 'File not writeable';
 $string['fkviolationdetails'] = 'Foreign key $a->keyname on table $a->tablename is violated by $a->numviolations out of $a->numrows rows.';
 $string['floatincorrectdecimals'] = 'Incorrect number of decimals for float field';
 $string['floatincorrectlength'] = 'Incorrect length for float field';
+$string['generate_documentation']='Documentation';
 $string['gotolastused'] = 'Go to last used file';
 $string['incorrectfieldname'] = 'Incorrect name';
 $string['index'] = 'Index';