r92356 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:< r92355‎ | r92356 | r92357 >
Date:14:24, 16 July 2011
Author:jeroendedauw
Status:deferred (Comments)
Tags:
Comment:
added smwdoc parser hook to auto generate parameter documentation tables for result formats
Modified paths:
  • /trunk/extensions/SemanticMediaWiki/includes/SMW_Setup.php (modified) (history)
  • /trunk/extensions/SemanticMediaWiki/includes/parserhooks/SMW_SMWDoc.php (added) (history)
  • /trunk/extensions/SemanticMediaWiki/includes/queryprinters/SMW_QueryPrinter.php (modified) (history)
  • /trunk/extensions/SemanticMediaWiki/specials/AskSpecial/SMW_SpecialAsk.php (modified) (history)

Diff [purge]

Index: trunk/extensions/SemanticMediaWiki/specials/AskSpecial/SMW_SpecialAsk.php
——@@ -728,7 +728,7 @@
729729
730730 $printer = SMWQueryProcessor::getResultPrinter( $format, SMWQueryProcessor::SPECIAL_PAGE );
731731
732 - $params = method_exists( $printer, 'getParameters' ) ? $printer->getParameters() : array();
 732+ $params = method_exists( $printer, 'getValidatorParameters' ) ? $printer->getValidatorParameters() : array();
733733
734734 // Ignore the format parameter, as we got a special control in the GUI for it already.
735735 unset( $params['format'] );
——@@ -736,7 +736,6 @@
737737 $optionsHtml = array();
738738
739739 foreach ( $params as $param ) {
740 - $param = $this->toValidatorParam( $param );
741740 $currentValue = array_key_exists( $param->getName(), $paramValues ) ? $paramValues[$param->getName()] : false;
742741
743742 $optionsHtml[] =
——@@ -779,46 +778,8 @@
780779 return $resultHtml;
781780 }
782781
783 - /**
784 - * Returns a Validator style Parameter definition.
785 - * SMW 1.5.x style definitions are converted.
786 - *
787 - * @since 1.6
788 - *
789 - * @param mixed $param
790 - *
791 - * @return Parameter
792 - */
793 - protected function toValidatorParam( $param ) {
794 - static $typeMap = array(
795 - 'int' => Parameter::TYPE_INTEGER
796 - );
797782
798 - if ( !( $param instanceof Parameter ) ) {
799 - if ( !array_key_exists( 'type', $param ) ) {
800 - $param['type'] = 'string';
801 - }
802783
803 - $paramClass = $param['type'] == 'enum-list' ? 'ListParameter' : 'Parameter';
804 - $paramType = array_key_exists( $param['type'], $typeMap ) ? $typeMap[$param['type']] : Parameter::TYPE_STRING;
805 -
806 - $parameter = new $paramClass( $param['name'], $paramType );
807 -
808 - if ( array_key_exists( 'description', $param ) ) {
809 - $parameter->setDescription( $param['description'] );
810 - }
811 -
812 - if ( array_key_exists( 'values', $param ) && is_array( $param['values'] ) ) {
813 - $parameter->addCriteria( new CriterionInArray( $param['values'] ) );
814 - }
815 -
816 - return $parameter;
817 - }
818 - else {
819 - return $param;
820 - }
821 - }
822 -
823784 /**
824785 * Get the HTML for a single parameter input.
825786 *
Index: trunk/extensions/SemanticMediaWiki/includes/queryprinters/SMW_QueryPrinter.php
——@@ -598,6 +598,24 @@
599599 }
600600
601601 /**
 602+ * Returns the parameters from getParameters, but with all non-Validator
 603+ * parameters converted to Validator parameters.
 604+ *
 605+ * @since 1.6
 606+ *
 607+ * @return array of Parameter
 608+ */
 609+ public function getValidatorParameters() {
 610+ $params = array();
 611+
 612+ foreach ( $this->getParameters() as $param ) {
 613+ $params[] = $this->toValidatorParam( $param );
 614+ }
 615+
 616+ return $params;
 617+ }
 618+
 619+ /**
602620 * A function to describe the allowed parameters of a query using
603621 * any specific format - most query printers should override this
604622 * function
——@@ -635,5 +653,45 @@
636654
637655 return $params;
638656 }
 657+
 658+ /**
 659+ * Returns a Validator style Parameter definition.
 660+ * SMW 1.5.x style definitions are converted.
 661+ *
 662+ * @since 1.6
 663+ *
 664+ * @param mixed $param
 665+ *
 666+ * @return Parameter
 667+ */
 668+ protected function toValidatorParam( $param ) {
 669+ static $typeMap = array(
 670+ 'int' => Parameter::TYPE_INTEGER
 671+ );
639672
 673+ if ( !( $param instanceof Parameter ) ) {
 674+ if ( !array_key_exists( 'type', $param ) ) {
 675+ $param['type'] = 'string';
 676+ }
 677+
 678+ $paramClass = $param['type'] == 'enum-list' ? 'ListParameter' : 'Parameter';
 679+ $paramType = array_key_exists( $param['type'], $typeMap ) ? $typeMap[$param['type']] : Parameter::TYPE_STRING;
 680+
 681+ $parameter = new $paramClass( $param['name'], $paramType );
 682+
 683+ if ( array_key_exists( 'description', $param ) ) {
 684+ $parameter->setDescription( $param['description'] );
 685+ }
 686+
 687+ if ( array_key_exists( 'values', $param ) && is_array( $param['values'] ) ) {
 688+ $parameter->addCriteria( new CriterionInArray( $param['values'] ) );
 689+ }
 690+
 691+ return $parameter;
 692+ }
 693+ else {
 694+ return $param;
 695+ }
 696+ }
 697+
