Extension:Include

MediaWiki extensions manual - list

include Release status: stable
Implementation	Tag
Description	Include external static content from the local file system, a remote URL, or SVN. External content can be included or embedded as an iframe.
Author(s)	Matthieu Moy (MatthieuMoyTalk)
Last version	9 (07-02-2011)
MediaWiki	1.5+
Database changes	no
License	public domain -- free of any licenses and restrictions
Download	see below
Parameters $wg_include_allowed_parent_paths, $wg_include_disallowed_regex
Hooks used Parser
Check usage (experimental)

This extension lets a wiki include external static text content from the following sources:

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

Options

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 values supported by GeSHi (see for example Extension:SyntaxHighlight_GeSHi#Supported_languages for a list). To colorize source code in internal text (i.e. not using remote inclusion), see the Extension:SyntaxHighlight GeSHi.

By default the included text is automatically wrapped in a <pre></pre> 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 & becomes &amp;). This can be turned off by specifying the noesc attribute (warning this can lead to XSS attacks. Use only if you trust all the potential contributors of your wiki, and in no case on a wiki where anonymous contributions are allowed)

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 <include> 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

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

Put the script secure-include.php - it is a single file - into your extensions directory root:

$IP/extensions/secure-include.php

Then add these examplary lines to your LocalSettings.php:

require_once("$IP/extensions/secure-include.php");                                                                                                                       
 
# Including local paths requires to uncomment the following line
# $wg_include_allowed_features['local'] = true;
$wg_include_allowed_parent_paths = $_SERVER['DOCUMENT_ROOT'];
$wg_include_disallowed_regex = array('/.*LocalSettings.php/', '/.*\.conf/', '/.*\/\.ht/');
 
# Including remote URLs requires to uncomment the following line
# $wg_include_allowed_features['remote'] = true;
$wg_include_allowed_url_regexp = array('/^http:\/\/.*$/');
$wg_include_disallowed_url_regexp = array('/^.*:\/\/intranet/');
 
$wg_include_allowed_features['highlight'] = true;

Warning:

These examplary settings allow any document under your DOCUMENT_ROOT to be shared, except LocalSettings.php and 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, but not SVN URLs:

$wg_include_allowed_parent_paths = array($_SERVER['DOCUMENT_ROOT'], '/home');

Most features are dactivated by default to minimize the security risk. Features must be activated using $wg_include_allowed_features. See the comments at the top of the source file for details.

Example Usage in a wikipage

A real example can be found here.

To illustrate the concept, the following line would include plain text from the given src URL:

<include src="http://www.ietf.org/rfc/rfc1945" />

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.

<include src="/var/www/htdocs/wiki/extensions/include.php"/> 

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:

<include svncat src="file:///home/svn/src/mediawiki/extensions/include.php" />

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

<include src="/var/www/htdocs/wiki/extensions/include.php" highlight="php" /> 

Download Source Code

The latest copy of the source code should be downloaded from here:

http://gitorious.org/include/include/trees/master

The script itself should be directly available here:

http://gitorious.org/include/include/blobs/raw/master/secure-include.php

See also

• Extension:IncludeArticle
• Extension:C_Style_Wiki_Includes
• Extension:SecureHTML, Extension:Secure HTML, or Extension:Secured HTML. With Iframe html coding, these extensions allows a page to have dynamic external pages embedded in any wiki page.