Extension:NewsBulletins

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
Crystal Clear action run.svg
newsBulletins
Release status: unmaintained
NewsBulletins.png
Implementation Parser extension, Tag
Description Adds a news/bulletins block to any page.
Author(s) ruggerittalk
Latest version 1.1 (2010-03-05)
MediaWiki 1.5
License GNU Free Documentation License
Download No link
Translate the NewsBulletins extension if it is available at translatewiki.net
Check usage and version matrix.

The NewsBulletins extension adds the ability to create a news/bulletins block on a wiki page. This can be useful to easily update users on what's going on around the wiki by adding items with a category addition, rather than static page editing.

Usage[edit]

This extension is used to create a block that displays new/bulletins for a site. This will be really helpful for categorizing quick bulletins and having them automatically added the block on the frontpage or a page with heavy traffic. One can add a block anywhere using the following tag:

<newsBulletins></newsBulletins>

To add articles to the news/bulletins, add the category "Bulletins" to an article and it will be added to the display. There are many options for customizing that are listed below.

Download instructions[edit]

Please cut and paste the code found below and place it in:

$IP/extensions/NewsBulletins/NewsBulletins.php

Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php .

Installation[edit]

To install this extension, add the following to LocalSettings.php :

require_once("$IP/extensions/NewsBulletins/NewsBulletins.php");

To add the custom CSS (display parameters), edit the page MediaWiki:Common.css by adding the following lines:

/**
 * News-Bulletins Css
 * @version 2008-07-11
 * @author ruggerit
 * @location MediaWiki:Common.css
 */

.news-bulletin {
  border: 1px solid #000;
  background-color: #ddd;
  padding:5px;
  width:300px;
  text-align:left;
}

.news-bulletin-header {
  font-size:14px;
  padding:3px;
  text-decoration:underline;
  font-style:italic;
  font-weight:bold;
}

.news-bulletin-title {
  font-weight:bold;
  font-size:13px;
}

.news-bulletin-title a{
  color:#000;
}
.news-bulletin-title a:visited{
  color:#000;
}

.news-bulletin-text {
  font-size:12px;
  padding-left:5px;
}

.news-bulletin-time {
  font-size:10px;
  font-style:italic;
  text-align:right;
}

Configuration parameters[edit]

There are many options available through this extension. Please report any issues or requested options. Options are added within the <newsBulletins> tag like the following:

Wiki text. <newsBulletins>option=value|anotheroption=differentvalue</newsBulletins> Wiki text.

NOTE: Only add options if you are changing values from the default. Adding an option with the default value will not cause problems, but it is redundant and will be dropped. The following options are available to use:

  • category
Default: "Bulletins"
This is the category that the extension will use to find your news/bulletins. Add this category to pages to have them picked up by this extension.
  • header
Default: null
Providing a header will give the block a header (title, banner) that is the text supplied.
  • links
Default: true
Changing links to 'false' or 'off' will turn the title links off of each entry.
  • limit
Default: 5
Tunes the number of pages that are returned to the block. Value [1,99] (That is between 1 and 99).
  • order
Default: DESC
Changing order to 'asc' or 'flip' will reverse the sort order of the pages to oldest first.
  • timestamp
Default: true
Changing timestamp to 'false' or 'off' will hide the timestamp that appears after every page item.

Using Teasers[edit]

If you desire to have the news/bulletin block only display teasers rather than the full article without losing the entire article text use the following feature. Add the <teaser> tag to your page with the desired teaser text to have this extension use this text rather than the full article text. When viewing the article, the teaser text will not be visible. Example page using the <teaser> tag function:

[[Category:Bulletins]]<teaser>Interested in this article?</teaser>Main article text to be displayed on the page.

The resulting page will not show the teaser text, but will show the main article text. This extension will use the text provided within the <teaser> tag as its text. If no <teaser> tag is found, the extension will use the full page text as its teaser, so this option is NOT required.

Using Titles[edit]

If you desire to have the news/bulletin block display a specific title instead of the articlename of the news bulletin.Add the <newstitle> tag to your page with the desired title text to have this extension use this text rather than the articlename of the news bulletin. When viewing the article, the title text will not be visible. Example page using the <newstitle> tag function:

[[Category:Bulletins]]<newstitle>My first news!</newstitle><teaser>Interested in this article?</teaser>Main article text to be displayed on the page.

