Extension:Include

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 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 &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 (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 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 for example 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.

Most features are desactivated by default to minimize the security risk. Features must be activated using. 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:



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://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