View source for Manual:Page content models/pt

<languages />
{{ExtensionTypes}}
{{ContentHandler}}
<span lang="en" dir="ltr" class="mw-content-ltr">The [[ContentHandler]] introduced in [[MediaWiki 1.21]] allows you to add new '''content models''' other than wikitext.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It makes it possible for wiki pages to be composed of data other than wikitext, and represented in any way — for example: Markdown, reStructuredText, icalendar, or a custom XML format.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The display and editing of these content models can be handled in custom ways (''e.g.'' different syntax highlighting, or whole new data-entry forms).</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This page steps through how to create a new content model in an extension.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It assumes some familiarity with general extension development practices. For a brief summary of the requirements, see the [[#Summary|Summary section]] at the bottom of this page.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">A meaningless "[[meta:Wikimedia Cuteness Association|Goat]]" content model will be used for the examples.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You can also examine the DataPages extension, which is part of {{ll|Extension:Examples}}.</span>

{{warning|1=Some sections of this page are outdated. In MW 1.38, Content::getParserOutput and AbstractContent::fillParserOutput were hard-deprecated in favour of ContentRenderer::getParserOutput. Extensions defining a content model should override ContentHandler::fillParserOutput.}}

<span id="Registration"></span>
== Inscrição ==

<div lang="en" dir="ltr" class="mw-content-ltr">
First of all, add the content model's name and handler class to your {{manual|extension.json}}:
</div>

<syntaxhighlight lang=json>
"ContentHandlers": {
	"goat": "MediaWiki\\Extension\\GoatExt\\GoatContentHandler"
}
</syntaxhighlight>

* <span lang="en" dir="ltr" class="mw-content-ltr">The left-hand value here is the name of the content type, it can be any unique string you want, and it lives alongside the five built-in content types: 'wikitext', 'JavaScript', 'CSS', 'plain text', 'JSON'.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This value is exposed to users in places such as [[Special:ChangeContentModel]] and [[Special:Info/Manual:Page content models|page information]].</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The right-hand value is the fully-qualified name of a class that extends {{class doclink|ContentHandler}}.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This will require two new classes to be created, such as <code class=nowrap>\MediaWiki\Extension\GoatExt\GoatContent</code> and <code>\MediaWiki\Extension\GoatExt\GoatContentHandler</code> (make sure their namespace is registered in {{manual|extension.json/Schema#AutoloadNamespaces|AutoloadNamespaces}}).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">More information about these classes is given below.</span>

=== <span lang="en" dir="ltr" class="mw-content-ltr">Optional content model constants</span> ===

<span lang="en" dir="ltr" class="mw-content-ltr">The 'goat' string above is the content model's ID (generally called <code>$modelId</code> in code), and is usually also defined as a constant.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">These constants are defined for all built-in content models, and lots of documentation refers to the "CONTENT_MODEL_XXX" constants.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you have not defined them, this can be a bit confusing.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The definition should be done via the [[Manual:Extension.json/Schema#callback|callback]] item in <code>extension.json</code>. For example:</span>

Em <code>extension.json</code>:

<syntaxhighlight lang=json>
"callback": "MediaWiki\\Extension\\GoatExt\\Hooks::registrationCallback"
</syntaxhighlight>

Em <code>includes/Hooks.php</code>:

<syntaxhighlight lang=php>
namespace MediaWiki\Extension\GoatExt;
class Hooks {
    public static function registrationCallback() {
        // Must match the name used in the 'ContentHandlers' section of extension.json
        define( 'CONTENT_MODEL_GOAT', 'goat' );
    }
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
You don't have to do it this way, and could just use the string.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Assigning content models to pages ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Pages can have their content type manually changed, but it's useful to have them default to the correct one. Two common ways of doing this are by namespace, and by file extension.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">'''By namespace:'''</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you want an entire wiki namespace to have a default content model, you can define it as such in extension.json:</span>

<syntaxhighlight lang="json">
"namespaces": [
	{
		"id": 550,
		"constant": "NS_GOAT",
		"name": "Goat",
		"subpages": false,
		"content": true,
		"defaultcontentmodel": "goat"
	},
	{
		"id": 551,
		"constant": "NS_GOAT_TALK",
		"name": "Goat_talk",
		"subpages": true,
		"content": false,
		"defaultcontentmodel": "wikitext"
	}
]
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
Note that published extensions should register the namespace IDs they use (<code>550</code> and <code>551</code> above) on the {{ll|extension default namespaces}} page.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
'''By file extension:''' If you want to determine the content type by the addition of a quasi-file-type suffix on the wiki page name, you can use the {{hook|ContentHandlerDefaultModelFor}} hook. For example:
</div>

<syntaxhighlight lang=php>
namespace MediaWiki\Extension\GoatExt;
class Hooks {
	public static function onContentHandlerDefaultModelFor( \Title $title, &$model ) {
		// Any page title (in any namespace) ending in '.goat'.
		$ext = '.goat';
		if ( substr( $title->getText(), -strlen( $ext ) ) === $ext ) {
			// This is the constant you defined earlier.
			$model = CONTENT_MODEL_GOAT;
			// If you change the content model, return false.
			return false;
		}
		// If you don't change it, return true.
		return true;
	}
}
</syntaxhighlight>

== <span lang="en" dir="ltr" class="mw-content-ltr">ContentHandler</span> ==

<span lang="en" dir="ltr" class="mw-content-ltr">The next thing to define is the GoatContentHandler class, which is where we also specify what format this content type will be stored as (in this case, text).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">ContentHandlers don't know anything about any ''particular'' page content, but determine the general structure and storage of the content.</span>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatContentHandler extends \ContentHandler {

	public function __construct( $modelId = 'goat' ) {
		parent::__construct( $modelId, [ CONTENT_FORMAT_TEXT ] );
	}

	public function serializeContent( \Content $content, $format = null ) {
	}

	public function unserializeContent( $blob, $format = null ) {
	}

	public function makeEmptyContent() {
		return new GoatContent();
	}

	public function supportsDirectEditing() {
		return true;
	}
}
</syntaxhighlight>

<span id="Content"></span>
Conteúdo
<span lang="en" dir="ltr" class="mw-content-ltr">The <code>GoatContent</code> class is the representation of the content's data, and does not know anything about pages, revisions, or how it is stored in the database.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Beside the required seven inherited methods, you can add other public methods are domain-specific; in this case we want to be able to retrieve the goat's name.</span>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatContent extends \AbstractContent {

	public function __construct( $modelId = 'goat' ) {
		parent::__construct( $modelId );
	}

	public function getTextForSearchIndex() {
	}

	public function getWikitextForTransclusion() {
	}

	public function getTextForSummary( $maxLength = 250 ) {
	}

	public function getNativeData() {
	}

	public function getSize() {
	}

	public function copy() {
	}

	public function isCountable( $hasLinks = null ) {
	}

	public function getName() {
		return 'Garry';
	}
}
</syntaxhighlight>

== <span lang="en" dir="ltr" class="mw-content-ltr">Edit form</span> ==

<span lang="en" dir="ltr" class="mw-content-ltr">Now we've got the skeleton set up, we'll want to try editing a Goat.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To do this, we create {{phpi|GoatContentHandler::getActionOverrides()}} and specify what actions we want to map to what classes.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To start with, we'll just deal with 'edit' (which corresponds to <code>?action=edit</code> in the URL).</span>

<syntaxhighlight lang=php>
	public function getActionOverrides() {
		return [
			'edit' => GoatEditAction::class,
		];
	}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
And we'll create our new <code>GoatEditAction</code> class, basically the same as the core <code>EditAction</code> but using our own <code>GoatEditPage</code>:
</div>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatEditAction extends \EditAction {

	public function show() {
		$this->useTransactionalTimeLimit();
		$editPage = new GoatEditPage( $this->getArticle() );
		$editPage->setContextTitle( $this->getTitle() );
		$editPage->edit();
	}

}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
Our new <code>GoatEditPage</code> class is where the action happens (excuse the pun):
</div>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatEditPage extends \MediaWiki\EditPage\EditPage {

	protected function showContentForm() {
		$out = $this->context->getOutput();

		// Get the data.
		$name = $this->getCurrentContent()->getGoatName();

		// Create the form.
		$nameField = new \OOUI\FieldLayout(
			new \OOUI\TextInputWidget( [ 'name' => 'goat_name', 'value' => $name ] ),
			[ 'label' => 'Name', 'align' => 'left' ]
		);
		$out->addHTML( $nameField );
	}

}
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">You should now be able to edit a page and see your form.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">But when you put data into it, and hit 'preview', you'll see that things are not yet working fully and that you get no output, nor is your submitted text shown again in the form.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">So we must override the 'submit' action as well, with a new <code>GoatSubmitAction</code> class and the addition of {{phpi|'submit' {{=}}> GoatSubmitAction::class,}} to our {{phpi|GoatContentHandler::getActionOverrides()}} method.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Our <code>GoatSubmitAction</code> class should be the same as that of core, but inheriting from our <code>GoatEditAction</code>.</span>

== Exibir ==

<span lang="en" dir="ltr" class="mw-content-ltr">A content model is responsible for producing any required output for display.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This usually involves working with its data and producing HTML in some way, to add to the parser output.</span>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatContent extends \AbstractContent {

	protected function fillParserOutput(
		Title $title, $revId, ParserOptions $options, $generateHtml, ParserOutput &$output
	) {
		// e.g. $output->setText( $html );
	}

}
</syntaxhighlight>

=== <span lang="en" dir="ltr" class="mw-content-ltr">Display a description/documentation</span> ===

<span lang="en" dir="ltr" class="mw-content-ltr">Sometimes you may want to display some information or some documentation for an article that have a custom content model such as JSON.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Actually there aren't [[Special:MyLanguage/Help:System message|system messages]] to display some text above such pages (except for [[MediaWiki:Clearyourcache]] displayed above only JavaScript and CSS pages).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You may want to see [[phab:T206395]] for further details.</span>

== Comparar revisões ==

<span lang="en" dir="ltr" class="mw-content-ltr">The <code>GoatDifferenceEngine</code> class is the representation of the difference between goat contents.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We override the default <code>generateContentDiffBody</code> method to generate a diff.</span>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatDifferenceEngine extends \DifferenceEngine {

	public function generateContentDiffBody( Content $old, Content $new ) {
	}
}
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">In order to tell MediaWiki to use our <code>GoatDifferenceEngine</code>, we overwrite the <code>getDiffEngineClass</code> in our <code>GoatContentHandler</code>.</span>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatContentHandler extends \ContentHandler {

	public function getDiffEngineClass() {
		return GoatDifferenceEngine::class;
	}
}
</syntaxhighlight>

<span id="Summary"></span>
== Resumo ==

<div lang="en" dir="ltr" class="mw-content-ltr">
To implement a new content model with a custom editing form, create the following:
</div>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatContent extends \AbstractContent  {
	public function __construct( $modelId = 'goat' ) {
		parent::__construct($modelId);
	}
	protected function fillParserOutput( \Title $title, $revId, \ParserOptions $options, $generateHtml, \ParserOutput &$output) {}
	public function getTextForSearchIndex() {}
	public function getWikitextForTransclusion() {}
	public function getTextForSummary( $maxLength = 250 ) {}
	public function getNativeData() {}
	public function getSize() {}
	public function copy() {}
	public function isCountable( $hasLinks = null ) {}
}
</syntaxhighlight>

<syntaxhighlight lang=php>
<?php

namespace MediaWiki\Extension\GoatExt;

class GoatContentHandler extends \ContentHandler {	
	public function __construct( $modelId = CONTENT_MODEL_GOAT, $formats = ['text/x-goat'] ) {
		parent::__construct($modelId, $formats);
	}
	protected function getContentClass() {}
	public function supportsDirectEditing() {}
	public function serializeContent( \Content $content, $format = null ) {}
	public function unserializeContent( $blob, $format = null ) {}
	public function makeEmptyContent() {}
	public function getActionOverrides() {}
}
</syntaxhighlight>

<span id="See_also"></span>
== Ver também ==
* {{ll|Manual:Hooks/ContentHandlerDefaultModelFor}}
* {{ll|Help:ChangeContentModel}} - para a documentação do utilizador final sobre a alteração de um modelo de conteúdo.
* {{ll|Extension:Examples}} - para um exemplo de um modelo de conteúdo personalizado (mas ainda sem qualquer forma de edição personalizada).

[[Category:ContentHandler{{#translation:}}]]
[[Category:Extension creation{{#translation:}}]]