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. (example: )

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

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:

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

Usage
Usage syntax takes the form:



Where ATTRIBUTE1, ATTRIBUTE2, etc are optional. The following subsections describe the available attributes.

src="[URL]" (needs 'local' and/or 'remote' feature)
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.

WARNING: Chose carefully which features to activate. Allowing users to include local files may give them access to files you should have kept secret (like .htpasswd files).

If you allow remote inclusion, the remote page will be fetched by the web server hosting the wiki, which may be allowed to access private pages (like intranet).

iframe (needs 'iframe' feature)
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

Example:



noesc (needs 'noesc' feature)
WARNING: activating this feature exposes you to cross-site scripting attacks from anyone having write access to your wiki. Do not activate this unless you fully understand the consequences and trust all your contributors.

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 (needs 'wikitext' feature)
This treats the included text as Wikitext. The text is passed to the Mediawiki parser to be turned into HTML.

svncat (needs 'svncat' feature)
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.

lines="range"
Select a line range from the file to include. The range can be of the form:
 * an integer ("42") : select this line
 * a comma-separated list of integers ("1, 3, 5") : select these lines.
 * a (comma-separated list of) ranges separated by a hyphen like "X-Y" : select lines between X and Y (included). If X and/or Y is omitted, consider the beginning/end of the file.

from="[STRING]", to="[STRING]", before="[STRING]", after="[STRING]"
Select a range of lines to include according to the content of the file. For example, to include the file starting from the line whose content is FOO and stopping at the line whose content is BAR, one can say



When using from= and to=, the matched lines are included in the output. before= and after= are similar except that the matched lines are excluded from the output. All of these attribute can take either a string, in which case the value is the complete content of the line, or a regexp (including delimiters, like /foo.*bar/), in which case the regexp is matched against the line content.

highlight="[SYNTAX]" (needs 'highlight' feature)
You may colorize the text of any file that you import. The value of SYNTAX must be any one managed by GeSHI. When highlight is activated, the following attributes are available :

of the inluded text file.
 * linenums: This will add line numbers to the beginning of each line
 * linestart="N": In conjunction with linenums, start numbering lines from line M instead of counting from 1.
 * select="range": Highlight lines selected by range. Range take the same syntax as the lines attribute above. Requires "highlight" to be selected. Corresponds to GeSHI's highlight_lines_extra.
 * style="css style": Style of the container (   or    ) for the code. For example, use style="border: 0px none white;" to disable the frame around the code. Corresponds to GeSHI's set_overall_style.

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.



Umlaute
If the source to be included contains non-standard characters such as umlaute, the option "wikitext" must be used. Otherwise the function returns a white screen only.

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