Extension:Include

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
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)
Latest version 9 (2011-02-07)
MediaWiki 1.5+
Database changes no
License Public domain
Download see below
Parameters

$wg_include_allowed_parent_paths, $wg_include_disallowed_regex

Hooks used
Parser

Translate the Include extension if possible

Check usage and version matrix; code metrics

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

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

Installation[edit | edit source]

$IP stands for the Installation Path (or "directory") of your MediaWiki installation, the same directory that holds LocalSettings.php, index.php etc..

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 Warning: These example 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 deactivated 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.

Usage[edit | edit source]

Usage syntax takes the form:

<include ATTRIBUTE1="..."  ATTRIBUTE2="..." src="[URL]" />

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

src="[URL]" (needs 'local' and/or 'remote' feature)[edit | edit source]

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)[edit | edit source]

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
  • frameborder
  • scrolling

Example:

<include iframe src="http://www.noah.org/cgi-bin/pr0n" width="" height="1000px" frameborder="0" scrolling="no" />

noesc (needs 'noesc' feature)[edit | edit source]

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 <include> 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[edit | edit source]

By default <include> 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)[edit | edit source]

This treats the included text as Wikitext. The text is passed to the Mediawiki parser to be turned into HTML.

svncat (needs 'svncat' feature)[edit | edit source]

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"[edit | edit source]

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]"[edit | edit source]

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

<include from="FOO" to="BAR" src="..." />

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)[edit | edit source]

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 :

  • linenums: This will add line numbers to the beginning of each line

of the inluded text file.

  • 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 (<div> or <pre>) 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[edit | edit source]

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

Options[edit | edit source]

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

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.

FAQ[edit | edit source]

Umlaute[edit | edit source]

If the source to be included contains non-standard characters such as umlaute, the option "wikitext" must be used (<include wikitext src="...">). Otherwise the function returns a white screen only.

Download Source Code[edit | edit source]

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[edit | edit source]