From 7474d1388ad04ceda8039aa1fe7eb743b50d56db Mon Sep 17 00:00:00 2001 From: Tim Starling Date: Mon, 22 Oct 2012 11:58:05 +1100 Subject: [PATCH] Document what ParserOutput::setProperty() is for Change-Id: I88735b1ebc9b8423b4fbe7b196dfc914f95818fd --- includes/parser/ParserOutput.php | 40 +++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php index b6bcf63264..28d07f1479 100644 --- a/includes/parser/ParserOutput.php +++ b/includes/parser/ParserOutput.php @@ -346,7 +346,45 @@ class ParserOutput extends CacheTime { } /** - * Set a property to be cached in the DB + * Set a property to be stored in the page_props database table. + * + * page_props is a key value store indexed by the page ID. This allows + * the parser to set a property on a page which can then be quickly + * retrieved given the page ID or via a DB join when given the page + * title. + * + * setProperty() is thus used to propagate properties from the parsed + * page to request contexts other than a page view of the currently parsed + * article. + * + * Some applications examples: + * + * * To implement hidden categories, hiding pages from category listings + * by storing a property. + * + * * Overriding the displayed article title. + * @see ParserOutput::setDisplayTitle() + * + * * To implement image tagging, for example displaying an icon on an + * image thumbnail to indicate that it is listed for deletion on + * Wikimedia Commons. + * This is not actually implemented, yet but would be pretty cool. + * + * Do not use setProperty() to set a property which is only used in a + * context where the ParserOutput object itself is already available, for + * example a normal page view. There is no need to save such a property + * in the database since it the text is already parsed. You can just hook + * OutputPageParserOutput and get your data out of the ParserOutput object. + * + * If you are writing an extension where you want to set + * a property in the parser which is used by an OutputPageParserOutput hook, + * just use a custom variable within the ParserOutput object: + * + * @par Example: + * @code + * $parser->getOutput()->my_ext_foo = '...'; + * @endcode + * */ public function setProperty( $name, $value ) { $this->mProperties[$name] = $value; -- 2.20.1