640698 }
Index: trunk/extensions/SemanticMediaWiki/includes/parserhooks/SMW_SMWDoc.php
——@@ -0,0 +1,186 @@
 2+<?php
 3+
 4+/**
 5+ * Class for the 'smwdoc' parser hooks,
 6+ * which displays parameter documentation for a specified result format.
 7+ *
 8+ * @since 1.6
 9+ *
 10+ * @file SMW_SMWDoc.php
 11+ * @ingroup SMW
 12+ *
 13+ * @licence GNU GPL v3
 14+ * @author Jeroen De Dauw < jeroendedauw@gmail.com >
 15+ */
 16+class SMWSMWDoc extends ParserHook {
 17+
 18+ /**
 19+ * No LSB in pre-5.3 PHP *sigh*.
 20+ * This is to be refactored as soon as php >=5.3 becomes acceptable.
 21+ */
 22+ public static function staticMagic( array &$magicWords, $langCode ) {
 23+ $instance = new self;
 24+ return $instance->magic( $magicWords, $langCode );
 25+ }
 26+
 27+ /**
 28+ * No LSB in pre-5.3 PHP *sigh*.
 29+ * This is to be refactored as soon as php >=5.3 becomes acceptable.
 30+ */
 31+ public static function staticInit( Parser &$parser ) {
 32+ $instance = new self;
 33+ return $instance->init( $parser );
 34+ }
 35+
 36+ /**
 37+ * Gets the name of the parser hook.
 38+ * @see ParserHook::getName
 39+ *
 40+ * @since 1.6
 41+ *
 42+ * @return string
 43+ */
 44+ protected function getName() {
 45+ return 'smwdoc';
 46+ }
 47+
 48+ /**
 49+ * Returns an array containing the parameter info.
 50+ * @see ParserHook::getParameterInfo
 51+ *
 52+ * @since 1.6
 53+ *
 54+ * @return array
 55+ */
 56+ protected function getParameterInfo( $type ) {
 57+ $params = array();
 58+
 59+ $params['format'] = new Parameter( 'format' );
 60+ $params['format']->addCriteria( new CriterionInArray( array_keys( $GLOBALS['smwgResultFormats'] ) ) );
 61+ $params['format']->setDescription( wfMsg( 'smw-smwdoc-par-format' ) );
 62+
 63+ return $params;
 64+ }
 65+
 66+ /**
 67+ * Returns the list of default parameters.
 68+ * @see ParserHook::getDefaultParameters
 69+ *
 70+ * @since 1.6
 71+ *
 72+ * @return array
 73+ */
 74+ protected function getDefaultParameters( $type ) {
 75+ return array( 'format' );
 76+ }
 77+
 78+ /**
 79+ * Renders and returns the output.
 80+ * @see ParserHook::render
 81+ *
 82+ * @since 1.0
 83+ *
 84+ * @param array $parameters
 85+ *
 86+ * @return string
 87+ */
 88+ public function render( array $parameters ) {
 89+ $params = $this->getFormatParameters( $parameters['format'] );
 90+
 91+ return $this->getParameterTable( $params );
 92+ }
 93+
 94+ /**
 95+ * Returns the wikitext for a table listing the provided parameters.
 96+ *
 97+ * @since 1.6
 98+ *
 99+ * @param array $parameters
 100+ *
 101+ * @return string
 102+ */
 103+ protected function getParameterTable( array $parameters ) {
 104+ $tableRows = array();
 105+
 106+ foreach ( $parameters as $parameter ) {
 107+ $tableRows[] = $this->getDescriptionRow( $parameter );
 108+ }
 109+
 110+ $table = '';
 111+
 112+ if ( count( $tableRows ) > 0 ) {
 113+ $tableRows = array_merge( array(
 114+ '!' . wfMsg( 'validator-describe-header-parameter' ) ."\n" .
 115+ '!' . wfMsg( 'validator-describe-header-aliases' ) ."\n" .
 116+ '!' . wfMsg( 'validator-describe-header-type' ) ."\n" .
 117+ '!' . wfMsg( 'validator-describe-header-default' ) ."\n" .
 118+ '!' . wfMsg( 'validator-describe-header-description' )
 119+ ), $tableRows );
 120+
 121+ $table = implode( "\n|-\n", $tableRows );
 122+
 123+ $table = "$h3\n\n" .
 124+ '{| class="wikitable sortable"' . "\n" .
 125+ $table .
 126+ "\n|}";
 127+ }
 128+
 129+ return $table;
 130+ }
 131+
 132+ /**
 133+ * Returns the wikitext for a table row describing a single parameter.
 134+ *
 135+ * @since 1.6
 136+ *
 137+ * @param Parameter $parameter
 138+ *
 139+ * @return string
 140+ */
 141+ protected function getDescriptionRow( Parameter $parameter ) {
 142+ $aliases = $parameter->getAliases();
 143+ $aliases = count( $aliases ) > 0 ? implode( ', ', $aliases ) : '-';
 144+
 145+ $description = $parameter->getDescription();
 146+ if ( $description === false ) $description = '-';
 147+
 148+ $type = $parameter->getTypeMessage();
 149+
 150+ $default = $parameter->isRequired() ? "''" . wfMsg( 'validator-describe-required' ) . "''" : $parameter->getDefault();
 151+ if ( is_array( $default ) ) {
 152+ $default = implode( ', ', $default );
 153+ }
 154+ else if ( is_bool( $default ) ) {
 155+ $default = $default ? 'yes' : 'no';
 156+ }
 157+
 158+ if ( $default === '' ) $default = "''" . wfMsg( 'validator-describe-empty' ) . "''";
 159+
 160+ return <<<EOT
 161+| {$parameter->getName()}
 162+| {$aliases}
 163+| {$type}
 164+| {$default}
 165+| {$description}
 166+EOT;
 167+ }
 168+
 169+ protected function getFormatParameters( $format ) {
 170+ if ( array_key_exists( $format, $GLOBALS['smwgResultFormats'] ) ) {
 171+ return SMWQueryProcessor::getResultPrinter( $format )->getValidatorParameters();
 172+ }
 173+ else {
 174+ return array();
 175+ }
 176+ }
 177+
 178+ /**
 179+ * @see ParserHook::getDescription()
 180+ *
 181+ * @since 1.6
 182+ */
 183+ public function getDescription() {
 184+ return wfMsg( 'smw-smwdoc-description' );
 185+ }
 186+
 187+}
