4 * A content object represents page content, e.g. the text to show on a page.
5 * Content objects have no knowledge about how they relate to Wiki pages.
8 abstract class Content
{
10 // TODO: create actual fields and document them
13 * @return String a string representing the content in a way useful for building a full text search index.
14 * If no useful representation exists, this method returns an empty string.
16 public abstract function getTextForSearchIndex( );
19 * @return String the wikitext to include when another page includes this content, or false if the content is not
20 * includable in a wikitext page.
22 #TODO: allow native handling, bypassing wikitext representation, like for includable special pages.
23 public abstract function getWikitextForTransclusion( ); #FIXME: use in parser, etc!
26 * Returns a textual representation of the content suitable for use in edit summaries and log messages.
28 * @param int $maxlength maximum length of the summary text
29 * @return String the summary text
31 public abstract function getTextForSummary( $maxlength = 250 );
34 * Returns native represenation of the data. Interpretation depends on the data model used,
35 * as given by getDataModel().
37 * @return mixed the native representation of the content. Could be a string, a nested array
38 * structure, an object, a binary blob... anything, really.
40 public abstract function getNativeData( ); #FIXME: review all calls carefully, caller must be aware of content model!
43 * returns the content's nominal size in bogo-bytes.
47 public abstract function getSize( );
50 * TODO: do we really need to pass a $modelName here?
51 * Seems odd and makes lots of stuff hard (ie having a newEmpty static method in TextContent)
55 public function __construct( $modelName = null ) {
56 $this->mModelName
= $modelName;
60 * Returns the name of the content model used by this content objects.
61 * Corresponds to the CONTENT_MODEL_XXX constants.
63 * @return String the model name
65 public function getModelName() {
66 return $this->mModelName
;
70 * Throws an MWException if $modelName is not the name of the content model
71 * supported by this Content object.
73 protected function checkModelName( $modelName ) {
74 if ( $modelName !== $this->mModelName
) {
75 throw new MWException( "Bad content model: expected " . $this->mModelName
. " but got found " . $modelName );
80 * Conveniance method that returns the ContentHandler singleton for handling the content
81 * model this Content object uses.
83 * Shorthand for ContentHandler::getForContent( $this )
85 * @return ContentHandler
87 public function getContentHandler() {
88 return ContentHandler
::getForContent( $this );
92 * Conveniance method that returns the default serialization format for the content model
93 * model this Content object uses.
95 * Shorthand for $this->getContentHandler()->getDefaultFormat()
97 * @return ContentHandler
99 public function getDefaultFormat() {
100 return $this->getContentHandler()->getDefaultFormat();
104 * Conveniance method that returns the list of serialization formats supported
105 * for the content model model this Content object uses.
107 * Shorthand for $this->getContentHandler()->getSupportedFormats()
109 * @return array of supported serialization formats
111 public function getSupportedFormats() {
112 return $this->getContentHandler()->getSupportedFormats();
116 * Returns true if $format is a supported serialization format for this Content object,
119 * Note that this will always return true if $format is null, because null stands for the
120 * default serialization.
122 * Shorthand for $this->getContentHandler()->isSupportedFormat( $format )
124 * @param String $format the format to check
125 * @return bool whether the format is supported
127 public function isSupportedFormat( $format ) {
129 return true; // this means "use the default"
132 return $this->getContentHandler()->isSupportedFormat( $format );
136 * Throws an MWException if $this->isSupportedFormat( $format ) doesn't return true.
139 * @throws MWException
141 protected function checkFormat( $format ) {
142 if ( !$this->isSupportedFormat( $format ) ) {
143 throw new MWException( "Format $format is not supported for content model " . $this->getModelName() );
148 * Conveniance method for serializing this Content object.
150 * Shorthand for $this->getContentHandler()->serializeContent( $this, $format )
152 * @param null|String $format the desired serialization format (or null for the default format).
153 * @return String serialized form of this Content object
155 public function serialize( $format = null ) {
156 return $this->getContentHandler()->serializeContent( $this, $format );
160 * Returns true if this Content object represents empty content.
162 * @return bool whether this Content object is empty
164 public function isEmpty() {
165 return $this->getSize() == 0;
169 * Returns true if this Content objects is conceptually equivalent to the given Content object.
171 * Will returns false if $that is null.
172 * Will return true if $that === $this.
173 * Will return false if $that->getModleName() != $this->getModelName().
174 * Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
175 * where the meaning of "equal" depends on the actual data model.
177 * Implementations should be careful to make equals() transitive and reflexive:
179 * * $a->equals( $b ) <=> $b->equals( $b )
180 * * $a->equals( $b ) && $b->equals( $c ) ==> $a->equals( $c )
182 * @param Content $that the Content object to compare to
183 * @return bool true if this Content object is euqual to $that, false otherwise.
185 public function equals( Content
$that = null ) {
186 if ( is_null( $that ) ){
190 if ( $that === $this ) {
194 if ( $that->getModelName() !== $this->getModelName() ) {
198 return $this->getNativeData() === $that->getNativeData();
202 * Return a copy of this Content object. The following must be true for the object returned
203 * if $copy = $original->copy()
205 * * get_class($original) === get_class($copy)
206 * * $original->getModelName() === $copy->getModelName()
207 * * $original->equals( $copy )
209 * If and only if the Content object is imutable, the copy() method can and should
210 * return $this. That is, $copy === $original may be true, but only for imutable content
213 * @return Content. A copy of this object
215 public abstract function copy( );
218 * Returns true if this content is countable as a "real" wiki page, provided
219 * that it's also in a countable location (e.g. a current revision in the main namespace).
221 * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
222 * to avoid redundant parsing to find out.
225 public abstract function isCountable( $hasLinks = null ) ;
228 * @param IContextSource $context
230 * @param null|ParserOptions $options
231 * @param Boolean $generateHtml whether to generate Html (default: true). If false,
232 * the result of calling getText() on the ParserOutput object returned by
233 * this method is undefined.
235 * @return ParserOutput
237 public abstract function getParserOutput( IContextSource
$context, $revId = null, ParserOptions
$options = NULL, $generateHtml = true );
240 * Construct the redirect destination from this content and return an
241 * array of Titles, or null if this content doesn't represent a redirect.
242 * The last element in the array is the final destination after all redirects
243 * have been resolved (up to $wgMaxRedirects times).
245 * @return Array of Titles, with the destination last
247 public function getRedirectChain() {
252 * Construct the redirect destination from this content and return an
253 * array of Titles, or null if this content doesn't represent a redirect.
254 * This will only return the immediate redirect target, useful for
255 * the redirect table and other checks that don't need full recursion.
257 * @return Title: The corresponding Title
259 public function getRedirectTarget() {
264 * Construct the redirect destination from this content and return the
265 * Title, or null if this content doesn't represent a redirect.
266 * This will recurse down $wgMaxRedirects times or until a non-redirect target is hit
267 * in order to provide (hopefully) the Title of the final destination instead of another redirect.
271 public function getUltimateRedirectTarget() {
275 public function isRedirect() {
276 return $this->getRedirectTarget() != null;
280 * Returns the section with the given id.
282 * The default implementation returns null.
284 * @param String $sectionId the section's id, given as a numeric string. The id "0" retrieves the section before
285 * the first heading, "1" the text between the first heading (inluded) and the second heading (excluded), etc.
286 * @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported
288 public function getSection( $sectionId ) {
293 * Replaces a section of the content and returns a Content object with the section replaced.
295 * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
296 * @param $with Content: new content of the section
297 * @param $sectionTitle String: new section's subject, only if $section is 'new'
298 * @return string Complete article text, or null if error
300 public function replaceSection( $section, Content
$with, $sectionTitle = '' ) {
305 * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
307 * @param Title $title
309 * @param null|ParserOptions $popts
312 public function preSaveTransform( Title
$title, User
$user, ParserOptions
$popts = null ) {
317 * Returns a new WikitextContent object with the given section heading prepended, if supported.
318 * The default implementation just returns this Content object unmodified, ignoring the section header.
320 * @param $header String
323 public function addSectionHeader( $header ) {
328 * Returns a Content object with preload transformations applied (or this object if no transformations apply).
330 * @param Title $title
331 * @param null|ParserOptions $popts
334 public function preloadTransform( Title
$title, ParserOptions
$popts = null ) {
338 # TODO: handle ImagePage and CategoryPage
339 # TODO: hook into dump generation to serialize and record model and format!
341 # TODO: make sure we cover lucene search / wikisearch.
342 # TODO: make sure ReplaceTemplates still works
343 # TODO: nice&sane integration of GeSHi syntax highlighting
344 # [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a config to set the class which handles syntax highlighting
345 # [12:00] <vvv> And default it to a DummyHighlighter
347 # TODO: make sure we cover the external editor interface (does anyone actually use that?!)
349 # TODO: tie into API to provide contentModel for Revisions
350 # TODO: tie into API to provide serialized version and contentFormat for Revisions
351 # TODO: tie into API edit interface
352 # TODO: make EditForm plugin for EditPage
354 # XXX: isCacheable( ) # can/should we do this here?
358 * Content object implementation for representing flat text.
360 * TextContent instances are imutable
362 abstract class TextContent
extends Content
{
364 public function __construct( $text, $modelName = null ) {
365 parent
::__construct( $modelName );
367 $this->mText
= $text;
370 public function copy() {
371 return $this; #NOTE: this is ok since TextContent are imutable.
374 public function getTextForSummary( $maxlength = 250 ) {
377 $text = $this->getNativeData();
379 $truncatedtext = $wgContLang->truncate(
380 preg_replace( "/[\n\r]/", ' ', $text ),
381 max( 0, $maxlength ) );
383 return $truncatedtext;
387 * returns the content's nominal size in bogo-bytes.
389 public function getSize( ) {
390 $text = $this->getNativeData( );
391 return strlen( $text );
395 * Returns true if this content is not a redirect, and $wgArticleCountMethod is "any".
397 * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here,
398 * to avoid redundant parsing to find out.
400 public function isCountable( $hasLinks = null ) {
401 global $wgArticleCountMethod;
403 if ( $this->isRedirect( ) ) {
407 if ( $wgArticleCountMethod === 'any' ) {
415 * Returns the text represented by this Content object, as a string.
417 * @return String the raw text
419 public function getNativeData( ) {
420 $text = $this->mText
;
425 * Returns the text represented by this Content object, as a string.
427 * @return String the raw text
429 public function getTextForSearchIndex( ) { #FIXME: use!
430 return $this->getNativeData();
434 * Returns the text represented by this Content object, as a string.
436 * @return String the raw text
438 public function getWikitextForTransclusion( ) { #FIXME: use!
439 return $this->getNativeData();
443 * Returns a generic ParserOutput object, wrapping the HTML returned by getHtml().
445 * @return ParserOutput representing the HTML form of the text
447 public function getParserOutput( IContextSource
$context, $revId = null, ParserOptions
$options = null, $generateHtml = true ) {
448 # generic implementation, relying on $this->getHtml()
450 if ( $generateHtml ) $html = $this->getHtml( $options );
453 $po = new ParserOutput( $html );
458 protected abstract function getHtml( );
462 class WikitextContent
extends TextContent
{
464 public function __construct( $text ) {
465 parent
::__construct($text, CONTENT_MODEL_WIKITEXT
);
467 $this->mDefaultParserOptions
= null; #TODO: use per-class static member?!
470 protected function getHtml( ) {
471 throw new MWException( "getHtml() not implemented for wikitext. Use getParserOutput()->getText()." );
474 public function getDefaultParserOptions() {
475 global $wgUser, $wgContLang;
477 if ( !$this->mDefaultParserOptions
) { #TODO: use per-class static member?!
478 $this->mDefaultParserOptions
= ParserOptions
::newFromUserAndLang( $wgUser, $wgContLang );
481 return $this->mDefaultParserOptions
;
485 * Returns a ParserOutput object resulting from parsing the content's text using $wgParser.
489 * @param IContextSource|null $context
491 * @param null|ParserOptions $options
492 * @param bool $generateHtml
494 * @return ParserOutput representing the HTML form of the text
496 public function getParserOutput( IContextSource
$context, $revId = null, ParserOptions
$options = null, $generateHtml = true ) {
500 $options = $this->getDefaultParserOptions();
503 $po = $wgParser->parse( $this->mText
, $context->getTitle(), $options, true, true, $revId );
509 * Returns the section with the given id.
511 * @param String $sectionId the section's id
512 * @return Content|false|null the section, or false if no such section exist, or null if sections are not supported
514 public function getSection( $section ) {
517 $text = $this->getNativeData();
518 $sect = $wgParser->getSection( $text, $section, false );
520 return new WikitextContent( $sect );
524 * Replaces a section in the wikitext
526 * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new"
527 * @param $with Content: new content of the section
528 * @param $sectionTitle String: new section's subject, only if $section is 'new'
529 * @return Content Complete article content, or null if error
531 public function replaceSection( $section, Content
$with, $sectionTitle = '' ) {
532 wfProfileIn( __METHOD__
);
534 $myModelName = $this->getModelName();
535 $sectionModelName = $with->getModelName();
537 if ( $sectionModelName != $myModelName ) {
538 throw new MWException( "Incompatible content model for section: document uses $myModelName, section uses $sectionModelName." );
541 $oldtext = $this->getNativeData();
542 $text = $with->getNativeData();
544 if ( $section === '' ) {
545 return $with; #XXX: copy first?
546 } if ( $section == 'new' ) {
547 # Inserting a new section
548 $subject = $sectionTitle ?
wfMsgForContent( 'newsectionheaderdefaultlevel', $sectionTitle ) . "\n\n" : '';
549 if ( wfRunHooks( 'PlaceNewSection', array( $this, $oldtext, $subject, &$text ) ) ) {
550 $text = strlen( trim( $oldtext ) ) > 0
551 ?
"{$oldtext}\n\n{$subject}{$text}"
552 : "{$subject}{$text}";
555 # Replacing an existing section; roll out the big guns
558 $text = $wgParser->replaceSection( $oldtext, $section, $text );
561 $newContent = new WikitextContent( $text );
563 wfProfileOut( __METHOD__
);
568 * Returns a new WikitextContent object with the given section heading prepended.
570 * @param $header String
573 public function addSectionHeader( $header ) {
574 $text = wfMsgForContent( 'newsectionheaderdefaultlevel', $header ) . "\n\n" . $this->getNativeData();
576 return new WikitextContent( $text );
580 * Returns a Content object with pre-save transformations applied (or this object if no transformations apply).
582 * @param Title $title
584 * @param null|ParserOptions $popts
587 public function preSaveTransform( Title
$title, User
$user, ParserOptions
$popts = null ) {
590 if ( $popts == null ) $popts = $this->getDefaultParserOptions();
592 $text = $this->getNativeData();
593 $pst = $wgParser->preSaveTransform( $text, $title, $user, $popts );
595 return new WikitextContent( $pst );
599 * Returns a Content object with preload transformations applied (or this object if no transformations apply).
601 * @param Title $title
602 * @param null|ParserOptions $popts
605 public function preloadTransform( Title
$title, ParserOptions
$popts = null ) {
608 if ( $popts == null ) $popts = $this->getDefaultParserOptions();
610 $text = $this->getNativeData();
611 $plt = $wgParser->getPreloadText( $text, $title, $popts );
613 return new WikitextContent( $plt );
616 public function getRedirectChain() {
617 $text = $this->getNativeData();
618 return Title
::newFromRedirectArray( $text );
621 public function getRedirectTarget() {
622 $text = $this->getNativeData();
623 return Title
::newFromRedirect( $text );
626 public function getUltimateRedirectTarget() {
627 $text = $this->getNativeData();
628 return Title
::newFromRedirectRecurse( $text );
632 * Returns true if this content is not a redirect, and this content's text is countable according to
633 * the criteria defiend by $wgArticleCountMethod.
635 * @param Bool $hasLinks if it is known whether this content contains links, provide this information here,
636 * to avoid redundant parsing to find out.
637 * @param IContextSource $context context for parsing if necessary
639 public function isCountable( $hasLinks = null, IContextSource
$context = null ) {
640 global $wgArticleCountMethod, $wgRequest;
642 if ( $this->isRedirect( ) ) {
646 $text = $this->getNativeData();
648 switch ( $wgArticleCountMethod ) {
652 if ( $text === false ) {
653 $text = $this->getRawText();
655 return strpos( $text, ',' ) !== false;
657 if ( $hasLinks === null ) { # not known, find out
658 if ( !$context ) { # make dummy context
659 //XXX: caller of this method often knows the title, but not a context...
660 $context = new RequestContext( $wgRequest );
663 $po = $this->getParserOutput( $context, null, null, false );
664 $links = $po->getLinks();
665 $hasLinks = !empty( $links );
672 public function getTextForSummary( $maxlength = 250 ) {
673 $truncatedtext = parent
::getTextForSummary( $maxlength );
675 #clean up unfinished links
676 #XXX: make this optional? wasn't there in autosummary, but required for deletion summary.
677 $truncatedtext = preg_replace( '/\[\[([^\]]*)\]?$/', '$1', $truncatedtext );
679 return $truncatedtext;
684 class MessageContent
extends TextContent
{
685 public function __construct( $msg_key, $params = null, $options = null ) {
686 parent
::__construct(null, CONTENT_MODEL_WIKITEXT
); #XXX: messages may be wikitext, html or plain text! and maybe even something else entirely.
688 $this->mMessageKey
= $msg_key;
690 $this->mParameters
= $params;
692 if ( is_null( $options ) ) {
695 elseif ( is_string( $options ) ) {
696 $options = array( $options );
699 $this->mOptions
= $options;
701 $this->mHtmlOptions
= null;
705 * Returns the message as rendered HTML, using the options supplied to the constructor plus "parse".
707 protected function getHtml( ) {
708 $opt = array_merge( $this->mOptions
, array('parse') );
710 return wfMsgExt( $this->mMessageKey
, $this->mParameters
, $opt );
715 * Returns the message as raw text, using the options supplied to the constructor minus "parse" and "parseinline".
717 public function getNativeData( ) {
718 $opt = array_diff( $this->mOptions
, array('parse', 'parseinline') );
720 return wfMsgExt( $this->mMessageKey
, $this->mParameters
, $opt );
726 class JavaScriptContent
extends TextContent
{
727 public function __construct( $text ) {
728 parent
::__construct($text, CONTENT_MODEL_JAVASCRIPT
);
731 protected function getHtml( ) {
733 $html .= "<pre class=\"mw-code mw-js\" dir=\"ltr\">\n";
734 $html .= htmlspecialchars( $this->getNativeData() );
735 $html .= "\n</pre>\n";
742 class CssContent
extends TextContent
{
743 public function __construct( $text ) {
744 parent
::__construct($text, CONTENT_MODEL_CSS
);
747 protected function getHtml( ) {
749 $html .= "<pre class=\"mw-code mw-css\" dir=\"ltr\">\n";
750 $html .= htmlspecialchars( $this->getNativeData() );
751 $html .= "\n</pre>\n";
757 #FUTURE: special type for redirects?!
758 #FUTURE: MultipartMultipart < WikipageContent (Main + Links + X)
759 #FUTURE: LinksContent < LanguageLinksContent, CategoriesContent
760 #EXAMPLE: CoordinatesContent
761 #EXAMPLE: WikidataContent