The resulting page will not show the title text, but will show the main article text. This extension will use the text provided within the <newstitle> tag as its text. If no <newstitle> tag is found, the extension will use the articlename of the news bulletin as its teaser, so this option is NOT required.

Examples[edit]

Get a basic news/bulletins block using the category 'Bulletins':

<newsBulletins></newsBulletins>

Get a block with limit 10 using category 'PressEvents':

<newsBulletins>category=PressEvents|limit=10</newsBulletins>

Get a block with no link, no timestamps, and in reverse order using the category 'Bulletins' and header 'News - ':

<newsBulletins>header=News - |links=off|timestamp=false|order=flip</newsBulletins>

Code[edit]

Please cut and paste the code found below and place it in:

$IP/extensions/NewsBulletins/NewsBulletins.php

Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php .

<?php

/**
 * newsBulletins Extension
 * @desc Provides the user with an attractive newBulletins block to quickly inform visitors of happenings.
 * @version 2008-07-11
 * @path $IP/extensions/NewsBulletins/NewsBulletins.php
 * @package MediaWiki.Extensions
 * @dependencies MediaWiki
 * @acknowledgement Thanks to Barrylb and the Calendar extension, [[Special:MyLanguage/Extension:Calendar (Barrylb)|Extension:Calendar (Barrylb)]] for help with the code. Much of this code is based on the calendar code. This project would not be possible without the calendar extension. Also, thanks to Andy no-PBB Roberts for help with regular expressions.
 */
 
/**
 *===========================================================================================================
 *===> How to use this extension
 *===|
 *===| This extension works by finding the <newsBulletins> tag within a wiki page. An example of this:
 *===|    "This is my wiki page text. <newsBulletins></newsBulletins> More text for the page."
 *===| Once the wiki detects this, it will render a block displaying news/bulletins where the tag was.
 *===|
 *=== +Installing
 *===| Place this code into the file at /extensions/NewsBulletins/NewsBulletins.php, then add the
 *===|  following code to your LocalSettings.php file:
 *===|    "require_once("$IP/extensions/NewsBulletins/NewsBulletins.php");"
 *===| You will also need to edit the MediaWiki:Common.css page to get display options. Navigate to the
 *===|  page titled 'MediaWiki:Common.css' and add the following css just as you would edit a normal page:
 
.news-bulletin {
  border: 1px solid #000;
  background-color: #ddd;
  padding:5px;
  width:300px;
  text-align:left;
}
 
.news-bulletin-header {
  font-size:14px;
  padding:3px;
  text-decoration:underline;
  font-style:italic;
  font-weight:bold;
}
 
.news-bulletin-title {
  font-weight:bold;
  font-size:13px;
}
 
.news-bulletin-title a{
  color:#000;
}
.news-bulletin-title a:visited{
  color:#000;
}
 
.news-bulletin-text {
  font-size:12px;
  padding-left:5px;
}
 
.news-bulletin-time {
  font-size:10px;
  font-style:italic;
  text-align:right;
}
 
 *===|
 *===| Of course, feel free to edit all of this css as you please to customize the look of the block.
 *===|
 *=== +Options
 *===| 
 *===| There are many options available through this extension. Please report any issues or requested options.
 *===| Options are added within the <newsBulletins> tag like the following:
 *===|    "Wiki text. <newsBulletins>option=value|anotheroption=differentvalue</newsBulletins> Wiki text."
 *===| NOTE: Only add options if you are changing values from the default. Adding an option with the default value
 *===|  will not cause problems, but it is redundant and will be dropped.
 *===| The following options are available to use:
 *===|
 *=== *category
 *===| Default: "Bulletins"
 *===| This is the category that the extension will use to find your news/bulletins. Add this category to pages
 *===|  to have them picked up by this extension.
 *===|
 *=== *header
 *===| Default: null
 *===| Providing a header will give the block a header (title, banner) that is the text supplied.
 *===|
 *=== *links
 *===| Default: true
 *===| Changing links to 'false' or 'off' will turn the title links off of each entry.
 *===|
 *=== *limit
 *===| Default: 5
 *===| Tunes the number of pages that are returned to the block. Value [1,99] (That is between 1 and 99).
 *===|
 *=== *order
 *===| Default: DESC
 *===| Changing order to 'asc' or 'flip' will reverse the sort order of the pages to oldest first.
 *===|
 *=== *timestamp
 *===| Default: true
 *===| Changing timestamp to 'false' or 'off' will hide the timestamp that appears after every page item.
 *===|
 *=== +Using Teasers
 *===|
 *===| If you desire to have the news/bulletin block only display teasers rather than the full article without
 *===|  losing the entire article text use the following feature.
 *===| Add the <teaser> tag to your page with the desired teaser text to have this extension use this text rather
 *===|  than the full article text. When viewing the article, the teaser text will not be visible.
 *===| Example page using the <teaser> tag function:
 *===|    "[[Category:Bulletins]]<teaser>Interested in this article?</teaser>Main article text to be displayed on the page."
 *===| The resulting page will not show the teaser text, but will show the main article text. This extension will use
 *===|  the text provided within the <teaser> tag as its text.
 *===| If no <teaser> tag is found, the extension will use the full page text as its teaser, so this option is NOT required.
 *===|
 *=== +Using Titles
 *===|
 *===| If you desire to have the news/bulletin block display a specific title instead of the articlename of the news bulletin.
 *===| Add the <newstitle> tag to your page with the desired title text to have this extension use this text rather
 *===|  than the articlename of the news bulletin. When viewing the article, the title text will not be visible.
 *===| Example page using the <newstitle> tag function:
 *===|    "[[Category:Bulletins]]<newstitle>My first news!</newstitle><teaser>Interested in this article?</teaser>Main article text to be displayed on the page."
 *===| The resulting page will not show the title text, but will show the main article text. This extension will use
 *===|  the text provided within the <newstitle> tag as its text.
 *===| If no <newstitle> tag is found, the extension will use the articlename of the news bulletin as its teaser, so this option is NOT required.
 *===|
 *=== +Examples
 *===|
 *===| Get a basic news/bulletins block using the category 'Bulletins':
 *===|    "<newsBulletins></newsBulletins>"
 *===| Get a block with limit 10 using category 'PressEvents':
 *===|    "<newsBulletins>category=PressEvents|limit=10</newsBulletins>"
 *===| Get a block with no link, no timestamps, and in reverse order using the category 'Bulletins' and header 'News - ':
 *===|    "<newsBulletins>header=News - |links=off|timestamp=false|order=flip</newsBulletins>"
 *===|
 *=== +Feedback
 *===| Your feedback is greatly appreciated. If you find a bug, need help, or have requests, please post them on the
 *===|  MediaWiki extension page to provide the best possible extension. Enjoy.
 *===|
 *=== +Thanks
 *===| A special thanks to Barrylb and the Calendar extension, [[Special:MyLanguage/Extension:Calendar (Barrylb)|Extension:Calendar (Barrylb)]]
 *===|  for inspiration and lots of coding help. This extension not possible without code from the calendar extension.
 *===|
 *===| ruggerit - 2008-07-11
 *===| modified by Alvinos - 2010-03-05
 *===========================================================================================================
 */
 
