Extension:Random

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Random

Release status: beta

Implementation Tag, Parser function
Description Randomly picks one or more items.
Author(s) darklamatalk
Latest version 0.3
License GPL, CC-BY-SA
Download This page
Tags
<random>
Hooks used
LanguageGetMagic

ParserFirstCallInit

Translate the Random extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

What is it?[edit | edit source]

Random is designed to return one or more items parsed as wikitext in a randomly shuffled order. A random shuffle prevents an item from being displayed twice by the same call to random, unless two or more items contain exactly the same contents.

Semi-random numbers can be generated without an extension like this, using magic words and ParserFunctions - see w:Template:Random number for an example.

For information about the unrelated native feature Special:Random, see Help:Random page.

Install[edit | edit source]

  1. Create a new folder/directory inside your mediawiki's extensions folder/directory named "Random".
  2. Create a new file named "Random.php" inside the "Random" folder/directory from step one.
  3. Copy the code to the new "Random.php" file from step two, and save the file.
  4. Add require_once("$IP/extensions/Random/Random.php"); to your LocalSettings.php

Examples[edit | edit source]

tag parser function what happens?
<random count="2">
<item>one</item>
<item>two</item>
<item>three</item>
</random>
{{#random:2
| one
| two
| three
}}
The result is that "onetwo", "onethree", "twoone", "twothree", "threeone", or "threetwo" is returned at random.
<random>
<item>[[one]]</item>
<item>[[two]]</item>
<item>[[three]]</item>
</random>
{{#random:1
| [[one]]
| [[two]]
| [[three]]
}}
The result is that "one", "two", or "three" is returned at random as a link. You can use any wiki mark up that could normally be used.
<random>
<format>[[%ITEM%]]</format>
<item>one</item>
<item>two</item>
<item>three</item>
</random>
not available The result is one, two, or three is returned at random as a link. The format tag provides an easy way to repeat any desired formatting. %ITEM% refers to the content of a picked item, and must be present at least once in a format tag. Using this method, for example, an image (with external link and caption) could be used as an item: <item>File:example.jpg|link=http://wikipedia.org/wiki/Test|caption</item>.
<random>
<format>[[%ITEM%]]</format>
<item>one</item>
<item>two</item>
<item>three</item>
<format>* %ITEM%</format>
<item>one</item>
<item>two</item>
<item>three</item>
</random>
not available The result is one, two, or three is returned at random either as a link or as a unsorted list. More than one format tag can be used to change the formatting of items following it.

Incorporating into a Template[edit | edit source]

If desired, the <random></random> tag (including the enclosed list of items) can be placed in a template (e.g. Template:MyRandomWikiItems ) and then just the corresponding template tag (e.g. {{MyRandomWikiItems}} ) could be placed within a wiki page. (It is then highly recommended that a wiki administrator "protect" such a template if it is not meant to be changed by casual wiki users.)

Code[edit | edit source]

<?php
 
/**
 * @package MediaWiki
 * @subpackage Extensions
 * @author darklama
 * @license http://www.gnu.org/licenses/gpl.html
 * @licence http://creativecommons.org/licenses/by-sa/3.1
 */
 
if ( !defined( 'MEDIAWIKI' ) ) {
  echo( "This is a mediaWiki extension and cannot be run standalone.\n" );
  die( -1 );
}
 
$wgHooks['LanguageGetMagic'][] = 'efRandomLanguageGetMagic';
$wgHooks['ParserFirstCallInit'][] = 'efRandomExtension';
$wgExtensionCredits['other'][] = array(
  'name'        => 'Random' ,
  'version'     => '0.3',
  'description' => 'Includes a random line of wikitext from given items',
  'author'      => '[https://en.wikiversity.org/wiki/User:Darklama darklama]',
  'url'         => 'https://www.mediawiki.org/wiki/Extension:Random',
);
 
function efRandomLanguageGetMagic( $magicWords, $langCode ) {
  $magicWords['random'] = array( 0, 'random' );
  return true;
}
 
function efRandomExtension( $parser ) {
  $parser->setHook( 'random', 'renderRandom' );
  $parser->setFunctionHook( 'random', 'randomObj', SFH_OBJECT_ARGS );
  return true;
}
 
function renderRandom( $input, $argv, $parser ) {
  $count = intval( $argv['count'] );
  $result = '';
  $format = '%ITEM%';
  $items = array();
  $elements = array( 'item', 'format' );
 
  $text = Parser::extractTagsAndParams( $elements, $input, $matches );
 
  foreach ( $matches as $marker => $data ) {
    list( $element, $content, $params, $tag ) = $data;
    if ( $element === 'item' ) {
      $content = trim( $content, " \t" );
      $content = trim( $content, "\n" );
      $items[] = str_replace( '%ITEM%', $content, $format );
    } else if ( $element === 'format' ) {
      if ( !empty( $content ) && preg_match( '/%ITEM%/', $content ) != 0 ) {
        $format = str_replace( '«', '<', $content );
        $format = str_replace( '»', '>', $format );
        $format = trim( $format, " \t" );
        $format = trim( $format, "\n" );
        $format = str_replace( '\n', "\n", $format );
      }
    }
  }
 
  $entries = count( $items );
  if ( $entries == 0) {
    return '';
  }
  if ( $count <= 0 ) {
    $count = 1;
  } else if ( $count > $entries ) {
    $count = $entries;
  }
 
  $keys = array_rand( $items, $count );
 
  if ( is_array( $keys ) ) {
    foreach ( $keys as $key ) {
      $result .= $parser->recursiveTagParse( $items[$key] );
    }
  } else {
    $result = $parser->recursiveTagParse( $items[$keys] );
  }
 
  $parser->disableCache();
  return $result;
}
 
function randomObj( $parser, $frame, $args ) {
  $count = isset($args[0]) ? intval(trim( $frame->expand( $args[0] ) ) ) : 1;
  $entries = count($args);
  $result = '';
 
  if ( $entries <= 0 ) {
    return '';
  } else if ( $entries == 1 ) {
    return trim( $frame->expand( $args[0] ) );
  } else if ( $count > ($entries-1) ) {
    $count = $entries-1;
  } else if ( $count <= 0 ) {
    $count = 1;
  }
 
  unset($args[0]);
  $keys = array_rand( $args, $count );
 
  if ( is_array( $keys ) ) {
    foreach ( $keys as $key ) {
      $result .= ltrim( $frame->expand( $args[$key] ) );
    }
  } else {
    $result = ltrim( $frame->expand( $args[$keys] ) );
  }
 
  $parser->disableCache();
  return rtrim( $result );
}

Alternatives[edit | edit source]

See also[edit | edit source]