Extension:Include

Description
This extension lets you include external static text content from the following sources:


 * local file system
 * a remote URL
 * SVN, using "svn cat"

If the external text is source code then it can be optionally colorized with syntax highlighting by specifying the highlight="SYNTAX" attribute. Where "SYNTAX" may be any of the following values: CPP, CSS, diff, DTD, HTML, Java, Javascript, MySQL, Perl, PHP, Python, Ruby, SQL, XML. (To colorize source code in internal text, see the Extension:SyntaxHighlight GeSHi).

By default the included text is automatically wrapped in a &lt;pre&gt;&lt;/pre&gt; tag block. This can be turned off if you want to include raw text or raw HTML by specifying the nopre attribute. You may want to combine this with the noesc attribute described below.

By default all HTML entities are escaped (for example &amp; becomes &amp;amp;). This can be turned off by specifying the noesc attribute.

You can use the wikitext attribute to treat the included text as WikiText. The included text will be passed to the MediaWiki parser to be turned into HTML. Thanks to Uli Knieper for this feature.

You can optionally add the svncat attribute which tells the extension to use "svn cat" to include the file from an SVN repository. In this case the "src" argument will be passed directly to SVN, so src="URL" may be any URL that SVN understands (file:///, svn+ssh://, webdav://, http:// ). This is very handy for documenting source code.

Note that syntax coloring requires the Pear Text_Highlighter module. The extension will still run without Text_Highlighter, but the highlight attribute will be disabled. If you try to use highlight without installing Text_Highlighter include will return an error message.

Installation
Put this script on your server in your MediaWiki extensions directory:

where $IP is the install path of your MediaWiki. Then add these lines to your LocalSettings.php:

Note that these settings allow any document under your DOCUMENT_ROOT to be shared except LocalSettings.php or any file ending in .conf. You can add other regex patterns for files that you want to disallow. You can also set $wg_include_allowed_parent_paths as an array of allowed paths. These parameter settings affect local and remote URLs -- not SVN URLs.

Example Usage in a wikipage
This would include plain text from the given src URL:



The previous example would be rendered in MediaWiki something like this:

Network Working Group                                    T. Berners-Lee Request for Comments: 1945                                      MIT/LCS Category: Informational                                     R. Fielding UC Irvine H. Frystyk MIT/LCS May 1996

Hypertext Transfer Protocol -- HTTP/1.0

Status of This Memo

This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. Distribution of  this memo is unlimited.

IESG Note:

The IESG has concerns about this protocol, and expects this document to be replaced relatively soon by a standards track document.

Abstract

The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and speed necessary for distributed, collaborative, hypermedia information systems. It is a generic, stateless, object-oriented protocol which can be used for many tasks, such as name servers and distributed object management systems, through extension of its request methods (commands). A feature of  HTTP is the typing of data representation, allowing systems to be   built independently of the data being transferred.

The following example includes the contents of a PHP script. The src points to a local file system path. This could be useful for documenting the script in a wiki. The advantage here is that you could include the script that is actually being used.



Better still, you could include the code that is checked into SVN by adding the svncat attribute and providing an URL to the file in the SVN repository:



Since we are including PHP source code for display we could also turn on syntax highlighting for PHP.



Download Source Code
The latest copy of the source code should be downloaded from here:
 * http://www.noah.org/wiki/MediaWiki_Include

The script from the above source will always be the latest copy. If that is not available you can copy the script from below: * *    For the latest version go here: *        http://www.noah.org/wiki/MediaWiki_Include * * ATTRIBUTES * *     The tag must always include at least have a 'src' attribute. * *     src="[URL]" *         You must include 'src' to specify the URL of the file to import. *         This may be the URL to a remote file or it may be a *          local file system path. * *     iframe *         This sets tells the extension to render the included file *         as an iframe. If the iframe attribute is included then the *         following attributes may also be included to determine how *         the iframe is rendered: * *             width *             height * *         Exampple: * *              * *     noesc *         By default will escape all HTML entities in *          the included text. You may turn this off by adding *         the 'noesc' attribute. It does not take any value. * *     nopre *         By default will add  tags around *         the included text. You may turn this off by adding *         the 'nopre' attribute. It does not take any value. * *     wikitext *         This treats the included text as Wikitext. The text is *         passed to the Mediawiki parser to be turned into HTML. * *     svncat *         This is used for including files from SVN repositories. *         This will tell include to use "svn cat" to read the file. *         The src URL is passed directly to svn, so it can be any *         URL that SVN understands. * *     linenums *         This will add line numbers to the beginning of each line *         of the inluded text file. * *     highlight="[SYNTAX]" *         You may colorize the text of any file that you import. *         The value of SYNTAX must be one of the following: * *             CPP *             CSS *             diff *             DTD *             HTML *             Java *             Javascript *             MySQL *             Perl *             PHP *             Python *             Ruby *             SQL *             XML * *     csshref="[URL]" *         If you set 'highlight' then by default it includes an inline CSS. *         You may override this and link to the style sheet of your choice. *         Set "URL" to point to the CSS you want to use. * * EXAMPLES * *     Include a file from the local file system: *          *     Include a remote file: *          *     Include a local fragment of HTML: *          *     Include a local file with syntax highlighting: *          * * DEPENDENCIES * *     For highlight support you will need to install PEAR Text_Highlighter. *     For example: *         pear install --alldeps *         http://download.pear.php.net/package/Text_Highlighter-0.6.9.tgz * * AUTHOR * *     Noah Spurrier  *     http://www.noah.org/wiki/MediaWiki_Include * * @package extensions * @version 8 * @copyright Copyright 2008 @author Noah Spurrier * @license public domain -- free of any licenses and restrictions * * $Id: include.php 256 2008-05-20 17:01:29Z noah $ * vi:ts=4:sw=4:expandtab:ft=php: */ // We want highlighting, but it isn't required, so set a flag to show if it's available or not. @include 'Text/Highlighter.php'; if (class_exists('Text_Highlighter')) {   $highlighter_package = True; } else {   $highlighter_package = False; } $wgExtensionFunctions[] = "wf_include"; $wgExtensionCredits['other'][] = array (   'name'        => 'include',    'version'     => '0.8',    'author'      => 'Noah Spurrier',    'url'         => 'http://mediawiki.org/wiki/Extension:include',    'description' => 'This lets you include static content from the local file system; a remote URL; or SVN.', ); function wf_include {   global $wgParser; $wgParser->setHook( "include", "render_include" ); } $inline_css=' .hl-default {color:Black;} .hl-code {color:Gray;} .hl-brackets {color:Olive;} .hl-comment {color:Orange;} .hl-quotes {color:Darkred;} .hl-string {color:Red;} .hl-identifier {color:Blue;} .hl-builtin {color:Teal;} .hl-reserved {color:Green;} .hl-inlinedoc {color:Blue;} .hl-var {color:Darkblue;} .hl-url {color:Blue;} .hl-special {color:Navy;} .hl-number {color:Maroon;} .hl-inlinetags {color:Blue;} .hl-main {background-color:White;} .hl-gutter {background-color:#999999; color:White} .hl-table {font-family:courier; font-size:12px; border:solid 1px Lightgrey;} '; /** * path_in_regex_disallowed_list * This returns true if the needle_path matches any regular expression in haystack_list. * This returns false if the needle_path does not match any regular expression in haystack_list. * This returns false if the haystack_list is not set or contains no elements. * * @param mixed $haystack_list * @param mixed $needle_path * @access public * @return boolean */ function path_in_regex_disallowed_list ($haystack_list, $needle_path) {   if ( ! isset($haystack_list) || count($haystack_list) == 0) {       return false; }   // polymorphism. Allow either a string or an Array of strings to be passed. if (is_string($haystack_list)) {       $haystack_list = Array($haystack_list); }   foreach ($haystack_list as $p) {       if (preg_match ($p, $needle_path)) {           return true; }   }    return false; } /** * path_in_allowed_list * This returns true if the given needle_path is a subdirectory of any directory listed in haystack_list. * * @param mixed $haystack_list * @param mixed $needle_path * @access public * @return boolean */ function path_in_allowed_list ($haystack_list, $needle_path) {   if ( ! isset($haystack_list) || count($haystack_list) == 0) {       return false; }   // polymorphism. Allow either a string or an Array of strings to be passed. if (is_string($haystack_list)) {       $haystack_list= Array($haystack_list); }   foreach ($haystack_list as $path) {       if (strstr($needle_path, $path)) {           return true; }   }    return false; } /** * render_include * * This is called automatically by the MediaWiki parser extension system. * This does the work of loading a file and returning the text content. * $argv is an associative array of arguments passed in the tag as * attributes. * * @param mixed $input unused * @param mixed $argv associative array * @param mixed $parser unused * @access public * @return string */ function render_include ( $input, $argv, &$parser ) {   global $inline_css, $highlighter_package; global $wg_include_allowed_parent_paths, $wg_include_disallowed_regex; $error_msg_prefix = "ERROR in ". basename(__FILE__); if ( ! isset($argv['src'])) return $error_msg_prefix. ": tag is missing 'src' attribute."; // You can add this to restrict contents to a given path or DOCUMENT_ROOT: //   if (is_file(realpath($argv['src'])) && strlen(strstr(realpath($argv['src']), realpath($_SERVER['DOCUMENT_ROOT']))) <= 0) //       return $error_msg_prefix. ": src to local path is not under DOCUMENT_ROOT."; // Or you could use this to disallow local files altogether: //   if (is_file(realpath($argv['src']))) //       return $error_msg_prefix. ": Local files are not allowed."; // You can use similar tricks to restrict the src url. // iframe option...   // Note that this does not check that the iframe src actually exists. // I also don't need to check against $wg_include_allowed_parent_paths or $wg_include_disallowed_regex // because the iframe content is loaded by the web browser and so security // is handled by whatever server is hosting the src file. if (isset($argv['iframe'])) {       if (isset($argv['width'])) $width = $argv['width']; else $width = '100%'; if (isset($argv['height'])) $height = $argv['height']; else $height = '100%'; $output = 'iframe '; return $output; }   // cat file from SVN repository... if (isset($argv['svncat'])) {       $cmd = "svn cat ". escapeshellarg($argv['src']); exec ($cmd, $output, $return_var); // If plain 'svn cat' fails then try again using 'svn cat // --config-dir=/tmp'. Plain 'svn cat' worked fine for months // then just stopped. // Adding --config-dir=/tmp is a hack that fixed it, but // I only want to use it if necessary. I wish I knew what // the root cause was. if ($return_var != 0) {           $cmd = "svn cat --config-dir=/tmp ". escapeshellarg($argv['src']); exec ($cmd, $output, $return_var); }       if ($return_var != 0) return $error_msg_prefix. ": could not read the given src URL using 'svn cat'.\ncmd: $cmd\nreturn code: $return_var\noutput: ". join("\n", $output); $output = join("\n", $output); }   else // load file from URL (may be a local or remote URL)... {       $src_path = realpath($argv['src']); if ( ! $src_path ) {           $src_path = $argv['src']; }       else {           if ( ! path_in_allowed_list ($wg_include_allowed_parent_paths, $src_path)) {               return $error_msg_prefix. ": src_path is not a child of any path in \$wg_include_allowed_parent_paths."; }           if ( path_in_regex_disallowed_list ($wg_include_disallowed_regex, $src_path) ) {               return $error_msg_prefix. ": src_path matches a pattern in \$wg_include_disallowed_regex."; }       }        $output=file_get_contents($argv['src']); if ($output === False) return $error_msg_prefix. ": could not read the given src URL."; }   // FIXME line numbers should be added after highlighting. if (isset($argv['linenums'])) {       $output_a = split("\n",$output); for ($index = 0; $index < count($output_a); ++$index) $output_a[$index] = sprintf("%04d",1+$index).":".$output_a[$index]; $output = join("\n", $output_a); }   if (isset($argv['highlight']) && $highlighter_package===True) { //       if ($highlighter_package === False) //       { //            return $error_msg_prefix. ": Text_Highlighter is not installed. You can't use 'highlight'."; //       }        $hl =& Text_Highlighter::factory($argv['highlight']); $output = $hl->highlight($output); if (isset($argv['csshref'])) {           $output = ''. "\n". $output; }       else {           $output = $inline_css. $output; }       return $output; }   if ( ! isset($argv['noesc'])) $output = htmlentities( $output ); if (isset($argv['wikitext'])) {       $parsedText = $parser->parse($output,                      $parser->mTitle,                      $parser->mOptions,                      false,                      false); $output = $parsedText->getText; }   else {       if ( ! isset($argv['nopre'])) $output = " ". $output. " ";   }    return $output; } ?>