//Adding extension into MediaWiki
$wgExtensionFunctions[] = "wfNewsBulletinsExtension";
$wgExtensionFunctions[] = "wfTeaserCatch";
$wgExtensionFunctions[] = "wfTitleCatch";
$wgExtensionCredits['parserhook'][] = array(
  	'name' => 'newsBulletins',
  	'author' => 'ruggerit',
  	'description' => 'Allows to adds news bulletins',
  	'url' => 'https://www.mediawiki.org/wiki/Extension:NewsBulletins',
  	'version'=>'1.1'
);
 
/**
 * wfNewsBulletinsExtension
 * @desc Creates hook for <newsBulletins> tag.
 */
function wfNewsBulletinsExtension() {
  	global $wgParser;
  	$wgParser->setHook( "newsBulletins", "createNewsBulletins" );
}
 
/**
 * wfTeaserCatch
 * @desc Creates hook for <teaser> tags.
 */
function wfTeaserCatch() {
  	global $wgParser;
  	$wgParser->setHook( "teaser", "removeTeaser" );
}

/**
 * wfTitleCatch
 * @desc Creates hook for <newstitle> tags.
 */
function wfTitleCatch() {
  	global $wgParser;
  	$wgParser->setHook( "newstitle", "removeTitle" );
}
 
/**
 * removeTeaser
 * @desc Removes all text that is contained within <teaser> tags.
 */
function removeTeaser($input, $args, $parser) {
	return "";
}

/**
 * removeTitle
 * @desc Removes all text that is contained within <title> tags.
 */
