Ejegg has submitted this change and it was merged.
Change subject: Document BannerRenderer
......................................................................
Document BannerRenderer
Change-Id: I48c789250b6303e004dd79349ae3b2f5a19c39b4
---
M includes/BannerRenderer.php
1 file changed, 78 insertions(+), 1 deletion(-)
Approvals:
Ejegg: Looks good to me, approved
jenkins-bot: Verified
diff --git a/includes/BannerRenderer.php b/includes/BannerRenderer.php
index b42c772..67a95b0 100644
--- a/includes/BannerRenderer.php
+++ b/includes/BannerRenderer.php
@@ -1,5 +1,8 @@
<?php
+/**
+ * Produce HTML and JSON output for a given banner and context
+ */
class BannerRenderer {
/**
* @var IContextSource $context
@@ -22,6 +25,18 @@
protected $debug;
+ /**
+ * Creates a new renderer for a given banner and context
+ *
+ * @param IContextSource $context UI context, including language.
+ *
+ * @param Banner $banner Banner to be rendered.
+ *
+ * @param string $campaignName Which campaign we're serving. This is
+ * substituted in for {{{campaign}}} magic word.
+ *
+ * @param boolean $debug If false, minify the output.
+ */
function __construct( IContextSource $context, Banner $banner,
$campaignName = null, $debug = false ) {
$this->context = $context;
@@ -36,6 +51,11 @@
// $this->mixinController->registerMagicWord( 'banner', array(
$this, 'getBanner' ) );
}
+ /**
+ * Produce a link to edit the banner
+ *
+ * @return string Edit URL.
+ */
function linkTo() {
return Linker::link(
SpecialPage::getTitleFor( 'CentralNoticeBanners',
"edit/{$this->banner->getName()}" ),
@@ -44,7 +64,15 @@
);
}
- // TODO: consolidate with above function
+ /**
+ * Get the edit link for a banner (static version).
+ *
+ * TODO: consolidate with above function
+ *
+ * @param string $name Banner name.
+ *
+ * @return string Edit URL.
+ */
public static function linkToBanner( $name ) {
return Linker::link(
SpecialPage::getTitleFor( 'CentralNoticeBanners',
"edit/{$name}" ),
@@ -55,6 +83,8 @@
/**
* Render the banner as an html fieldset
+ *
+ * @return string HTML fragment
*/
function previewFieldSet() {
global $wgNoticeBannerPreview;
@@ -91,6 +121,8 @@
* Get the body of the banner, with all transformations applied.
*
* FIXME: "->inLanguage( $context->getLanguage() )" is necessary due to
a bug in DerivativeContext
+ *
+ * @return string HTML fragment for the banner body.
*/
function toHtml() {
global $wgNoticeUseLanguageConversion;
@@ -109,10 +141,21 @@
return $bannerHtml;
}
+ /**
+ * Render any preload javascript for this banner
+ *
+ * @return string JS snippet.
+ */
function getPreloadJs() {
return $this->substituteMagicWords( $this->getPreloadJsRaw() );
}
+ /**
+ * Unrendered blob of preload javascript snippets
+ *
+ * This is only used internally, and will be parsed for magic words
+ * before use.
+ */
function getPreloadJsRaw() {
$snippets = $this->mixinController->getPreloadJsSnippets();
$bundled = array();
@@ -132,6 +175,14 @@
return implode( "\n", $bundled );
}
+ /**
+ * Render any ResourceLoader modules
+ *
+ * If the banner includes RL mixins, render the JS (TODO: and CSS) and
+ * return here.
+ *
+ * @return string HTML snippet.
+ */
function getResourceLoaderHtml() {
$modules = $this->mixinController->getResourceLoaderModules();
if ( $modules ) {
@@ -146,6 +197,15 @@
return "";
}
+ /**
+ * Replace magic word placeholders with their value
+ *
+ * We rely on $this->renderMagicWord to do the heavy lifting.
+ *
+ * @param string $contents Raw contents to be processed.
+ *
+ * @return string Rendered contents.
+ */
function substituteMagicWords( $contents ) {
return preg_replace_callback(
'/{{{([^}:]+)(?:[:]([^}]*))?}}}/',
@@ -154,12 +214,29 @@
);
}
+ /**
+ * Get a list of magic words provided or dependened upon by this banner
+ *
+ * @return array List of magic word names.
+ */
function getMagicWords() {
$words = array( 'banner', 'campaign' );
$words = array_merge( $words,
$this->mixinController->getMagicWords() );
return $words;
}
+ /**
+ * Get the value for a magic word
+ *
+ * @param array $re_matches Funky PCRE callback param having the form,
+ * array(
+ * 0 => full match, ignored,
+ * 1 => magic word name,
+ * 2 => optional arguments to the magic word replacement
function
+ * );
+ *
+ * @return string HTML fragment with the resulting value.
+ */
protected function renderMagicWord( $re_matches ) {
$field = $re_matches[1];
if ( $field === 'banner' ) {
--
To view, visit https://gerrit.wikimedia.org/r/182897
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I48c789250b6303e004dd79349ae3b2f5a19c39b4
Gerrit-PatchSet: 3
Gerrit-Project: mediawiki/extensions/CentralNotice
Gerrit-Branch: master
Gerrit-Owner: Awight <awi...@wikimedia.org>
Gerrit-Reviewer: AndyRussG <andrew.green...@gmail.com>
Gerrit-Reviewer: Awight <awi...@wikimedia.org>
Gerrit-Reviewer: Ejegg <eeggles...@wikimedia.org>
Gerrit-Reviewer: Katie Horn <kh...@wikimedia.org>
Gerrit-Reviewer: Mwalker <mwal...@khaosdev.com>
Gerrit-Reviewer: Ssmith <ssm...@wikimedia.org>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