\ No newline at end of file
Property changes on: trunk/extensions/SemanticMediaWiki/includes/parserhooks/SMW_SMWDoc.php
___________________________________________________________________
Added: svn:eol-style
1188 + native
Index: trunk/extensions/SemanticMediaWiki/includes/SMW_Setup.php
——@@ -192,6 +192,7 @@
193193 $wgAutoloadClasses['SMWSet'] = $phDir . 'SMW_Set.php';
194194 $wgAutoloadClasses['SMWSetRecurringEvent'] = $phDir . 'SMW_SetRecurringEvent.php';
195195 $wgAutoloadClasses['SMWDeclare'] = $phDir . 'SMW_Declare.php';
 196+ $wgAutoloadClasses['SMWSMWDoc'] = $phDir . 'SMW_SMWDoc.php';
196197
197198 // Stores & queries
198199 $wgAutoloadClasses['SMWQueryProcessor'] = $smwgIP . 'includes/SMW_QueryProcessor.php';
——@@ -231,6 +232,9 @@
232233 $wgAutoloadClasses['Html'] = $smwgIP . 'compat/Html.php';
233234 }
234235
 236+ $wgHooks['ParserFirstCallInit'][] = 'SMWSMWDoc::staticInit';
 237+ $wgHooks['LanguageGetMagic'][] = 'SMWSMWDoc::staticMagic';
 238+
235239 $wgAutoloadClasses['SMWTestStore'] = $smwgIP . 'includes/storage/SMW_TestStore.php';
236240
237241 ///// Register specials, do that early on in case some other extension calls "addPage" /////

Follow-up revisions

RevisionCommit summaryAuthorDate
r92357fu r92356jeroendedauw14:44, 16 July 2011
r92532Cleanup based on r92356devayon13:23, 19 July 2011
r92540follow up to r92356jeroendedauw16:10, 19 July 2011

Comments

#Comment by Devayon (talk | contribs)   13:58, 19 July 2011

Makes line 732 of S:Ask redundant; one can no longer selectively "turn off" certain GUI controls of the parameter box.

I looked for an easy fix for this, but didn't find one.

#Comment by Jeroen De Dauw (talk | contribs)   16:10, 19 July 2011

Good catch! I re-implemented this behaviour in r92540 :)