function removeTitle($input, $args, $parser) {
	return "";
}
 
/**
 * createNewsBulletins
 * @desc Checks for input, then creates newsBulletins block.
 */
function createNewsBulletins($input, $args, $parser) {
	$newsBulletins = new newsBulletins();
 
	//Check for category input
	preg_match('/category=([^|]+)/', $input, $finds[0]);
	if (isset($finds[0][1])) {
		$newsBulletins->changeCategory($finds[0][1]);
	}
 
	//Check for header input
	preg_match('/header=([^|]+)/',$input,$finds[1]);
	if (isset($finds[1][1])) {
		$newsBulletins->changeHeader($finds[1][1]);
	}
 
	//Check links toggle
	if ((strpos($input,"links=false") !== false) || (strpos($input,"links=off") !== false)) {
		$newsBulletins->changeLinks(false);
	}
 
	//Check for limit input
	preg_match('/limit=(\d{1,2})/',$input,$finds[2]);
	if (isset($finds[2][1])) {
		$newsBulletins->changeLimit($finds[2][1]);
	}
 
	//Check order toggle
	if ((strpos($input,"order=asc") !== false) || (strpos($input,"order=flip") !== false)) {
		$newsBulletins->changeOrder("ASC");
	}
 
	//Check timestamp toggle
	if ((strpos($input,"timestamp=false") !== false) || (strpos($input,"timestamp=off") !== false)) {
		$newsBulletins->changeTimestamp(false);
	}
 
	return $newsBulletins->showBulletins();
}
 
/**
 * newsBulletins class
 */
class newsBulletins {
	public $var_category;
	public $var_header;
	public $var_links;
	public $var_limit;
	public $var_order;
	public $var_timestamp;
	public $messages;
 
	/**
	 * newsBulletins
	 * @desc Creates a new newsBulletin.
	 */
	function newsBulletins() {
		$this->var_header = null;
		$this->var_links = true;
		$this->var_limit = 5;
		$this->var_order = "DESC";
		$this->var_timestamp = true;
		
		global $wgLanguageCode;
		if( $wgLanguageCode == 'fr' ){
			$this->messages = array(
				'noentriesfound'		=>		'Aucune actualité n\'est disponible actuellement.'
			);
			$this->var_category = "Actualités";
		} else {
			$this->messages = array(
				'noentriesfound'		=>		'No entries found at this time.'
			);
			$this->var_category = "Bulletins";
		}
	}
 
	/**
	 * changeCategory
	 * @desc Changes the category varialbe.
	 * @param String $newCategory The category to be set to.
	 */
	function changeCategory($newCategory) {
		$this->var_category = $newCategory;
	}
 
	/**
	 * changeHeader
	 * @desc Changes the header varialbe.
	 * @param String $newHeader The header to be set to.
	 */
	function changeHeader($newHeader) {
		$this->var_header = $newHeader;
	}
 
	/**
	 * changeLinks
	 * @desc Changes the links varialbe.
	 * @param boolean $newLinks True for use links, false to not.
	 */
	function changeLinks($newLinks) {
		$this->var_links = $newLinks;
	}
 
	/**
	 * changeLimit
	 * @desc Changes the limit varialbe.
	 * @param int $newLimit The number of entries to be displayed.
	 */
	function changeLimit($newLimit) {
		$this->var_limit = $newLimit;
	}
 
	/**
	 * changeOrder
	 * @desc Changes the order varialbe.
	 * @param String $newOrder ASC or DESC.
	 */
	function changeOrder($newOrder) {
		$this->var_order = $newOrder;
	}
 
	/**
	 * changeTimestamp
	 * @desc Changes the timestamp varialbe.
	 * @param boolean $newTimestamp True for use timestamp, false to not.
	 */
	function changeTimestamp($newTimestamp) {
		$this->var_timestamp = $newTimestamp;
	}
 
	/**
	 * getTitleConditions
	 * @desc Creates conditions for finding all pages that are a member of the target category.
	 * @param String $pageTable The table for pages within the wiki.
	 * @param String $categoryLinksTable The table for category links within the wiki.
	 * @return String MYSQL conditions for finding all pages under the given category.
	 */
	function getTitleConditions($pageTable,$categoryLinksTable) {
		$statement = 	"SELECT * " .
						"FROM " . $pageTable . ", " . $categoryLinksTable. " " .
						"WHERE ".$categoryLinksTable.".cl_to LIKE '" . $this->var_category . "' AND " . $pageTable.".page_is_redirect = 0 AND ".$pageTable.".page_id = ".$categoryLinksTable.".cl_from" . " " .
						"ORDER BY " . $categoryLinksTable . ".`cl_timestamp` " . $this->var_order . " " .
						"LIMIT " . $this->var_limit;
		return $statement;
 
	}
 
