* @ingroup API
*/
abstract class ApiFormatBase extends ApiBase {
- private $mIsHtml, $mFormat, $mUnescapeAmps, $mHelp, $mCleared;
- private $mBufferResult = false, $mBuffer, $mDisabled = false;
+ private $mIsHtml, $mFormat, $mUnescapeAmps, $mHelp;
+ private $mBuffer, $mDisabled = false;
/**
* If $format ends with 'fm', pretty-print the output in HTML.
$this->mFormat = $format;
}
$this->mFormat = strtoupper( $this->mFormat );
- $this->mCleared = false;
}
/**
* Overriding class returns the MIME type that should be sent to the client.
- * This method is not called if getIsHtml() returns true.
+ *
+ * When getIsHtml() returns true, the return value here is used for syntax
+ * highlighting but the client sees text/html.
+ *
* @return string
*/
abstract public function getMimeType();
return $this->mFormat;
}
- /**
- * Specify whether or not sequences like " should be unescaped
- * to " . This should only be set to true for the help message
- * when rendered in the default (xmlfm) format. This is a temporary
- * special-case fix that should be removed once the help has been
- * reworked to use a fully HTML interface.
- *
- * @param bool $b Whether or not ampersands should be escaped.
- */
- public function setUnescapeAmps( $b ) {
- $this->mUnescapeAmps = $b;
- }
-
/**
* Returns true when the HTML pretty-printer should be used.
* The default implementation assumes that formats ending with 'fm'
}
/**
- * Whether this formatter can format the help message in a nice way.
- * By default, this returns the same as getIsHtml().
- * When action=help is set explicitly, the help will always be shown
- * @return bool
- */
- public function getWantsHelp() {
- return $this->getIsHtml();
- }
-
- /**
- * Disable the formatter completely. This causes calls to initPrinter(),
- * printText() and closePrinter() to be ignored.
+ * Disable the formatter.
+ *
+ * This causes calls to initPrinter() and closePrinter() to be ignored.
*/
public function disable() {
$this->mDisabled = true;
}
+ /**
+ * Whether the printer is disabled
+ * @return bool
+ */
public function isDisabled() {
return $this->mDisabled;
}
/**
- * Whether this formatter can handle printing API errors. If this returns
- * false, then on API errors the default printer will be instantiated.
+ * Whether this formatter can handle printing API errors.
+ *
+ * If this returns false, then on API errors the default printer will be
+ * instantiated.
* @since 1.23
* @return bool
*/
}
/**
- * Initialize the printer function and prepare the output headers, etc.
- * This method must be the first outputting method during execution.
- * A human-targeted notice about available formats is printed for the HTML-based output,
- * except for help screens (caused by either an error in the API parameters,
- * the calling of action=help, or requesting the root script api.php).
- * @param bool $isHelpScreen Whether a help screen is going to be shown
+ * Initialize the printer function and prepare the output headers.
+ * @param bool $unused Always false since 1.25
*/
- function initPrinter( $isHelpScreen ) {
+ function initPrinter( $unused = false ) {
if ( $this->mDisabled ) {
return;
}
- $isHtml = $this->getIsHtml();
- $mime = $isHtml ? 'text/html' : $this->getMimeType();
- $script = wfScript( 'api' );
+
+ $mime = $this->getIsHtml() ? 'text/html' : $this->getMimeType();
// Some printers (ex. Feed) do their own header settings,
// in which case $mime will be set to null
- if ( is_null( $mime ) ) {
+ if ( $mime === null ) {
return; // skip any initialization
}
if ( $apiFrameOptions ) {
$this->getMain()->getRequest()->response()->header( "X-Frame-Options: $apiFrameOptions" );
}
-
- if ( $isHtml ) {
-?>
-<!DOCTYPE HTML>
-<html>
-<head>
-<?php
- if ( $this->mUnescapeAmps ) {
-?> <title>MediaWiki API</title>
-<?php
- } else {
-?> <title>MediaWiki API Result</title>
-<?php
- }
-?>
-</head>
-<body>
-<?php
- if ( !$isHelpScreen ) {
-// @codingStandardsIgnoreStart Exclude long line from CodeSniffer checks
-?>
-<br />
-<small>
-You are looking at the HTML representation of the <?php echo $this->mFormat; ?> format.<br />
-HTML is good for debugging, but is unsuitable for application use.<br />
-Specify the format parameter to change the output format.<br />
-To see the non HTML representation of the <?php echo $this->mFormat; ?> format, set format=<?php echo strtolower( $this->mFormat ); ?>.<br />
-See the <a href='https://www.mediawiki.org/wiki/API'>complete documentation</a>, or
-<a href='<?php echo $script; ?>'>API help</a> for more information.
-</small>
-<pre style='white-space: pre-wrap;'>
-<?php
-// @codingStandardsIgnoreEnd
- // don't wrap the contents of the <pre> for help screens
- // because these are actually formatted to rely on
- // the monospaced font for layout purposes
- } else {
-?>
-<pre>
-<?php
- }
- }
}
/**
- * Finish printing. Closes HTML tags.
+ * Finish printing and output buffered data.
*/
public function closePrinter() {
if ( $this->mDisabled ) {
return;
}
- if ( $this->getIsHtml() ) {
-?>
-</pre>
-</body>
-</html>
-<?php
+ $mime = $this->getMimeType();
+ if ( $this->getIsHtml() && $mime !== null ) {
+ $format = $this->getFormat();
+ $result = $this->getBuffer();
+
+ $context = new DerivativeContext( $this->getMain() );
+ $context->setUser( new User ); // anon to avoid caching issues
+ $context->setSkin( SkinFactory::getDefaultInstance()->makeSkin( 'apioutput' ) );
+ $out = new OutputPage( $context );
+ $out->addModules( 'mediawiki.apipretty' );
+ $out->setPageTitle( $context->msg( 'api-format-title' ) );
+ $context->setOutput( $out );
+
+ $header = $context->msg( 'api-format-prettyprint-header' )
+ ->params( $format, strtolower( $format ) )
+ ->parseAsBlock();
+ $out->addHTML(
+ Html::rawElement( 'div', array( 'class' => 'api-pretty-header' ),
+ ApiHelp::fixHelpLinks( $header )
+ )
+ );
+
+ if ( wfRunHooks( 'ApiFormatHighlight', array( $context, $result, $mime, $format ) ) ) {
+ $out->addHTML(
+ Html::element( 'pre', array( 'class' => 'api-pretty-content' ), $result )
+ );
+ }
+
+ $out->output();
+ } else {
+ // For non-HTML output, clear all errors that might have been
+ // displayed if display_errors=On
+ ob_clean();
+
+ echo $this->getBuffer();
}
}
/**
- * The main format printing function. Call it to output the result
- * string to the user. This function will automatically output HTML
- * when format name ends in 'fm'.
+ * Append text to the output buffer.
* @param string $text
*/
public function printText( $text ) {
- if ( $this->mDisabled ) {
- return;
- }
- if ( $this->mBufferResult ) {
- $this->mBuffer = $text;
- } elseif ( $this->getIsHtml() ) {
- echo $this->formatHTML( $text );
- } else {
- // For non-HTML output, clear all errors that might have been
- // displayed if display_errors=On
- // Do this only once, of course
- if ( !$this->mCleared ) {
- ob_clean();
- $this->mCleared = true;
- }
- echo $text;
- }
+ $this->mBuffer .= $text;
}
/**
return $this->mBuffer;
}
+ public function getExamplesMessages() {
+ return array(
+ 'action=query&meta=siteinfo&siprop=namespaces&format=' . $this->getModuleName()
+ => array( 'apihelp-format-example-generic', $this->getFormat() )
+ );
+ }
+
+ public function getHelpUrls() {
+ return 'https://www.mediawiki.org/wiki/API:Data_formats';
+ }
+
/**
- * Set the flag to buffer the result instead of printing it.
- * @param bool $value
+ * To avoid code duplication with the deprecation of dbg, dump, txt, wddx,
+ * and yaml, this method is added to do the necessary work. It should be
+ * removed when those deprecated formats are removed.
*/
- public function setBufferResult( $value ) {
- $this->mBufferResult = $value;
+ protected function markDeprecated() {
+ $fm = $this->getIsHtml() ? 'fm' : '';
+ $name = $this->getModuleName();
+ $this->logFeatureUsage( "format=$name" );
+ $this->setWarning( "format=$name has been deprecated. Please use format=json$fm instead." );
+ }
+
+ /************************************************************************//**
+ * @name Deprecated
+ * @{
+ */
+
+ /**
+ * Specify whether or not sequences like &quot; should be unescaped
+ * to " . This should only be set to true for the help message
+ * when rendered in the default (xmlfm) format. This is a temporary
+ * special-case fix that should be removed once the help has been
+ * reworked to use a fully HTML interface.
+ *
+ * @deprecated since 1.25
+ * @param bool $b Whether or not ampersands should be escaped.
+ */
+ public function setUnescapeAmps( $b ) {
+ wfDeprecated( __METHOD__, '1.25' );
+ $this->mUnescapeAmps = $b;
+ }
+
+ /**
+ * Whether this formatter can format the help message in a nice way.
+ * By default, this returns the same as getIsHtml().
+ * When action=help is set explicitly, the help will always be shown
+ * @deprecated since 1.25
+ * @return bool
+ */
+ public function getWantsHelp() {
+ wfDeprecated( __METHOD__, '1.25' );
+ return $this->getIsHtml();
}
/**
* Sets whether the pretty-printer should format *bold*
+ * @deprecated since 1.25
* @param bool $help
*/
public function setHelp( $help = true ) {
+ wfDeprecated( __METHOD__, '1.25' );
$this->mHelp = $help;
}
/**
* Pretty-print various elements in HTML format, such as xml tags and
* URLs. This method also escapes characters like <
+ * @deprecated since 1.25
* @param string $text
* @return string
*/
protected function formatHTML( $text ) {
+ wfDeprecated( __METHOD__, '1.25' );
+
// Escape everything first for full coverage
$text = htmlspecialchars( $text );
- // encode all comments or tags as safe blue strings
- $text = str_replace( '<', '<span style="color:blue;"><', $text );
- $text = str_replace( '>', '></span>', $text );
+
+ if ( $this->mFormat === 'XML' || $this->mFormat === 'WDDX' ) {
+ // encode all comments or tags as safe blue strings
+ $text = str_replace( '<', '<span style="color:blue;"><', $text );
+ $text = str_replace( '>', '></span>', $text );
+ }
// identify requests to api.php
$text = preg_replace( '#^(\s*)(api\.php\?[^ <\n\t]+)$#m', '\1<a href="\2">\2</a>', $text );
return $text;
}
- public function getExamples() {
- return array(
- 'api.php?action=query&meta=siteinfo&siprop=namespaces&format=' . $this->getModuleName()
- => "Format the query result in the {$this->getModuleName()} format",
- );
- }
-
- public function getHelpUrls() {
- return 'https://www.mediawiki.org/wiki/API:Data_formats';
- }
-
+ /**
+ * @see ApiBase::getDescription
+ * @deprecated since 1.25
+ */
public function getDescription() {
return $this->getIsHtml() ? ' (pretty-print in HTML)' : '';
}
/**
- * To avoid code duplication with the deprecation of dbg, dump, txt, wddx,
- * and yaml, this method is added to do the necessary work. It should be
- * removed when those deprecated formats are removed.
+ * Set the flag to buffer the result instead of printing it.
+ * @deprecated since 1.25, output is always buffered
+ * @param bool $value
*/
- protected function markDeprecated() {
- $fm = $this->getIsHtml() ? 'fm' : '';
- $name = $this->getModuleName();
- $this->logFeatureUsage( "format=$name" );
- $this->setWarning( "format=$name has been deprecated. Please use format=json$fm instead." );
+ public function setBufferResult( $value ) {
}
+
+ /**@}*/
}
/**
- * This printer is used to wrap an instance of the Feed class
- * @ingroup API
+ * For really cool vim folding this needs to be at the end:
+ * vim: foldmarker=@{,@} foldmethod=marker
*/
-class ApiFormatFeedWrapper extends ApiFormatBase {
-
- public function __construct( ApiMain $main ) {
- parent::__construct( $main, 'feed' );
- }
-
- /**
- * Call this method to initialize output data. See execute()
- * @param ApiResult $result
- * @param object $feed An instance of one of the $wgFeedClasses classes
- * @param array $feedItems Array of FeedItem objects
- */
- public static function setResult( $result, $feed, $feedItems ) {
- // Store output in the Result data.
- // This way we can check during execution if any error has occurred
- // Disable size checking for this because we can't continue
- // cleanly; size checking would cause more problems than it'd
- // solve
- $result->addValue( null, '_feed', $feed, ApiResult::NO_SIZE_CHECK );
- $result->addValue( null, '_feeditems', $feedItems, ApiResult::NO_SIZE_CHECK );
- }
-
- /**
- * Feed does its own headers
- *
- * @return null
- */
- public function getMimeType() {
- return null;
- }
-
- /**
- * Optimization - no need to sanitize data that will not be needed
- *
- * @return bool
- */
- public function getNeedsRawData() {
- return true;
- }
-
- /**
- * ChannelFeed doesn't give us a method to print errors in a friendly
- * manner, so just punt errors to the default printer.
- * @return bool
- */
- public function canPrintErrors() {
- return false;
- }
-
- /**
- * This class expects the result data to be in a custom format set by self::setResult()
- * $result['_feed'] - an instance of one of the $wgFeedClasses classes
- * $result['_feeditems'] - an array of FeedItem instances
- */
- public function execute() {
- $data = $this->getResultData();
- if ( isset( $data['_feed'] ) && isset( $data['_feeditems'] ) ) {
- $feed = $data['_feed'];
- $items = $data['_feeditems'];
-
- $feed->outHeader();
- foreach ( $items as & $item ) {
- $feed->outItem( $item );
- }
- $feed->outFooter();
- } else {
- // Error has occurred, print something useful
- ApiBase::dieDebug( __METHOD__, 'Invalid feed class/item' );
- }
- }
-}
dépôts / lhc / web / wiklou.git / blobdiff