	/**
	 * showBulletins
	 * @desc Preforms operations to create the html for the newsBulletins block.
	 * @return String $output The html of a completed newsBulletins block.
	 */
	function showBulletins() {
		global $wgScript, $wgUser, $wgParser, $wgTitle, $wgOut, $wgLocalTZoffset, $namespaceNames;
 
		//Try to disable cache
 		$wgOut->enableClientCache(false);
 		wfPurgeSquidServers(array($wgTitle->getInternalURL()));
 		$wgTitle->invalidateCache();
 
		$sk =& $wgUser->getSkin();
		$i=0;
 
 		//Prep the db
    	$dbr =& wfGetDB( DB_SLAVE );
    	$pageTable = $dbr->tableName( 'page' );
    	$categoryLinksTable = $dbr->tableName( 'categorylinks' );
 
		//Finding all entries
		$conditions = $this->getTitleConditions($pageTable,$categoryLinksTable);
		$result = $dbr->query($conditions);
 
		$output = "<div class='news-bulletin'>";
 
		//Checking on header
		if (!empty($this->var_header)) {
			$output .= "<div class='news-bulletin-header'>" . $this->var_header . "</div>";
		}
 
		//For each page found...
		while ($row = $dbr->fetchObject($result) ) {
			//Getting and formatting title
			$title = Title::makeTitle($row->page_namespace, $row->page_title);
			$title_text = $title->getSubpageText();
			$title_text = str_replace('_',' ',$title_text);
 
			//Getting article content
			$article = new Article ( $title ) ;
    		$content = $article->getContent();
    		$content = preg_replace("/\[\[" . $namespaceNames['NS_CATEGORY'] . "\:\S+\]\]/","",$content);
			
			//Checking for <newstitle> tag for customized title
    		preg_match('/<newstitle>(\S|\s)+<\/newstitle>/',$content,$titleOn);
    		if ($titleOn[0]) {
    			$title_text = $titleOn[0];
				$content = preg_replace('/<newstitle>(\S|\s)+<\/newstitle>/',"",$content);
    		}
 
    		//Checking for <teaser> tag for teaser
    		preg_match('/<teaser>(\S|\s)+<\/teaser>/',$content,$teaserOn);
    		if ($teaserOn[0]) {
    			$content = $teaserOn[0];
    		}
 
			//Creating output
			if ($this->var_links===false) {
				$output .= "<div class='news-bulletin-title'>&raquo;&nbsp;" . $title_text . "</div>";
			}
			else {
				$output .= "<div class='news-bulletin-title'>&raquo;&nbsp;" . $sk->makeKnownLinkObj($title, $title_text) . "</div>";
			}
			$output .= "<div class='news-bulletin-text'>" . $content . "</div>";
			if ($this->var_timestamp!==false) {
				$output .= "<div class='news-bulletin-time'>" . date("j M Y — H:m",strtotime($row->cl_timestamp) + ($wgLocalTZoffset * 60)) . "</div>";
			}
			$output .= "\n\n";
			$i++;
	  	}
 
	  	//Special case of no pages found
	  	if ($i<1) {
	  		$output .= $this->messages['noentriesfound'];
	  	}
 
	  	$output .= "</div>";
 
      	return $output;
	}
}

Thanks[edit]

A special thanks to Barrylb and the Calendar extension, Extension:Calendar (Barrylb) , for inspiration and lots of coding help. This extension not possible without code from the calendar extension.

History[edit]

Version 1.1[edit]

  • Added a "<newstitle>" tag, allowing to display a custom title for a news item instead of the articlename.
  • Added the time zones improvements which were given in the talk page.
  • Added a "$messages" property to the "newsBulletins" class, which contains internationalization data. This adds the following features:
    • Translated versions of the "No entries found at this time!" message.
    • Local translations of the default category newsBulletins is relying on.
  • Modified the code so that translated versions of the "category" wiki tag could be correctly hidden.

Related Issues[edit]